Themes

The skies

A theme is a palette and an atmosphere. Each tile sets its own data-theme and runs the real <Atmosphere> inside it — live canvas, not an image. Components stay flat on top: the sky is the page's ground, never a surface's skin, which is how 37 components keep their contrast guarantee.

Readability is not left to taste. Every scene is drawn over its theme's --ground and then veiled with it again, so a pixel can travel at most intensity × alpha from the page's base colour. check-atmosphere.mjs recomputes that worst case from the same numbers the canvas draws with and fails the build if body text drops below 4.5:1 — or if a sky is so veiled it has become invisible. Stars are the one exemption: sub-2px point lights are not backgrounds, so they are capped by radius instead of by contrast.

The palettes

Each tile paints itself with literal values from the token export, so every theme is visible at once regardless of which one is active.

Every semantic token, every theme

Components reference only this table, never a primitive. The four surface tokens are what replace an elevation ramp — depth is a step on the neutral scale plus a hairline, not a shadow. That is why each ramp has eleven steps.

Note what Night Aurora does with status colours: every one of them flips -ink to near-black, because the lifted variants are too bright to carry white text. A flat token system can't express that without hardcoding a different pairing per component.

The contrast gate

The build checks 20 pairs per theme — 100 in total — and refuses to emit if any text pair falls below 4.5:1. Translucent layers are composited first, so a tinted badge is measured against the tint over its real surface rather than against the ideal colour.

Its first run on this palette rejected ink-faint at 2.46:1 — placeholder text at the 400 step of the ramp. Placeholder text is still text, and that failure is one of the most common real accessibility defects in shipped software. Moving to the 500 step fixed it.

Adding a fourth

A new key under themes in tokens.json, then pnpm tokens. No component changes, because no component has ever referenced a primitive. The theme menu picks it up too — its list comes from generated metadata, not a hand-maintained array.

"themes": {
  "$order": ["horizon", "storm", "aurora", "highnoon"],
  "highnoon": {
    "$label": "High Noon",
    "$scheme": "light",
    "ground": "{primitive.color.white}",
    "ink":    "{primitive.color.cool-950}",
    "accent": "{primitive.color.steel-700}",
    ...
  }
}