Foundations
Colour
Colour roles are semantic, so a role says what the colour is for, not what it looks like. The names match a widely used convention (shadcn/ui), which makes off-the-shelf component kits easy to plug in, but nothing depends on that kit.
Light (no chroma)
| Role | Value | Use |
|---|---|---|
background |
oklch(1 0 0) |
Page |
foreground |
oklch(0.145 0 0) |
Text |
card / popover |
oklch(1 0 0) |
Panels and menus. These lift with shadow, not with a fill change |
primary |
oklch(0.205 0 0) |
The single primary action. Near-black |
muted |
oklch(0.97 0 0) |
Passive surfaces: group headers, skeletons, icon tiles |
accent |
oklch(0.955 0 0) |
The item you are on (selected or focused). A step and a half deeper than muted |
muted-foreground |
oklch(0.556 0 0) |
Secondary text, labels, icons at rest |
border / input |
oklch(0.922 0 0) |
Hairlines |
ring |
oklch(0.708 0 0) |
Focus ring, at 50% |
destructive |
oklch(0.577 0.245 27) |
Delete, errors |
sidebar |
oklch(0.985 0 0) |
Navigation area, a shade off white |
Dark (a cool cast)
Every neutral carries a hint of blue (chroma about 0.005, hue about 260). Dark themes with no chroma look like dead grey, and this small bias gives the dark theme its character. Elevation is a lightness ladder: background 0.16 → card 0.196 → popover 0.23. Borders are white at 9%, so one value works on every surface. Selection (0.275) is lighter than muted, because on a dark page lighter reads as nearer.
Status
The recipe is the same for every status: a 15% tint of the hue as the fill, and a deep shade of the same hue as the text. Dark mode keeps the fill and lifts the text to a light shade, because a deep shade on a 15% tint can't be read on near-black.
| Token pair | Meaning |
|---|---|
status-success-* (emerald) |
Done, passed, healthy, low risk |
status-warning-* (amber) |
Needs attention, medium risk |
status-danger-* (rose) |
Failed, broken, high risk |
status-info-* (sky) |
In progress, waiting. Add a pulsing dot when it is live |
status-neutral-* (muted) |
Pending, cancelled, stopped |
Rules:
- A deliberate user action is never red.
- Status is never shown by colour alone. There is always a text label.
- Warning banners use
banner-warning-*: a pale amber background, an amber hairline and dark amber text.
Deliberately dark surfaces
Floating toolbars over content, and terminal-style readouts, use
deliberate-dark in both themes. That is a choice, not a missing dark
variant.
Component tokens
A few roles differ in kind between light and dark, not just in value, so they get their own tokens. This keeps every dark-mode decision inside tokens.css: --control-bg, --control-bg-hover, --control-border (outline buttons), --field-bg, --field-bg-disabled (inputs), --ghost-hover, --destructive-tint, --destructive-tint-hover, --segment-active-bg, --segment-active-border (tabs), --focus-ring and --invalid-ring.