ADR-006: Color & Theming

Field	Value
Type	Skill Resource
Source	~/.copilot/skills/adr/references/adr-006-color-and-theming.md
Description	Not specified

Source Content

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.

Related

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