Color & theming

Palette — --{hue}-{0..12}

Each hue family has 13 steps from 0 (lightest) to 12 (darkest). Hues available: gray, stone, red, pink, purple, violet, indigo, blue, cyan, teal, green, lime, yellow, orange, choco, brown, sand, camo, jungle.

Scale guideline:

0–2

Page backgrounds, light surfaces

3–5

Borders, dividers, subtle fills

6–8

Accent fills, icon colors

9–12

Text, high-contrast elements

Alpha — color-mix

Compose translucent colors with color-mix in OKLCH. This project standardizes on color-mix for alpha (rather than Open Props' --{hue}-{n}-hsl variants) so color calculations use a perceptually uniform space. oklch is safe here because the other colour is transparent, which contributes no hue; a mix against an opaque near-neutral is written in oklab instead — see Radio group · color-mix.

Semantic aliases

The project defines semantic color aliases for Open Props values in /index.css, so component CSS names each color by its purpose. Use the aliases, not the palette, when writing component CSS.

--surface-1

Page background

--surface-2

Card / section background

--surface-3

Raised elements, hover fills

--surface-overlay

Panels floating in the top layer — the x-select picker, the combobox list, ui-menu, ui-popover, ui-notifications. Not a step on the surface ramp: it equals --surface-1 in light and steps a tone lighter in dark. See Elevation § Overlay surfaces for why

--text-1

Primary text

--text-2

Muted text (captions, meta)

--brand

Primary action / accent

--on-brand

Text / icons sitting on a --brand fill (white in light mode; near-black in dark, where the brand is a light indigo)

--border-color

Subtle borders and dividers

--border-strong

Emphasised borders — hover states, focus-adjacent

--info / --success / --warning / --error

Feedback colors (text/icon roles — dark mode rebinds them to lighter palette steps) — see Notifications and Form field states

Two cases need more than a semantic alias:

• Dark fills that stay the same in both themes — a destructive button or record button keeps its dark red background and white text in both modes. Explain these choices in comments so later edits preserve them.
• Text colors that adapt to the theme — color-mix(in oklab, <ink> 60%, var(--text-1)) deepens an accent toward black on light surfaces and lifts it toward white on dark ones, because --text-1 itself flips. Used for callout text and dark status colors. oklab, not oklch: --text-1 is near-neutral rather than neutral, so its residual hue affects the mix. The two browser engines produce different hues — orange in Chromium against magenta in Firefox for this combination. See Radio group · color-mix.

3-state theming (System / Light / Dark)

Swap alias values under three triggers, so the user can pick System, Light, or Dark:

• No class on :root — follow the OS via prefers-color-scheme.
• :root.dark — force dark even on a light-mode OS.
• :root.light — force light even on a dark-mode OS.

Values are defined once as -light/-dark pairs (the open-props.style adaptive-colors pattern); the two dark-mode blocks only assign those paired values and must stay identical — a media query can't share a selector list with a class. The project's own tokens live in /index.css. Every page also includes <meta name="color-scheme" content="light dark"> so the browser uses the right color scheme before loading CSS.

Browser chrome — <meta name="theme-color">

Mobile browsers paint their address bar, and an installed app paints its title bar, from <meta name="theme-color">. Importing /ui/lib/theme.mjs keeps that tag updated with the current value of --surface-1 — creating the tag if needed — so the browser bars match the page through every theme change, including OS changes in System mode. The module handles this without additional page markup.

Why JavaScript updates the tag. The static form of this tag is one <meta> per media="(prefers-color-scheme: …)", which follows the OS preference. The switcher's Light and Dark choices override the OS preference. With static tags, choosing Light on a dark-mode OS would leave dark browser bars above a light page. Reading the computed token also keeps the color definition in one place, like the -light/-dark pairs above do.

A web app manifest carries a theme_color of its own, and it is a single static value — the format has no light/dark pair. Give it the light --surface-1, so the two agree wherever the runtime tag has not yet been applied (a splash screen, an install card), and let this tag correct it once the page runs.

theme.mjs — module API

The toggle demos below drive the same module the rest of the app uses. Source: /ui/lib/theme.mjs.

The same 'theme-change' event is also dispatched on document, for a listener in a component that never imports this module. Choose where to listen according to the listener's lifetime — see Conventions for the event-listener hierarchy.

Live readout — get_effective_theme + theme_events

This box updates whenever the choice changes or the OS theme flips while in 'system' mode. Toggle your OS appearance to see it in action.

Flash prevention

A tiny inline <script> in <head> before the stylesheet links applies the saved choice before CSS parses, so a returning dark-mode user doesn't see a flash of light.

Demo A — sun-and-moon toggle (2-state)

Borrowed from Adam Argyle's web.dev article — an SVG sun with 8 beams, masked by a moving moon circle. All animation is CSS transforms (no JS animation). The button's aria-label reflects the current effective theme and aria-live="polite" announces updates to screen readers.

Reaching System with only two states: the click handler flips the effective theme, and when the result matches the OS preference it stores 'system' instead of the explicit value — so toggling onto whatever the OS already shows returns the user to following the OS. This provides access to all three preferences with one button. The app ships this packaged as <ui-theme-toggle> (/ui/components/ui-theme-toggle.mjs); Demo B below shows the explicit 3-button alternative.

Demo B — segmented radiogroup (3-state)

The same 3-state model as a one-of-three choice — System / Light / Dark — built as the shared radio group: a <fieldset role="radiogroup"> of native radios. There is no roving tabindex and no keydown handler here, because the platform supplies the whole APG radio pattern for real radios. Each option's icon is aria-hidden="true"; the visible text is the accessible name.

This demo changes the appearance with two custom properties, --segmented-track and --segmented-selected: the picker uses --surface-2 for the track and --surface-1 for the selected option, replacing the default fill of --brand. See Radio group § Theming.

Pitfalls

• Use semantic aliases, not palette values (--surface-1, not --stone-0) so components adapt to light/dark automatically.
• Alpha via color-mix(in oklch, …) — not RGB hex + opacity.
• Wrap motion in the motion query so the theme toggle respects prefers-reduced-motion.

See also

• Tokens — size and spacing tokens.
• Motion — easing curves used in the sun-and-moon animation.
• /ui/lib/theme.mjs — theme state + theme-change event.
• Conventions — the event-listener hierarchy (theme-change is dispatched at tiers 2 and 3).