Most token implementations fail not because of technology, but because of structure. Without a taxonomy, you produce redundancy and inconsistency. The right architecture determines whether a token system works equally well with 50 or 5,000 tokens.

The 3-Tier Model

The established architectural pattern distinguishes three tiers that build upon each other:

Tier 1: Primitive Tokens define raw values – the complete palette of all available values. They are descriptively named: color.blue.500, spacing.16, font.size.24. Primitive tokens are never used directly in components.

Tier 2: Semantic Tokens (also alias tokens) give primitives functional meaning: color.action.primary: {color.blue.500}. They describe the purpose, not the value. This is the decisive architectural advantage: when the brand color changes, one semantic token is rewired – all components follow automatically.

Tier 3: Component Tokens bind semantics to concrete UI elements: button.primary.bg: {color.action.primary}. They enable component-specific theming without breaking global semantics.

Aliasing Strategies

Aliasing is the heart of token architecture. A token references another token instead of a concrete value, creating reference chains: button.primary.bg → color.action.primary → color.blue.500 → #2563EB.

The optimal aliasing depth is two levels: Component → Semantic → Primitive. Three levels is the maximum. More levels make the system opaque and hard to debug.

Naming Conventions

The CTI schema (Category-Type-Item) has become the standard: color.background.page, spacing.inset.medium. Token names describe function, not values: color.border.subtle not color.gray.300. Token names avoid platform-specific terms.

Anti-Patterns

Too flat: All tokens on one level, no hierarchy. Too deep: Five levels of aliasing for a simple color value. Missing semantics: Primitive tokens directly in components. Inconsistent naming: Mixed schemas in one system.

Tier
Purpose
Example Name
Example Value
Primitive
Raw values / Palette
color.green.500
#72D36F
Semantic
Contextual meaning
color.feedback.success
`{color.green.500}`
Component
Component-specific
button.primary.bg
`{color.action.primary}`

Multi-Brand and Multi-Theme

The 3-tier model enables multi-brand setups: Primitive tokens remain identical across all brands. Semantic tokens are overridden per brand. Component tokens stay identical – components automatically work with every brand. Dark mode follows the same principle.

Key Takeaways

  • The 3-tier model (Primitive → Semantic → Component) is the architectural standard for scalable token systems.
  • Aliasing depth of maximum two levels keeps the system debuggable.
  • Token names describe function, not values – color.border.subtle not color.gray.300.
  • Missing semantics makes every rebrand a mammoth task.
  • Multi-brand and dark mode rely on the same principle: override semantic tokens, keep the rest stable.