Theming and Dark Mode

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

Theme

A set of values (mostly colours) that controls how the whole site looks, which you can swap as a group.

Custom property

A CSS variable you name yourself with two dashes, like --bg, and read with var(--bg).

Design token

A named design value, like --accent or --radius, used everywhere instead of raw values.

Semantic token

A token named by its job (--text, --danger) rather than its look (--red-600).

`prefers-color-scheme`

A media feature that tells CSS whether the user's system is set to light or dark.

`color-scheme`

A property that tells the browser which schemes your page supports, so it draws its own parts (canvas, controls, scrollbars) to match.

`light-dark()`

A colour function that returns its first colour in light mode and its second in dark mode.

Canvas

The background the browser paints behind your whole page.

Theme flash

The page appearing in the wrong theme for a moment while it loads, before the right one is applied.

1. 1

   Add a token

   In the first example, add a --border token to both themes and use it for the .app border. Predict what the border looks like in each theme before you click.

2. 2

   Remove color-scheme

   In the second example, delete .force-dark { color-scheme: dark; }. Predict the dark panel's background and its input's look. Run and check the console.

3. 3

   Emulate dark mode

   Open DevTools on the third example, find the Rendering panel and emulate prefers-color-scheme: dark. Predict what the message will say first.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   The building blocks are custom properties (CSS variables, Phase 3): --bg: #ffffff; defines one, var(--bg) reads it. A theme is a set of design tokens: named values like --bg, --text, --muted, --accent and --border. Components never use raw colours; they use tokens: background: var(--bg). Custom properties inherit, so redefining the tokens on one element re-themes everything inside it.

2. 2

   Name tokens by role, not by colour. --accent can be indigo in light mode and pale indigo in dark mode; a token called --indigo-600 that later holds a pale colour is a lie. Many systems use two levels: primitive tokens (--indigo-600: #4f46e5) and semantic tokens that point at them (--accent: var(--indigo-600)). Themes only change the semantic level.

3. 3

   The user's operating system has a light or dark setting. CSS reads it with the media query @media (prefers-color-scheme: dark) { ... } (Phase 9). The usual pattern: define light tokens on :root, then redefine them inside that media query. JavaScript can read the same setting with matchMedia("(prefers-color-scheme: dark)").matches.

4. 4

   Your CSS isn't the only thing that draws. The browser draws the page background (the canvas), scrollbars, form controls, and the default text colour. The **color-scheme** property tells it which schemes your page supports: :root { color-scheme: light dark; } means "I support both; use the user's preference". In dark mode the browser then paints a dark canvas, dark scrollbars and dark <input> and <select> controls. Without it, you get a dark page with glaring white form controls. The <meta name="color-scheme" content="light dark"> tag says the same thing before the CSS has even loaded, which avoids a white flash.

5. 5

   **light-dark(a, b)** is a colour function that returns a when the element's used colour scheme is light and b when it is dark: --bg: light-dark(#ffffff, #111827);. It reads color-scheme, so it only works when color-scheme allows dark (light dark or dark). With it, one declaration replaces a whole media-query block, and setting color-scheme: dark on one element makes that element dark even if the page is light. It only accepts colours (Baseline 2024).

6. 6

   Most sites also give users a theme switch, because the system setting isn't always what people want on your site. The common recipe: a data-theme="light" or "dark" attribute on <html>, CSS that sets color-scheme (and token values) for each, a button that changes the attribute, and localStorage to remember the choice. To avoid a flash of the wrong theme on load, a tiny script in the <head> sets the attribute before the page is painted.

7. 7

   Dark mode is a design task, not "invert the colours". Pure black backgrounds with pure white text are harsh; use a dark grey like #111827 and slightly dimmed text. Shadows don't show on dark backgrounds, so use lighter surface colours for raised elements. Saturated brand colours often need lighter versions to keep contrast (Topic 11.7). And images may need filter: brightness(.9) or separate dark versions with <picture> and media="(prefers-color-scheme: dark)".

• ↔

  Following only the system setting needs no JavaScript, but users can't choose a different theme for your site; a toggle needs a little script and storage.

• ↔

  light-dark() makes tokens compact, but it only handles colours and two schemes; images, shadows and extra themes (high contrast, sepia) still need attributes or media queries.

• I can define semantic colour tokens and use them in components.

• I can switch tokens with prefers-color-scheme.

• I know what color-scheme changes and always set it.

• I can write tokens with light-dark().

• I can build a remembered theme switch without a flash on load.