Colour tokens

Five ramps of eleven steps, generated from one hue each; sixty-nine semantic roles built on top of them; and a handful of controls that derive every interactive state. Nothing here is hand-picked, and every value on this page is read out of the browser at runtime rather than typed into the document.

How colour is generated

No swatch in this system was chosen by eye. A ramp is three things multiplied together: one hue angle, a lightness ladder shared by all five ramps, and a chroma ladder of its own. Every step is the same declaration with different generator tokens substituted in.

--color-brand-600: oklch(var(--l-600) var(--c-brand-600) var(--hue-brand));

That is the actual line from src/tokens.css, not a paraphrase of it. The consequence is that a ramp has exactly one editable input for hue: change --hue-brand and all eleven steps move together, in step, without any of them leaving sRGB. The chroma ladders peak near the middle of each ramp and fall off at both ends, which is what keeps --color-brand-50 reading as a tint rather than a washed-out mid-tone.

The lightness ladder

All five ramps walk the same ladder: even 8% steps from 98% down to 18%. That is what makes step numbers mean something across ramps: --color-brand-600 and --color-danger-600 have identical lightness, so swapping one family for another in a component changes hue and nothing else.

The chroma ladders

The other half of the generator. Each ramp carries its own chroma ladder, peaking near the middle of the lightness ladder and falling away at both ends so the lightest and darkest steps stay inside sRGB and read as tints rather than as saturated colour. This is why the five ramps share a lightness but not an intensity: orange has far less headroom at a given lightness than blue does, and forcing them to match would push warn out of gamut.

The five ramps

Each cell below is filled with its own step token (the fourth cell of the danger row is literally background-color: var(--color-danger-300)), so this is a live rendering of the tokens rather than a picture of them. Each cell carries Aa in --color-white and Aa in --color-black, which puts the point where text has to flip colour on the screen instead of in a spreadsheet.

Brand

The product hue. Blue-violet at 262, harmonised with neutral so greys sit in the same family rather than reading as a second colour. Hue token: --hue-brand = .

Neutral

Chroma near zero across the whole ramp, but not exactly zero: the greys carry a trace of the brand hue so surfaces and text never look muddy beside brand-coloured elements. Hue token: --hue-neutral = .

Success

Green at 150. Chroma peaks lower than brand because green is already the most luminous hue at a given lightness. Hue token: --hue-success = .

Warn

Orange at 48. Light at every usable step, which is why solid warn carries a dark label in both themes and why its state derivation differs. Hue token: --hue-warn = . Under data-brand="orange", and only there, it is 80 (amber) with six chroma steps of its own, so warn stays distinct from an orange brand.

Danger

Red-orange at 27. Chroma ladder is the widest of the five, which is what keeps a destructive action separable from brand at the same step. Hue token: --hue-danger = .

Semantic roles

Surfaces

Five stacked planes, from the page up to an inverted strip. The first three are a ladder in both themes: sunken under the page under a surface. A white card measures 1.21:1 against the page in light and in dark, and the page 1.08 / 1.09 against a sunken well. Light has no rung above white, so its step is bought by moving the page down: the page is a 55% mix of --color-neutral-100 into --color-neutral-50 and sunken an 85% mix, the deepest that keeps --color-text-subtle above 4.5:1 on it (4.62). Note the deliberate asymmetry one rung up: in light mode --color-surface and --color-surface-raised are the same white and elevation is carried entirely by shadow, which is how light interfaces actually read. In dark mode shadow is nearly invisible, so the two differ by a full ladder step. A component must therefore never rely on raised being a different colour from surface: use a shadow token alongside it.

Text

Text roles are shown as text on the surface they are meant for. A swatch of --color-text-subtle tells you nothing useful; a line of it at reading size on --color-surface tells you whether it is readable. Both muted and subtle sit one step deeper than the obvious choice, because the even ladder puts --color-neutral-500 at only 3.55:1 on --color-bg.

Borders

Three roles with three different jobs, rendered here as actual borders on both --color-bg and --color-surface. They answer to different bars, see the contrast section.

The four families

Brand, success, warn and danger each expose the same six roles: the bare name for icons and rules, -solid with its -on-solid label, -subtle with -text for tinted callouts, and -border for outlines. Because the shape is identical, a component can be written once and parameterised by family.

Brand alone carries a seventh: --color-brand-subtle-raised, the raised-ground sibling of --color-brand-subtle, the same pairing as --color-surface / --color-surface-raised. In dark mode --color-brand-subtle and --color-surface land on the same rung of the lightness ladder, so a fill built from one measures 1.00:1 against a ground built from the other: scrollspy.css's current-link fill shipped exactly that bug. The raised role takes --color-brand-text the same way --color-brand-subtle does.

