Color guide

--surface is the canvas, --surface-raised the elevated one, --surface-subtle the working level for fields and hovers. --text, --text-muted and --text-subtle are the three ink tiers, and --neutral is the intent, not a ramp rung — it sits on the ramp here because it has to belong to the same family.

In light, the paper is nearly achromatic and the chroma climbs all the way to the ink: the darkest text is the most tinted thing in the palette. In dark it inverts — the ink goes to a flat near-white and the temperature moves into the paper and the borders, peaking at --border — the last rung before the ink.

That is why a dark theme is not a light theme with the lightness reversed. Both schemes are authored separately, as light-dark() pairs in the same declaration.

bun run report:neutral-ramp prints these figures for every preset, plus the lightness a tint costs at equal contrast. It is a survey, not a gate: leaving the trend is a legitimate palette decision.

Angles are OKLCH, the space report:neutral-ramp reports in — they do not match the HSL numbers written in the theme sources, and the strip above is built in OKLCH so a marker lands on the colour it names.

As measured here, ocean straddles: its neutrals sit a few degrees either side of the primary, and the shadow ink is pushed about 30° beyond all of them. sunset fans out in one direction: the primary is the reddest thing in the palette and every neutral lies further toward amber, with the shadow ink tucked in between. Two different answers to the same question.

Either way the relationship is a coordination, decided once by the theme author and recorded in the theme's own values. Nothing in the core derives a neutral or an intent from --primary at runtime.

Simultaneous contrast does the work in the first case: a neutral card on a cool ground makes the ground read cooler, without a single blue pixel in the card. "Never use pure white" is a rule of thumb, not a law — what matters is that the ramp around it belongs to one family.

A stored --primary-subtle would be one colour against one assumed background. This one resolves against the surface it is actually sitting on, in whichever island, in whichever scheme — twelve results above from three declarations.

It reaches the default .badge and .alert plus every explicit .soft, and nothing else — a component sitting on its own surface keeps its --border rim.

--shadow and --shadow-popout are derived from --shadow-color with color-mix(), on every theme boundary. A palette changes the ink once instead of restating a shadow list — and it is free to place that ink outside its own primary's hue, as figure 03 shows.

Two levels, not three. A hero card that wants more is an application decision, not a missing global token.

Intents are curated pairs in each theme's own values, not mechanical derivatives of --primary. That is what lets ocean place success in a cool green and sunset place it in a warmer one while both keep meaning the same thing.

The second bar is a perfectly reasonable #f8fafc → #cbd5e1 lifted from a generic grey scale. On a warm canvas it belongs to nothing — the surface it sits on is the only thing that decides whether a gradient reads as part of the page or pasted onto it.

The preset also re-runs the recipe over a darkened base for hover rather than reusing the resting fill, so the gradient shape survives the state change instead of flattening.

--hover-overlay is about four percent of ink. A button paints it as box-shadow: inset 0 0 0 999px over whatever fill it already has, so one token covers a solid, an outline and a table row without a hover colour per variant. The second chip above is that same recipe applied to --surface, which is the only way to see four percent at all.

--focus-ring is not authored: it is color-mix(in oklch, var(--focus) 30%, transparent), re-derived on every boundary. Override --focus and the ring follows; there is no stale second value to keep in sync.

accent-color is the one that catches people out. The checkbox and range above carry no Actual class at all — the browser paints them, and follows the island only because accent-color: var(--primary) is re-declared on every [data-theme]. It inherits as a computed value, so a single declaration at the root would paint every island with the root's primary.

Without data-theme, the default palette advertises color-scheme: light dark and follows the OS. A dark-only theme declares color-scheme: dark, a light-only one light. Browsers without light-dark() get the light fallback, which is why every preset states it first.

Theme-derived aliases — --shadow, --shadow-popout, --backdrop-fill, --selection-bg, --heading, --state-selected, --indicator-ring — are declared on :root, [data-theme] rather than on :root alone. A custom property resolves its var() references where it is declared, so an alias declared only at the root would be inherited already resolved and would ignore the island entirely.

data-theme is an active boundary on every element that carries it, never a place to park a value. A <option value="ocean"> or a hidden input holding a theme name wants data-theme-value or the control's own value — unless you actually want that element painted, which is exactly how a theme swatch is built.

A review heuristic, not a conformance test — and not the same thing as the contrast requirement. The alert keeps its border, its weight and its position; the three ink tiers keep their separation. Nothing here needed hue to be understood.

forced-colors: active is the other floor: the browser remaps colour, background and border to system colours, and the core supplies the handful of overrides the browser cannot infer — focus outline, selected and disabled states, the backdrop, and removing decorative shadows.

A small token set is a feature — every rung is one more thing a theme author has to get right, in light and in dark, for every island. The bar for adding one is evidence from real compositions, not symmetry with someone else's list.