You’re doing dark mode wrong.

Most theme toggles have two states: light and dark. Neither means what many users actually want — “just match my device.”

How that plays out over one evening:

1. 19:42

   Sunset. Their OS fades to dark — macOS Auto, iOS Automatic, Android’s schedule, Windows via Auto Dark Mode. Every app follows.

2. 19:42

   Your site: still #FFFFFF. Now the brightest thing on the screen.

3. 19:43

   They click your toggle. localStorage.theme = "dark". The page goes dark — and that value now overrides the system on every future visit.

4. 07:06

   Sunrise. The OS returns to light. Every app follows — except your site, pinned by a value written ten hours ago. It will now disagree with the device twice a day.

5. ∞

   No way back to automatic. The toggle still switches between light and dark, but “follow my system” is gone — the UI has no state for it. Staying in sync is now manual work; the only reset is clearing site data, a step few would connect to a theme.

The code usually looks like this:

// ❌ the two-state toggle, with its three bugs annotated

const theme = localStorage.getItem('theme') || 'light';
// BUG 1 — defaults to 'light' for every first-time visitor.
// The system preference is available, but never consulted.

document.documentElement.dataset.theme = theme;
// …and because the attribute is ALWAYS set, the CSS
// prefers-color-scheme media query can never apply. Auto is unreachable.

toggle.addEventListener('click', () => {
  const next = html.dataset.theme === 'dark' ? 'light' : 'dark';
  localStorage.setItem('theme', next);
  // BUG 2 — stored permanently after the first click. There is no
  // third state, so there is no way to hand control back.
  html.dataset.theme = next;
});

// BUG 3 — nowhere in this file:
//   matchMedia('(prefers-color-scheme: dark)')
// When the OS switches at sunset, this page won’t follow.

1. The user already answered.

   Every browser exposes the device’s appearance via prefers-color-scheme — Baseline since 2020. The preference is on record before the user arrives; a toggle that defaults to light simply ignores it.

2. Operating systems follow the sun. A stored toggle can’t.

   macOS has Auto, iOS has Automatic with a schedule, Android can switch on a schedule or with Battery Saver, and Windows does it via PowerToys or Auto Dark Mode. Appearance changes mid-session — and a stored binary value can never follow.

3. One click disconnects the site permanently.

   Try the other theme once, and the choice is stored for good. As Bramus Van Damme puts it, such sites “will never be able to respond to the system preference again, as they always have an override applied.”

4. It’s an accessibility signal, not a vibe.

   Photophobia and migraines push some users to dark; astigmatism halation pushes others to light; NN/g’s research review found no default that suits everyone. That’s why the OS lets each user pick — and why overriding the signal is the same class of bug as ignoring prefers-reduced-motion.

5. Everything else on the device already behaves this way.

   Native apps follow the system. The OS settings panel is a tri-state — so are Stack Overflow’s and GitHub’s theme controls. When a site doesn’t follow, the mismatch reads as a bug in the site, not in the settings.

6. The fix costs one enum value and one event listener.

   Both versions need two themes in CSS, a stored preference, a control, and a head script against theme flash. The difference is treating “nothing stored” as a state and listening for system changes — a few lines.

The model: light and dark are stored overrides; auto means nothing is stored. Once “no stored value” means “follow the system,” the rest falls into place.

Auto isn’t a third theme — it’s the absence of an override.

Step one — the head. Declare scheme support before any CSS, and apply a stored override synchronously, before first paint. The script must be inline and blocking — external files, defer, async and modules all run too late and flash the wrong theme.

<meta name="color-scheme" content="light dark">
<meta name="theme-color" content="#f4f5f7" media="(prefers-color-scheme: light)">
<meta name="theme-color" content="#0a0b0d" media="(prefers-color-scheme: dark)">

<!-- inline + blocking, BEFORE the stylesheet -->
<script>
  try {
    const t = localStorage.getItem('theme');
    if (t === 'light' || t === 'dark')
      document.documentElement.dataset.theme = t;
    // no stored key? do nothing — CSS handles auto by itself
  } catch (e) {}
