Three-Tier Design Tokens

Design decisions are encoded as CSS custom properties in three tiers, where each tier consumes only the tier above it:

Primitive  →  Semantic  →  Component

• Primitive — raw values (--color-dark-blue-500, --space-4). Consumed only by semantic tokens.
• Semantic — meaning (--color-bg, --color-accent-hover). Consumed only by components. Never holds a raw value — always var(--primitive).
• Component — local (--btn-bg), declared on the component selector, with a semantic fallback so callers can override (--btn-bg: var(--color-accent)).

Hard rule: primitives never appear directly in a component. If no semantic token fits, add one — don't reach for a primitive, and never drop a magic number into a component rule.

Why three tiers: the split decouples raw value ↔ meaning ↔ usage. Change a brand color once at the primitive level; reskin by remapping semantics; override one component without touching the global scale. Each axis of change has exactly one place to edit.

Source: css-conventions skill §1–2.