Skip to content
Documentation

ADR-001: Design Tokens

Decision

All color, radius, typography, and spacing values are CSS custom-property tokens. Tokens are the single source of truth; component CSS references tokens, never raw values.

Key rules

  • Every color, radius, typography, and spacing value is a CSS custom property — never a hardcoded hex, px, or palette number.
  • Token names are the source of truth; components reference tokens, not raw values.
  • Radius follows the xl / lg / md / sm scale — live values in ADR-002; no intermediate values.
  • Type families resolve to the system font stack at the token layer; no brand web fonts (see ADR-003).
  • Changing a token value is a change to this record.

Why

Tokens are what make theming, dark mode, and accent overrides work without touching component code. A raw value in a component is a value that cannot be re-themed.

Applies when

You are adding, renaming, or changing any design token — color, radius, spacing, or typography.

  • ADR-002 — radius and shape (owns the live radius values).
  • ADR-003 — typography and density.
  • ADR-006 — color and theming.