The Token Mess
Everyone says they use design tokens. Few teams do it well. The typical implementation: a Figma file with some named colors, manually exported to CSS variables. No semantic mapping. No platform parity. No single source of truth. When the brand color changes, someone manually updates three codebases and misses a fourth.
The Three-Tier Architecture
Tier 1 - Primitives: Raw values. blue-500: #1F3FFF, space-4: 16px. These never appear in component code.
Tier 2 - Semantics: Intent-mapped aliases. color-action-primary: blue-500, space-component-gap: space-4. These are what components reference.
Tier 3 - Component: Scoped tokens. button-bg-primary: color-action-primary. These enable component-level theming without touching the semantic layer.
Why Naming Matters Most
We've seen more token systems fail because of bad naming than bad tooling. A token named card-shadow-medium works today. But what happens when you need a card shadow that's between medium and large? card-shadow-medium-large? That path leads to chaos.
Our naming convention uses a strict hierarchy: category-property-variant-state. Example: color-surface-elevated-hover. It reads like a sentence, scales predictably, and generates zero ambiguity.
Cross-Platform Token Distribution
We use Style Dictionary to transform our token source file (JSON) into platform-specific outputs: CSS custom properties for web, Swift asset catalogs for iOS, and XML resources for Android. One source, three outputs, zero manual sync.
Migration Guide
You don't need to rebuild your design system to adopt tokens. Start by auditing your existing CSS variables. Map them to semantic names. Add the primitive and component tiers over two sprints. The tooling (Style Dictionary, Figma Tokens plugin) handles the rest. Two sprints of setup. Infinite sprints of payoff.