Theme toggle

THE GLYPH FOLLOWS THE PAGE, NOT THE BUTTON

Each theme declares --ds-theme-is-light — 0 for a dark one, 1 for a light one — and the sun and moon cross-fade on it. So they change because the theme changed, not because a class was toggled. A face driven by the button's own state lies exactly when it matters: a page served light with a control that has not been told yet.

aria-pressed says the same thing to a reader who cannot see it, and it is read back off data-theme rather than set alongside it. That is what lets a page carry two of these — a header and a footer — without them disagreeing.

FOUR LINES IN THE HEAD, OR ONE FRAME OF THE WRONG PAGE

Alpine boots after the document is parsed, so the stored theme arrives a frame after the first paint unless the document applies it itself. This book runs exactly this, which is why switching to paper and following a link does not flash.

<!-- in <head>, before the first paint -->
<script>
  try {
    const t = localStorage.getItem('ds-theme');
    if (t) document.documentElement.dataset.theme = t;
  } catch {}
</script>

try is not defensive padding: storage throws on access where it is denied — a private window, third-party cookies blocked — and an uncaught exception in a head script stops the rest of the head.

It is not required. Leave it out and the switch still works, still remembers, and still restores on the next page; the reader sees one frame of the default theme first. The directive reads the document rather than storage on boot, so the two can never argue.

TWO THEMES, NAMED DARK FIRST

With no value it switches between portfolio-dark and portfolio-light. A consumer with its own pair names them, and the order is the contract — the dark one first, because a pair written the other way round would silently invert every reader's choice.

<!-- a consumer with its own pair names them, dark first -->
<button class="theme-toggle" type="button" data-ds-pending
        aria-pressed="false" aria-label="Light theme"
        x-ds-theme="acme-night acme-day"></button>

WHY NOT hidden

It is the obvious attribute for "not relevant yet", and it is the wrong one here. The UA stylesheet spells it display: none !important — measured, not assumed: an inline display: grid on a hidden element still computes to none. So it does not merely withhold the control, it takes the box away with it, and the switch arriving a frame later shoves everything beside it sideways.

<!-- what does NOT work, and it is the obvious first try -->
<button class="theme-toggle" hidden …></button>

/* the UA sheet, measured in Chromium: */
[hidden] { display: none !important; }

The attribute is on the markup rather than absent from it, too: [data-ds-pending] adds the waiting, where a :not([data-ds-ready]) would make it the base state. A component's base class is the ordinary case and a modifier adds — the same rule that says the name is is-disabled and never is-enabled.