Designing tokens for a calm, legible UI

Our components never name a colour. They ask for a role — surface, foreground, line, primary — and the theme decides what that role looks like in light and in dark.

Three layers

• A raw palette: the brand values, used nowhere directly

• Semantic roles that point into the palette

• Utilities like bg-surface and text-foreground-muted

:root {
  --role-surface: var(--palette-neutral-0);
  --role-primary: var(--palette-primary-600);
}

:root[data-theme='dark'] {
  --role-surface: var(--palette-neutral-950);
  --role-primary: var(--palette-primary-300);
}

Status is never colour alone

Every status badge pairs a tone with a word. A colour-blind reader, a screen reader and a printed page all get the same information.