04 — Token System
Token Architecture
Section Overview
What This Is
The Token System formalises design intent as named, typed, versioned data. A three-tier hierarchy — Primitive, Semantic, Component — with strict downward-only derivation rules.
Why It Exists
Direct value literals in component declarations produce specifications untranslatable across themes and platforms. The Token System interposes a named, purpose-bearing layer between raw values and component consumers.
How It Works
Primitive tokens declare raw values. Semantic tokens assign purpose. Component tokens scope purpose to a component. Reference direction is strictly downward. The compiler resolves full token chains during Transform.
References flow downward only · Cross-tier aliasing is a compile-time error · Max alias chain depth: 3 hops
The three-tier model enforces separation: raw values (Primitive), purpose (Semantic), scoped consumption (Component).
The token system is organised in three tiers: Primitive, Semantic, and Component. Each tier has defined derivation rules, reference constraints, and governance implications. Lower tiers may not reference higher tiers. Forward references within or across tiers are compile-time errors. The token system is the foundational data layer of IDL — all component declarations consume tokens, never raw values.
Why Three Tiers
A flat token system produces two failure modes: tokens that carry both raw values and purpose (making them hard to theme) and tokens that are too abstract to map directly to component needs (requiring ad-hoc overrides). The three-tier model separates these concerns: Primitive tokens hold values, Semantic tokens assign purpose, Component tokens scope purpose to a component. Each tier is independently overridable for theming without touching adjacent tiers.
Tier Summary
| Tier | References | Referenced By | Scope |
|---|---|---|---|
| Primitive | Nothing | Semantic tokens only | System-global |
| Semantic | Primitive tokens | Component tokens | System-global, theme-aware |
| Component | Semantic tokens | Component declarations | Scoped to one component |
Token Governance
Primitive and Semantic tokens are governed at the system level — changes require RFC review and are recorded in the changelog. Component tokens are governed at the component level and may be modified as part of a component version increment without a system-level RFC. This boundary clarifies what constitutes a system-level change versus a component-level change in design system governance.