Design System Glossary

Token Tiers / Token Hierarchy

Home
/
Design Systems
/
Design System Glossary
/
Token Tiers / Token Hierarchy

Token tiers describe the layered structure of a design token system: how raw values climb toward meaning and specificity. Most modern systems follow three tiers: primitive/global tokens, semantic tokens, and component tokens.

Tier 1: Primitives — the raw materials. blue-500, space-16, font-weight-600. No context, no decision. Just values.

Tier 2: Semantic — meaning and purpose. color-action-primary, space-stack-lg, font-weight-bold. A primitive can map to many semantics (one blue-500 could be both color-link-default and color-action-primary in different contexts).

Tier 3: Component — scoped to specific UI. button-bg-hover, input-border-error, card-shadow. These live in component documentation or in code comments, often as component tokens.

Why tiers matter: if your components reach straight for primitives, theming breaks. If your component tokens reference primitives directly, a rebrand cascades everywhere. The semantic layer is the insulation — it decouples what a value means from what colour it is. Swap the semantics, and every component updates. Swap the primitives, and every theme updates.

Some teams add a fourth tier — local tokens scoped to a single instance or state — but the discipline gets harder. Three tiers is the sweet spot for most Design Systems.