The dispatch app’s night-shift users asked for dark mode for two years. Every estimate came back at “six weeks per product”, because colors were hard-coded in hundreds of components. With the semantic tier from the last lesson, Northwind’s dark mode took nine days, most of it design review. The components didn’t change at all.
\nA theme changes which primitive each semantic token points at. Nothing else.
\n:root {\n --nw-color-surface: var(--nw-gray-0);\n --nw-color-text: var(--nw-gray-900);\n --nw-color-action-bg: var(--nw-blue-600);\n --nw-color-action-text: var(--nw-gray-0);\n}\n\n[data-theme=\"dark\"] {\n color-scheme: dark;\n --nw-color-surface: var(--nw-gray-950);\n --nw-color-text: var(--nw-gray-100);\n --nw-color-action-bg: var(--nw-blue-400);\n --nw-color-action-text: var(--nw-gray-950);\n}Two details matter. First, the selector is [data-theme="dark"], not html[data-theme="dark"], so any element can start a dark subtree: the marketing site’s hero is dark on an otherwise light page. Second, color-scheme: dark tells the browser to draw its own UI, such as scrollbars, checkboxes and date inputs, in dark colors too.
Notice the action blue changes step, from 600 to 400. Dark backgrounds need lighter accent colors to keep contrast, so dark mode is a design task, not a color inversion.
\nThree rules saved Northwind weeks of review. Check contrast for every text and background pair in the dark theme separately, because a pair that passes on white can fail on near-black. Avoid pure black surfaces; a very dark grey like #111827 is easier on the eyes and leaves room for darker shadows. And express elevation with lighter surfaces rather than heavier shadows, since shadows barely show on dark backgrounds: a raised card in dark mode is a step lighter than the page behind it.
That last rule is a good example of why the semantic tier needs names like --nw-color-surface-raised. In light mode it maps to white on a light grey page; in dark mode it maps to a slightly lighter grey. Same name, same role, different values.
Respect the operating system setting by default, and let users override it:
\n@media (prefers-color-scheme: dark) {\n :root:not([data-theme=\"light\"]) {\n color-scheme: dark;\n --nw-color-surface: var(--nw-gray-950);\n /* …same remapping as [data-theme=\"dark\"] */\n }\n}// Inline in <head>, before the CSS paints, so there is no flash of the wrong theme.\nconst saved = localStorage.getItem('nw-theme');\nif (saved === 'light' || saved === 'dark') {\n document.documentElement.dataset.theme = saved;\n}Duplicating the dark block inside the media query is the price of supporting both. Northwind’s token pipeline generates both copies from one source, which you’ll set up in two lessons. For simple two-mode colors you can also use the CSS light-dark() function with color-scheme: light dark, but it only switches colors (and, in newer browsers, images) between exactly two schemes, so it doesn’t replace token remapping for brands or density.
Northwind has three axes, each set by its own attribute:
\nThe trick that keeps them independent is ownership: each axis remaps its own tokens and never another axis’s. Density only touches spacing:
\n:root {\n --nw-space-control-y: var(--nw-space-2);\n --nw-space-control-x: var(--nw-space-4);\n}\n[data-density=\"compact\"] {\n --nw-space-control-y: var(--nw-space-1);\n --nw-space-control-x: var(--nw-space-3);\n}Brand and color scheme do interact, because Tidewater’s teal needs a lighter step in dark mode just like Northwind’s blue. Solve it with one level of indirection: the brand defines a ramp of brand primitives, and the theme chooses the step.
\n:root { /* Northwind is the default brand */\n --nw-brand-400: var(--nw-blue-400);\n --nw-brand-600: var(--nw-blue-600);\n}\n[data-brand=\"tidewater\"] {\n --nw-brand-400: var(--nw-teal-400);\n --nw-brand-600: var(--nw-teal-600);\n}\n:root { --nw-color-action-bg: var(--nw-brand-600); }\n[data-theme=\"dark\"] { --nw-color-action-bg: var(--nw-brand-400); }Now <html data-brand="tidewater" data-theme="dark" data-density="compact"> works without a single combined selector. One caveat: this version assumes data-brand sits on <html>, which holds for Northwind because a page belongs to one brand. The :root mapping is computed once at the root, so if a brand could change mid-page you would repeat the semantic mappings under [data-brand] as well, for the same reason component tokens live on component selectors. Brand decides which colors, theme decides how light, density decides how tight. Eight combinations, six small blocks.
In the exercise, you add a dark theme that works on any element and a compact density mode. Next, you move these tokens out of hand-written CSS into a format every tool can read.
\n","toc":[{"id":"sec-1","text":"A theme is a remapping","level":2},{"id":"sec-2","text":"Designing the dark palette","level":2},{"id":"sec-3","text":"Following the system preference","level":2},{"id":"sec-4","text":"Modes are independent axes","level":2}],"takeaways":["A theme or mode is a remapping of semantic tokens; components and primitives stay the same.","Treat color scheme, brand and density as independent axes, each owning its own set of tokens, so combinations don’t multiply your work.","Selectors like[data-theme="dark"] work on any element, so a section of a page can use a different theme from the rest.","Set color-scheme with your dark theme so browser-drawn parts like form controls and scrollbars match."],"further":[{"title":"prefers-color-scheme (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-color-scheme"},{"title":"color-scheme (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/color-scheme"},{"title":"light-dark() (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/light-dark"}],"quiz":[{"q":"Northwind has 2 color schemes, 2 brands and 2 densities. How many hand-written theme files should you need if the axes are independent?
","options":[{"text":"Eight, one for each combination.","why":"That’s the result of treating combinations as themes; it grows multiplicatively and each file duplicates the others."},{"text":"Six, one block per value on each axis, plus small overrides only where two axes truly interact.","why":"Correct. Each axis owns its tokens, so you write 2 + 2 + 2 blocks and let the cascade combine them."},{"text":"Two, light and dark, with brand and density handled in components.","why":"Pushing brand and density into components means every component needs to know about them, which is what tokens avoid."},{"text":"One, because the browser calculates dark colors automatically.","why":"Browsers don’t derive a usable dark palette from a light one; you design and map it."}],"answer":1},{"q":"The marketing hero sets data-theme="dark" on its <section>, but its cards stay white. The dark block is written as html[data-theme="dark"] { … }. What’s wrong?
<section> elements.","why":"Any element can carry data attributes, and attribute selectors match them anywhere."},{"text":"Custom properties don’t inherit through <section>.","why":"Custom properties inherit through every element."},{"text":"The html type selector limits the dark tokens to the root, so the section’s attribute never matches.","why":"Correct. Writing [data-theme="dark"] alone lets any element start a dark subtree."},{"text":"The hero needs color-scheme: dark to activate the tokens.","why":"The color-scheme property changes browser-drawn UI like scrollbars; it doesn’t switch your custom properties."}],"answer":2},{"q":"In dark mode, Northwind’s buttons use --nw-blue-400 instead of --nw-blue-600. Tidewater buttons use a teal ramp. Which structure handles both cleanly?
--nw-brand-* primitive ramp; the theme picks which step of the ramp each semantic token uses.","why":"Correct. Brand decides which colors, theme decides how light or dark, and neither needs to know about the other."},{"text":"Four blocks with combined selectors for every brand and theme pair.","why":"It works for two brands, but every new brand or mode multiplies the blocks to maintain."},{"text":"Separate button components for each brand.","why":"Forking components per brand undoes the reason for having a shared system."}],"answer":0}],"exercise":{"kind":"web","mode":"dom","starter":{"html":"The light theme and the components are done. Add two modes by remapping semantic tokens only (leave the components alone):
\ndata-theme="dark", not just <html>: surface → --nw-gray-950, text → --nw-gray-100, action background → --nw-blue-400, action text → --nw-gray-950. Also set color-scheme: dark.data-density="compact": control padding y → --nw-space-1, x → --nw-space-3.The hero section already carries data-theme="dark", so it should turn dark as soon as your theme works.
[data-theme="dark"] { … }. Adding html in front would stop the hero from matching.","Inside the block, redeclare the four semantic color tokens with var() pointing at the dark primitives.","The density block only needs --nw-space-control-y and --nw-space-control-x."],"explanation":"Both modes are pure remappings: no component CSS changed, yet the hero card, its button and any page with data-theme="dark" on <html> all switch. Because the selector is a bare attribute selector, the theme can start at any element, and because the button declares its component tokens on .nw-button, they resolve against the nearest theme. Density owns only spacing tokens, so it combines with either theme without extra rules.
data-theme="dark") uses the dark surface and text","dark-button":"Buttons inside the dark hero use the lighter blue with dark text","page-dark":"data-theme="dark" on <html> darkens the whole page and sets color-scheme: dark","compact":"data-density="compact" shrinks the button padding to 4px by 12px"}},"words":678,"readMinutes":3}