Colour

Ten families of eleven stops, a twelfth in the two surface ladders, 54 roles, and a rule that keeps them apart: nothing in the product references a primitive directly.

How colour is organised

Three layers, and a seam between the first two. Primitives name a value — twilight/600 — and are never applied in a component. Theme tokens name a job — interactive/accent — and point at a primitive; they are the only layer a component references, and the only one that changes between light and dark. That seam is what makes the dark theme possible: without it, dark mode would mean auditing every use to work out which meant “the accent” and which just wanted violet.

Primitives

The raw ramps. These carry no meaning and are not used in components — they exist to be aliased. Every family is generated in OKLCH and shares one lightness per stop, so a number means the same amount of light everywhere: any 600 carries a white label at 4.5:1 or better, any 400 carries a night/950 label, any 500 is the 3:1 stop for icons and borders, any 700 is text on its own 050, any 300 is text on its own 900. Chroma and hue are each family’s own.

There are no half steps for text or fills. The twenty-step neutral this replaced had adjacent steps 1.08 to 1.23:1 apart, and produced two text levels nobody could tell apart. The one exception is 925, the surface step, in stone and night only: no text is ever set in one surface against another, and every reference system measured places its surface levels closer than any ramp places its text stops — see Elevation and states. When a ladder runs out, separate with a border.

One lightness per stop

The lightness is stone’s, read in OKLCH; every other family sits within a thousandth of it. Each stop’s job is measured across all ten families as the page renders, and the family shown is the one where the pair is tightest.

Choosing a colour

Reach for the role, never the value. A component that needs the accent takes interactive/accent; if what it needs has no token, the answer is a new token, not a primitive that happens to look right today — a separator borrowed as a text colour reads until borders get lighter, and then the text goes with them.

One colour, one meaning. The accent means interactive, so that hue on static text tells the reader to click something that is not a control. glow is the brand and never a button tone: glow/600 and ember/600 are 1.02:1 apart, and a pink button beside a danger button would be two of the same thing. amber is warning and flare the highlight, kept far enough apart at 400 to read as two. And filled colour is emphasis: one solid accent per view, with the alternative beside it neutral — see Button.

Measure the pair that renders. Text against the surface it sits on, a border against the fill it edges, a label against its own button in every state, and an alpha over the ground it lands on. The tables below do exactly that, with the function the test suite runs; a value written by hand is a value that can rot.

Surfaces

A ladder of elevation rather than a set of colours. In light, raised and overlay are both white and the shadow does the separating; in dark, overlay steps lighter because shadow no longer reads as height, and sunken shares the canvas because the ramp ends at 950 — a well on the canvas takes a border. The dark ladder is night 950, 925, 900, ΔL .043 per step; a product that wants a neutral dark aliases the same stops of stone, and every pair holds — the tightest, border/strong on stone/800, is 3.44:1. The tail is deep on purpose: 700 to 950 sit at L .43, .33, .245, .205 and .16, so the dark canvas reads as night rather than slate. Alpha tokens are shown flattened over a card.

Text

Measured against surface/raised. Placeholder is the same stop as tertiary and clears AA; disabled and inert sit below it deliberately — both are exempt under WCAG 2.1, and both are documented at their recorded value so a future edit cannot quietly make them worse.

Interactive

Fills and the labels that sit on them. Every on-* token is measured against all of its fill states, not just the resting one. The two wash tokens are a state layer rather than a fill — laid over a row, a menu item, a ghost button or the neutral button’s own fill — and are shown here over a card; their readings are on the Elevation page.

Border

Three tiers by function, not by weight. subtle divides, and is an alpha so it reads on every surface without picking a stop above any of them; default outlines containers; and strong is the only tier that clears WCAG 1.4.11 — which is why every form control uses it.

Accessibility

Colour is never the only channel. A state has an icon, a label or a shape beside its colour; focus adds a ring rather than recolouring a border; a selected row carries an attribute a screen reader can read. Text clears 4.5:1 and non-text, borders and icons and the parts of a control, 3:1, on the surface they render on, in both modes.

Two text tokens sit under the line on purpose. disabled and inert are exempt under WCAG 2.1 — one is an unavailable control, the other decoration — and each is documented at its recorded value above, so an edit that made either worse would show in the table before it shipped.