Buy detergent due today
Tap a task to mark it done
```
Read the names, not the values. `--surface` is "a card", whatever shade a card is today. `--ink` is "borders". The dark block redefines the same names, and every rule that reads them changes with it. Not one rule was copied. Notice two things the naive swap got wrong:
- **The muted grey is lifted, not inverted.** `#6B7280` on white passes the 4.5:1 contrast rule for body text; its mirror image on navy would not. The dark value is chosen by measuring, not by arithmetic.
- **The accent is not redefined at all.** A red button stays the same red in both themes; only its surroundings move. Deciding which tokens change and which stay is most of the design work.
> NOTE
>
> `color-scheme` is a one-line bonus: it tells the browser which theme the page is, so scrollbars, form controls and the default focus ring match without any rules of yours.
## One attribute switches everything
With tokens in place, switching the theme means changing one attribute on the root element. The rules do not know it happened; they just read different values the next time the browser computes styles.
apply.js
```ts
const root = document.documentElement;
function colours() {
const body = getComputedStyle(document.body).backgroundColor;
const card = getComputedStyle(document.getElementById("card")).backgroundColor;
const due = getComputedStyle(document.getElementById("due")).color;
return `${body} | card ${card} | due ${due}`;
}
root.setAttribute("data-theme", "light");
console.log("light:", colours());
root.setAttribute("data-theme", "dark");
console.log("dark: ", colours());
root.removeAttribute("data-theme");
```
What the browser terminal prints
```ts
light: rgb(250, 250, 249) | card rgb(255, 255, 255) | due rgb(192, 57, 43)
dark: rgb(15, 15, 26) | card rgb(22, 33, 62) | due rgb(192, 57, 43)
```
The page, the card and the words all moved with one line, and the due date stayed red in both, because its token was not redefined. This is the whole mechanism. Everything that follows is about deciding *which* value to put in that attribute, and *when*.
## A preference is not what is on screen
Ada's toggle had two states, on and off. Complaint four shows why two is not enough: some people want the page to follow the operating system, which is a third state. So there are two separate things:
- The **preference**: what the visitor asked for. `"light"`, `"dark"`, or `"system"` (follow the OS).
- The **resolved theme**: what is actually on screen right now, which is only ever `"light"` or `"dark"`.
Turning one into the other is a pure function, so write it as one and test it without a browser:
resolve.js
```ts
function resolveTheme(preference, osPrefersDark) {
if (preference === "dark") return "dark";
if (preference === "light") return "light";
return osPrefersDark ? "dark" : "light";
}
const cases = [
["system", false],
["system", true],
["light", true],
["dark", false],
[null, true],
["banana", false],
];
for (const [preference, osDark] of cases) {
console.log(String(preference).padEnd(7), "os dark:", String(osDark).padEnd(5), "→", resolveTheme(preference, osDark));
}
```
Output of `node resolve.js` and of the browser terminal
```ts
system os dark: false → light
system os dark: true → dark
light os dark: true → light
dark os dark: false → dark
null os dark: true → dark
banana os dark: false → light
```
Anything that is not exactly `"dark"` or `"light"`, including a missing value and a typo, means "follow the OS". That is the safe default: a corrupted stored value can never trap someone in a theme they did not choose.
The OS setting itself comes from a media query. The same `prefers-color-scheme` that CSS can test in an `@media` block is available to JavaScript through `window.matchMedia`, which returns an object whose `matches` is true or false right now, and which fires a `change` event when the answer changes.
## Remembering safely
The preference has to survive a reload, so it goes in `localStorage`, which [Browser APIs](https://zudojs.oyinlola.site/learn/browser-apis) covered. Two rules from that lesson matter here. Storage can throw, in a private window or when the visitor has blocked site data, and a theme switch must never crash a page over that. And store only what was chosen: "system" is the *absence* of a stored value, so a visitor who never touches the toggle keeps following their OS forever, and clearing the value is how you go back to it.
safe-pref.js
```ts
const KEY = "academy-demo:theme";
function readPreference(storage) {
try {
const value = storage.getItem(KEY);
return value === "light" || value === "dark" ? value : "system";
} catch {
return "system";
}
}
function writePreference(storage, preference) {
try {
if (preference === "light" || preference === "dark") storage.setItem(KEY, preference);
else storage.removeItem(KEY);
return true;
} catch {
return false;
}
}
// A fake storage: the same interface, so the functions cannot tell the difference.
function fakeStorage({ broken = false } = {}) {
const data = new Map();
const fail = () => { throw new Error("storage is disabled"); };
return {
getItem: (k) => (broken ? fail() : (data.has(k) ? data.get(k) : null)),
setItem: (k, v) => (broken ? fail() : void data.set(k, String(v))),
removeItem: (k) => (broken ? fail() : void data.delete(k)),
};
}
const ok = fakeStorage();
console.log("fresh:", readPreference(ok));
console.log("write dark:", writePreference(ok, "dark"), "→", readPreference(ok));
console.log("write system:", writePreference(ok, "system"), "→", readPreference(ok));
ok.setItem(KEY, "banana");
console.log("garbage:", readPreference(ok));
const blocked = fakeStorage({ broken: true });
console.log("blocked read:", readPreference(blocked));
console.log("blocked write:", writePreference(blocked, "dark"));
```
Output of `node safe-pref.js` and of the browser terminal
```ts
fresh: system
write dark: true → dark
write system: true → system
garbage: system
blocked read: system
blocked write: false
```
Both helpers turn every failure into a value the caller can live with: a preference of "system", or `false` from a write. The page still switches theme for the rest of the visit; it just will not be remembered, which is the right amount of failure.
## Stopping the flash
Now complaint one, the white flash. Follow what the browser does with Ada's page. It reads the HTML from the top. When it meets a stylesheet it fetches it, and it will not paint until the CSS has arrived, so the first paint already has the right rules. But the theme attribute is set by JavaScript, and her script is at the bottom of the page with `defer`, so it runs after that first paint. For a moment the page is painted with the default (light) tokens; then the script runs, the attribute appears, and everything repaints. That moment is the flash.
The fix is to set the attribute *before* the first paint, which means before the stylesheet: a small inline script in ``, above the `