Skip to content
Documentation

ADR-006: Color & Theming

Decision

Components reference semantic tokens only; public component APIs use semantic tone names. Color is organized in two token layers, and all theme authoring happens in one place.

Key rules

  • Components reference semantic tokens, never raw palette tokens, hex, or Tailwind palette numbers (text-gray-500, #6b7280).
  • Public component props use semantic tones only: info, success, warning, danger, accent. Never teal / amber / purple in a shared component API.
  • Two token layers: palette (raw values) and semantic surface (contextual usage). Components consume the semantic layer.
  • Theme definitions live in one place (src/index.css); a new theme adds entries at both the palette and semantic layers.
  • Dark mode adapts through tokens ([data-theme]) — never conditionally swap class names.
  • The tone vocabulary is closed; propose additions to this record before using a new name.

Code patterns

/* Palette layer — raw values */
--primary: hsl(...);


/* Semantic surface layer — what components reference */
--surface-accent: var(--primary);
--surface-accent-foreground: var(--primary-foreground);

Why

Semantic tokens let themes, dark mode, and accent overrides work without touching component code. A palette name in a public API leaks an implementation detail that cannot be re-themed.

Applies when

You are choosing a color, defining a variant or tone prop, or adding a theme.

  • ADR-001 — design tokens.
  • ADR-004 — motion and interaction (state colors).