Themes

How theming is layered

Color is organized in two tiers. Keeping them separate means a new theme only redefines roles — it never touches the palette or any component.

Tokens are category-first: --color-text* (foreground), --color-bg* (backgrounds & surfaces), --color-border*, --color-icon*, plus four status intents (success / warning / error / info) and --color-primary. The light theme is the single source of truth; a small set of base value-holders (--background, --primary, …) sit behind the aliases so light/dark can swap one value — don't consume those directly.

Darken & lighten on the fly

The palette is a fixed 50–950 ramp. When you need a shade that isn't on it — a hover one notch darker, a tint one notch lighter — derive it with CSS relative colors in OKLCH, where lightness is perceptually uniform. The shared step helpers in color-scheme.css name the conventional amounts.

/* one notch darker for a hover state */
.button:hover {
  background: oklch(
    from var(--color-primary)
    calc(l - var(--shade-darken-2)) c h
  );
}

/* a subtle tint of any role color */
.badge {
  background: oklch(
    from var(--color-info)
    calc(l + var(--shade-lighten-3)) c h
  );
}

Step helpers: --shade-darken-1/-2/-3 and --shade-lighten-1/-2/-3 (lightness deltas, subtle → strong). Relative color syntax requires Chrome/Edge 119+, Safari 16.4+, Firefox 128+.

Using semantic tokens

.card {
  background: var(--color-bg-surface);
  color: var(--color-text);
  border: 1px solid var(--color-border);
}

.card__meta {
  color: var(--color-text-secondary);
}

.alert--error {
  background: var(--color-bg-error);
  color: var(--color-text-error);
  border: 1px solid var(--color-border-error);
}

Text

Foreground colors for text and labels. Default text plus a de-emphasis scale, an on-fill color for text over strong/colored backgrounds, links, and per-status text.

Background & surface

Backgrounds for the page and components, with hover / active / selected states, a muted surface, inverse surfaces for primary actions and nav, and soft per-status surfaces.

Border

Borders and dividers: standard, subtle hairlines, a stronger rule, the focus outline, and per-status borders.

Icon

Neutral icon colors. Status icons reuse the --color-text-{status} tokens; icons on a strong fill use --color-icon-on-fill.

Status & intent

Four intents — success, warning, error, info. Each has a solid vivid fill plus the text/surface/border tokens above. Use the solid for bold fills (dots, badges) and the -on-fill token for text/icons on top of it.

Primary & interactive

Primary action color and its on-fill foreground, plus the secondary/accent aliases.

Sidebar

Surface and text tokens for the app shell navigation.

Avatar accents

Accent fills for avatars without an image, keyed off the palette.

Overlays

Translucent black for scrims, shadows, and subtle fills. Number = opacity percent.

Visualization

Data-viz hues, each with a primary (bold) and secondary (tint) for charts and graphs.

Notes

• Components consume only --color-* tokens — never the raw palette (--volcanic-ash-* etc.) and never the base value-holders.
• For muted text use --color-text-muted; --color-bg-muted is a near-white surface, not a text color.
• Status icons reuse the --color-text-{status} tokens; there is no separate status-icon family.
• Inverted ≠ dark theme. The --color-text-inverse* / --color-icon-inverse* tokens are for content on a dark/inverse surface (a dark panel, nav, or inverse button) — which happens in light theme too. They pair with --color-bg-inverse and flip automatically in dark theme. Components use the inverted prop, not a theme switch.
• Dark mode is class-based (.dark) and driven entirely by themes/dark.css — components carry no per-element dark overrides.