frontend-theming-dark-light-mode

name	frontend-theming-dark-light-mode
description	Use when adding dark mode to a website or app, choosing between system-followed-only and user-toggle modes, eliminating duplicated `@media (prefers-color-scheme: dark) { ... }` rules with `light-dark()`, fixing a white flash on reload (FOUC), getting scrollbars and native form controls (`<input type="checkbox">`, `<input type="date">`, `<select>`) to render in dark theme, persisting a user theme choice across reloads, or building a three-state toggle (system / light / dark). Use when reviewing a dark mode that already exists and assessing whether it covers all the cases below. Prevents the six dominant dark-mode failures : using `light-dark()` without declaring `color-scheme: light dark` on `:root` (always returns the light value), forgetting `color-scheme` entirely so the page background goes dark but scrollbars and checkboxes stay light, applying the theme via `useEffect` AFTER first paint causing a white flash on every reload, duplicating every rule in `@media (prefers-color-scheme: dark)` instead of using `light-dark()`, missing `aria-pressed` on the toggle button, and forcing dark mode for all users regardless of system preference. Covers the `color-scheme` property (values : `normal`, `light`, `dark`, `light dark`, `only light`, `only dark` and its purpose : it informs the user agent which color schemes the page supports so the UA can theme its own UI : scrollbars, form controls, spellcheck underlines, canvas surface), the `<meta name= "color-scheme">` tag, the `light-dark(<light>, <dark>)` function (Baseline 2024, requires `color-scheme` to function), the `@media (prefers-color-scheme: dark | light)` media query and its default `light` value when the user has no preference, the `<picture>` element with `<source media="(prefers-color-scheme: dark)">` for theme-specific images, the `data-theme` attribute override pattern, localStorage persistence, the head-script pattern for FOUC prevention (read storage, set attribute BEFORE CSS executes), and the three-state toggle architecture (system / light / dark with explicit user choice tracked separately from system preference). Keywords: color-scheme, light-dark, light-dark function, prefers-color-scheme, dark mode, light mode, system theme, theme toggle, data-theme, FOUC, flash of unstyled, no flash, localStorage theme, meta color-scheme, only light, only dark, Auto Dark Theme, picture prefers-color-scheme, theme persistence, three-state toggle, system default, manual override, matchMedia prefers-color-scheme, dark mode broken, scrollbar wrong color, scrollbar still light, form controls wrong color, checkbox light in dark mode, date picker light in dark mode, theme not persisting, white flash on reload, theme flashes on load, how to add dark mode, how to do dark mode in CSS, why does dark mode flash, how to remember theme choice, how to follow system dark mode, how to make dark mode toggle, is light-dark CSS supported.
license	MIT
compatibility	Designed for Claude Code. Requires Frontend Design evergreen-2026.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

Frontend Theming : Dark and Light Mode

Authoritative reference for evergreen-2026 dark / light theming. The four primitives : color-scheme (declares what the page supports), light-dark() (per-property branch), @media (prefers-color-scheme: dark | light) (rules-block branch), and <picture><source media="(prefers-color-scheme: dark)"> (image branch).

Quick Reference

Baseline status

Feature	Baseline	Source
color-scheme	Widely Available since January 2022	MDN : color-scheme (verified 2026-05-19)
prefers-color-scheme	Widely Available since January 2020	MDN : prefers-color-scheme (verified 2026-05-19)
light-dark()	Newly Available since May 2024; becoming Widely Available in 2026	MDN : light-dark() (verified 2026-05-19)

Minimum system-followed dark mode (no JS, no toggle)

<meta name="color-scheme" content="light dark">

:root {
  color-scheme: light dark;

  --bg:     light-dark(#ffffff, #0b0d12);
  --fg:     light-dark(#1a1a1a, #f5f5f5);
  --accent: light-dark(#2563eb, #60a5fa);
  --border: light-dark(#e2e8f0, );
}

 { : (--bg); : (--fg); }