04 — Token System
Primitive Tokens
Primitive tokens are raw value declarations with no semantic meaning attached. They are the foundation of the token system — the layer that holds actual values. A primitive token gives a raw value a stable name and type, enabling it to be referenced by semantic tokens without the semantic layer caring about the underlying value.
Characteristics of Primitive Tokens
- Primitive tokens carry no purpose. color.blue.500 is a color; what that color means in the interface is the semantic layer's responsibility.
- Primitive tokens MUST NOT be referenced directly in component declarations or component-tier token definitions.
- Primitive tokens are system-global — they are declared once and available across all modules.
- Primitive token names follow a category.scale naming convention: color.blue.500, spacing.4, radius.sm, duration.200.
- Primitive token values are raw: hex, pixels, milliseconds, unitless numbers.
Primitive Token Categories
| Category | Type | Scale Convention |
|---|---|---|
| color.* | Color | Hue name + numeric lightness step (50–950) |
| spacing.* | Dimension | Numeric scale (1–16, corresponding to base-unit multiples) |
| radius.* | Dimension | Named steps: none, sm, md, lg, full |
| shadow.* | Composite | Named steps: sm, md, lg, xl |
| duration.* | Duration | Named steps: instant, fast, base, slow, deliberate |
| font-size.* | Dimension | Named scale steps: xs through 2xl |