</script>

<link rel="stylesheet" href="/styles.css">

Step two — the CSS. Three lines plus your colors. color-scheme opts you into both schemes — form controls, scrollbars and the default canvas match the OS for free. light-dark() picks every color’s side automatically; an override is just color-scheme narrowed to one value.

/* 1 · support both schemes; auto now works with zero JS */
:root { color-scheme: light dark; }

/* 2 · an explicit choice just narrows the scheme */
:root[data-theme="light"] { color-scheme: light; }
:root[data-theme="dark"]  { color-scheme: dark; }

/* 3 · every color picks its own side — no duplicated palettes,
       no media queries, correct in all three states */
body {
  background: light-dark(#f4f5f7, #0a0b0d);
  color:      light-dark(#0d0f13, #eef1f5);
}

light-dark() is Baseline 2024 (Chrome 123, Edge 123, Firefox 120, Safari 17.5). For older browsers, same model in classic syntax: tokens in :root, overridden in @media (prefers-color-scheme: dark) guarded by :root:not([data-theme]), then re-asserted under each [data-theme]. (This page ships that fallback — view source.)

Step three — the control and the logic. Radio buttons give you keyboard support and screen-reader semantics for free. The logic enforces one invariant: storage holds overrides only.

<fieldset>
  <legend>Theme</legend>
  <label><input type="radio" name="theme" value="light"> Light</label>
  <label><input type="radio" name="theme" value="auto" checked> Auto</label>
  <label><input type="radio" name="theme" value="dark"> Dark</label>
</fieldset>

const mql = matchMedia('(prefers-color-scheme: dark)');

function setTheme(choice) {           // 'light' | 'dark' | 'auto'
  if (choice === 'auto') {
    localStorage.removeItem('theme'); // absence IS the auto state
    delete document.documentElement.dataset.theme;
  } else {
    localStorage.setItem('theme', choice);
    document.documentElement.dataset.theme = choice;
  }
  syncThemeColor();                   // see the fine print below
}

document.querySelectorAll('input[name="theme"]').forEach((input) => {
  input.addEventListener('change', () => setTheme(input.value));
});

// In auto mode, CSS already follows OS changes live — this listener
// is for everything CSS can't reach: canvas charts, maps, embeds,
// and <meta name="theme-color">.
mql.addEventListener('change', () => {
  if (!localStorage.getItem('theme')) syncThemeColor();
});

The fine print — two gotchas that survive even good implementations. First: <meta name="theme-color"> media attributes track the OS only, never your data-theme attribute — while overridden, rewrite the metas from JS. Second: if you animate the swap, gate it behind matchMedia('(prefers-reduced-motion: reduce)') in the JS, not just CSS.

objections, anticipated

This page runs exactly the code above — view source; it’s one file. With the header toggle on Auto, change your OS appearance and watch the page follow, no reload:

The page’s actual internals, updated live:

Audit your own site against these. (Ticking the boxes stores nothing — this page only writes to storage when you override the theme.)

• The control has three states: Light, Dark, and Auto. A checkbox cannot represent “follow my system.” Radios or a select can.
• Auto is the default for every first-time visitor. First paint honors prefers-color-scheme — no flash of your favorite theme.
• Storage holds overrides only — no key means Auto. removeItem on Auto, never setItem('auto'). Absence is the state.
• A matchMedia change listener keeps JS-rendered things in sync. Charts, maps, embeds and meta theme-color don’t read CSS variables on their own.
• An inline, blocking head script applies the override before first paint. Inline, above the stylesheet. defer/async/module all flash.
• color-scheme is declared in both the meta tag and the CSS. Scrollbars, form controls and the pre-CSS canvas follow the scheme for free.
• meta theme-color gets rewritten from JS while overridden. Its media attribute tracks the OS, not your data-theme attribute.
• The theme swap respects prefers-reduced-motion. Checked in JS before any view transition — not just in CSS.