Warn is the exception, and deliberately so. Orange is light at every usable step, so --color-warn-solid is --color-warn-400 in both themes rather than a light-dark() pair, and --color-warn-on-solid is always dark. Orange is spent only where it is bright: --color-warn-text is the normal reading colour in both themes, and the orange itself lives in the icon, the 1px border, the light-mode pale fill and --color-warn graphics, never in a paragraph of running text.

Highlight, selection, focus and overlay

The neutral role family

Neutral carries the same five role names as brand, success, warn and danger, so a component can write --color-<family>-subtle generically instead of special-casing one of them. These are aliases onto roles that already exist, no new colours, but they were added after the first components were written, because without them every component reinvented the mapping and two of them picked different answers.

Raised and sunken surface states

--color-surface-hover and --color-surface-active derive from --color-surface only. Raised and sunken surfaces need their own derivations, and this is not cosmetic: in dark mode --color-surface-raised sits a step lighter than --color-surface, so an elevated card pointed at --color-surface-hover goes darker on hover than it is at rest, backwards. Deriving from each surface's own resting colour keeps the direction right in both themes.

--card-bg-hover: color-mix(in oklab, var(--card-bg), var(--state-shade) var(--state-hover-amount));

Interactive states

How a hover is derived

Hover and active colours are not authored. Each one is a mix between the base fill and a shade token, by a fixed amount:

--color-brand-solid-hover: color-mix(in oklab, var(--color-brand-solid), var(--state-shade) var(--state-hover-amount));

--state-shade is black in light and white in dark, so the same formula darkens the fill in light mode and lightens it in dark mode. The light half is not --color-black: black has no hue, and neither does a white surface, so the mix of the two was a true grey beside neutrals that are all cool. It is generated instead: black's lightness, the neutral hue, and the chroma that makes a hover from white land exactly on --color-neutral-100. Lightness is untouched, so a solid fill's hover and press are as long as they were with plain black. That is not a cosmetic preference. It is the rule that keeps the label readable:

Which means direction is a property of the fill's label, not of the theme. --state-lift exists for exactly one case: warn, whose fill carries a dark label in both themes. Using --state-shade there walked the warn label from 5.71:1 at rest down to 3.55:1 on :active in light mode: the formula was right and the direction was wrong.

Rest, hover, active

All four families, in both themes. Each cell is filled with its own token and labelled with its own -on-solid colour, so what you are reading is the actual pairing.

State controls

Surface states

Neutral surfaces derive the same way. --color-surface-selected mixes in --color-brand instead of the shade, because selection is a statement about identity rather than about pressure. The orange preset is the exception in dark mode: a 12% mix of bright orange into a dark surface is a warm grey, so there it starts from --color-surface-raised (a checked menu row sits on a raised menu) and mixes toward --color-text instead.

Contrast

The numbers below are measured, not estimated. Each token was resolved in a live browser, converted OKLab → linear sRGB → WCAG relative luminance, and the ratio computed from that. Re-running the measurement is the only way to know these still hold.

Solid fills against their own labels

Read each cell as [rest, hover, active].

Every pairing clears AA at 4.5:1, with 5.05:1 the worst case. More usefully, every one improves on hover and improves again on active, which is the derivation rule doing its job, in twenty-four measurements, rather than a coincidence.

Text and border roles

Retuning a ramp

One declaration in your own stylesheet is the whole operation. Your CSS is unlayered, so it wins over the tokens layer without any priority-raising declaration.

:root {
  --hue-brand: 275;
}

That regenerates all eleven ramp steps from --color-brand-50 to --color-brand-950, both light-dark() arms of --color-brand, --color-brand-solid, --color-brand-subtle, --color-brand-text and --color-brand-border, both derived state colours, --color-surface-selected (which mixes brand in), and --color-focus (which is an alias of brand). Retuning --hue-neutral additionally moves every surface, every text role, every border role and both shadow tints, since those are mixed from the neutral ramp rather than from literals.

Brand presets

Seven ready-made main colours ship as data-brand presets: one attribute on the root element instead of hand-picking a hue. blue is the shipped default. See Choosing the main colour for the mechanism, including why it is root-only and why mono flips with the theme rather than shipping as a literal black and a literal white, and A custom main colour, from a seed to build one of your own from a hex or rgb value.

background-color: oklch(var(--l-600) var(--c-brand-600) var(--hue-brand));