Waypoint’s dark mode was built the classic way: a full set of color tokens in :root, and a second full set inside @media (prefers-color-scheme: dark). It worked until three things happened. Someone added a token to the light set and forgot the dark one. Users asked for a toggle, because their OS is dark but they want the schedule light on a projector. And the design team wanted the hero to be dark in both modes.
Each of these is a one-liner with color-scheme and light-dark().
:root {\n color-scheme: light dark;\n}This declaration says “this page supports both schemes; use the user’s preference”. The browser responds by rendering its own UI to match: form controls, checkboxes, scrollbars, the default page background and text color. Without it, a dark page still gets bright white <select> menus and scrollbars, which is the most common tell of a hand-made dark mode.
Add the matching meta tag so the browser knows before your CSS arrives, and the page doesn’t flash white on load:
\n<meta name=\"color-scheme\" content=\"light dark\">light-dark() takes two colors and returns the first when the element’s used color scheme is light and the second when it’s dark:
:root {\n color-scheme: light dark;\n\n --surface: light-dark(#ffffff, #0f172a);\n --text: light-dark(#1f2937, #e5e7eb);\n --card: light-dark(#f8fafc, #1e293b);\n --border: light-dark(oklch(90% 0.01 280), oklch(35% 0.02 280));\n}\n\nbody {\n background: var(--surface);\n color: var(--text);\n}\n.session-card {\n background: var(--card);\n border: 1px solid var(--border);\n}Each token is now defined once, with both values side by side. Adding a token without its dark value becomes visibly incomplete in review. light-dark() for colors is Baseline 2024 and works in every current browser. Passing it two images (such as gradients or url()s) only became Baseline in September 2026, and it never accepts lengths or other values, so for those keep a prefers-color-scheme media query for now.
Because everything reads the color scheme, the toggle only has to change one property on the root:
\n:root[data-theme=\"light\"] { color-scheme: light; }\n:root[data-theme=\"dark\"] { color-scheme: dark; }With no data-theme, the root keeps light dark and follows the OS. With data-theme="dark", it’s forced dark, and every token follows. The JavaScript for a three-way control is tiny:
const select = document.querySelector('#theme');\nconst saved = localStorage.getItem('theme');\nif (saved) document.documentElement.dataset.theme = saved;\n\nselect.addEventListener('change', () => {\n const value = select.value; // 'system' | 'light' | 'dark'\n if (value === 'system') {\n delete document.documentElement.dataset.theme;\n localStorage.removeItem('theme');\n } else {\n document.documentElement.dataset.theme = value;\n localStorage.setItem('theme', value);\n }\n});Run the restore part in a small inline script in the <head> so the saved theme applies before the first paint.
color-scheme is inherited, and light-dark() resolves against each element’s own value. So the always-dark hero needs one declaration:
.hero {\n color-scheme: dark;\n background: var(--surface);\n color: var(--text);\n}Inside the hero, --surface, --text and --card all resolve to their dark values, including the keynote session card nested inside it, while the rest of the page stays light. The same trick works the other way for a light “print preview” panel inside a dark app.
Dark mode isn’t inverted light mode. A few rules that hold up on real projects:
\n#0f172a is easier on the eyes and leaves room for elevation.#1e293b, a popover on a step lighter. Shadows barely show on dark backgrounds.oklch(from var(--track) 72% calc(c * 0.8) h) raises lightness and tones down chroma for dark surfaces.You don’t have to switch your operating system to test any of this. Chrome’s DevTools can emulate prefers-color-scheme: dark from the Rendering panel, and Firefox has a toggle in its Inspector. Test the three toggle states and the hero in each, and check the form controls: they are the first place a missing color-scheme shows up.
The exercise uses the old pattern: tokens plus a prefers-color-scheme override, and no toggle. Rewrite the tokens with light-dark(), wire up data-theme on the root, and make the hero dark in both modes. The checks set data-theme and read the computed colors. Next, you’ll make sure people who navigate with a keyboard can see where they are, in both themes.
color-scheme: light dark tells the browser the page supports both schemes, so form controls, scrollbars and default colors follow the user’s setting.","light-dark(A, B) returns A or B depending on the element’s used color scheme, so each token is defined once instead of in two places.","A three-way toggle (system, light, dark) only needs to set color-scheme on the root; every light-dark() value follows.","Because light-dark() resolves per element, color-scheme: dark on one section makes that section dark while the rest of the page stays light."],"further":[{"title":"light-dark() (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/light-dark"},{"title":"color-scheme (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme"},{"title":"Improved dark mode default styling with color-scheme (web.dev)","url":"https://web.dev/articles/color-scheme"}],"quiz":[{"q":"You write --surface: light-dark(white, #0f172a) and use it on body, but the page stays white in dark mode. What’s missing?
@media (prefers-color-scheme: dark) block around the token.","why":"That’s the older technique; light-dark() exists so you don’t need it. It reads the color scheme instead."},{"text":"color-scheme: light dark on the root (or the element).","why":"Correct. Without it, the used color scheme is light, so light-dark() always returns its first value."},{"text":"@property registration for --surface.","why":"Unregistered custom properties work fine here; light-dark() is resolved where the token is used."},{"text":"Dark mode only works when the color is written in oklch().","why":"light-dark() accepts any color format."}],"answer":1},{"q":"The Waypoint hero should always look dark, even in light mode. Its colors come from light-dark() tokens. What’s the smallest change?
--hero- prefix holding the dark values.","why":"It works, but it doubles the token set and drifts the moment someone edits one copy."},{"text":"Add data-theme="dark" to the hero element.","why":"That attribute only matters if your CSS reads it there; the toggle in this lesson reads it on the root."},{"text":"Add color-scheme: dark to .hero.","why":"Correct. light-dark() resolves against each element’s own used color scheme, which inherits, so the hero and its descendants pick the dark values."}],"answer":2},{"q":"What’s the job of <meta name="color-scheme" content="light dark"> in the HTML head?
light-dark() to work.","why":"The CSS color-scheme property is enough for light-dark(); the meta tag helps first paint."},{"text":"It replaces the prefers-color-scheme media query in all stylesheets.","why":"Media queries keep working; the meta tag only declares which schemes the page supports."}],"answer":0}],"exercise":{"kind":"web","mode":"dom","starter":{"html":"Rewrite the theme so that:
\n--surface, --text and --card are each defined once with light-dark() (light values: #ffffff, #1f2937, #f8fafc; dark: #0f172a, #e5e7eb, #1e293b). Remove the media query.data-theme="light" or data-theme="dark" on <html> forces that scheme; with no attribute, the page follows the system..hero is dark in every mode, using the same tokens (no hero-specific colors).The checks set data-theme on <html> and read computed colors.
light-dark() only works when color-scheme allows dark. Start with color-scheme: light dark on :root.","The toggle rules only change color-scheme: :root[data-theme="dark"] { color-scheme: dark; } and the same for light.","For the hero, add color-scheme: dark; to .hero. Its var(--surface) and the nested card’s var(--card) then resolve to the dark values."],"explanation":"light-dark() picks a value from the used color scheme of the element where the token is used, and color-scheme sets that scheme. color-scheme: light dark on the root follows the OS; the data-theme rules override it with a single property, so every token follows without a second token set. Because light-dark() resolves per element and color-scheme inherits, color-scheme: dark on .hero makes the hero and the keynote card inside it dark while the regular card stays light.