If your team is still copying hex values between Figma files, hardcoding spacing in CSS, and syncing color updates by hand ? you're not running a design system. You're running a design illusion. Design tokens fix this. But the way most teams implement them creates as many problems as it solves. This post covers a token architecture that actually scales.
What Design Tokens Actually Are (and What They're Not)
A design token is a named, platform-agnostic design decision stored as data. That's it. color.brand.primary is a token. #6C5CE7 is not ? that's a raw value. The token is the name that points to the value, and that indirection is what makes tokens powerful.
Where teams go wrong: they treat tokens as a fancy variable system. A flat list of named colors and spacing values that you export once, then never touch. That's not architecture ? that's renaming CSS variables and calling it a design system.
The Three-Tier Token Model
The architecture that scales follows a strict three-tier hierarchy. Each tier has a specific job, and tokens only reference tokens one tier above them ? never skipping levels.
Tier 1: Primitive Tokens (Global / Base)
These are your raw palette ? every possible value the system will ever use. No semantics, no context. Just named values.
color.purple.500 = #6C5CE7color.gray.100 = #F5F5F5spacing.4 = 16pxfont.size.md = 16px
Primitives never appear directly in components. They exist only to be referenced by the next tier. This is non-negotiable ? violating it destroys the system's refactorability.
Tier 2: Semantic Tokens (Alias / Decision)
Semantic tokens give intent to primitives. They describe what a value means in context, not what it looks like. This tier is where theme switching (light/dark, brand A/brand B) happens.
color.background.surface = {color.gray.100}color.interactive.primary = {color.purple.500}color.text.default = {color.gray.900}
When you switch to dark mode, you remap semantic tokens to different primitives. The component code never changes ? it always reads color.background.surface. The system resolves it to a different hex. This is the entire mechanism behind proper theme support.
Tier 3: Component Tokens (Scoped)
Component tokens scope semantic values to specific UI elements. They're optional ? but valuable on large teams where components need independent overrides without breaking the global system.
button.background.primary = {color.interactive.primary}button.text.primary = {color.text.on-interactive}button.padding.horizontal = {spacing.4}
Tooling in 2025: The Stack That Works
The W3C Design Tokens Community Group spec has stabilized enough that tooling is now solid. Here's the stack most production teams are running:
Tokens stored in JSON following W3C spec ? portable, tool-agnostic
Figma Variables as the design-side source of truth (synced via Tokens Studio or native API)
Style Dictionary for transforming raw token JSON into CSS custom properties, TypeScript constants, iOS Swift, or Android XML
Git as the sync layer ? token changes go through PRs, are reviewed, and trigger automated builds
The moment your tokens live in Git and get built through CI/CD is the moment your design system becomes infrastructure ? not documentation.
Figma-to-Code Sync: What Actually Works
Figma Variables (introduced in 2023, matured in 2024) map directly to the three-tier model. Primitive collections, semantic mode collections, and component-scoped overrides are all natively supported.
The practical workflow: designers update token values in Figma ? Tokens Studio (or a custom Figma plugin using the Variables REST API) exports changes as a JSON diff ? a GitHub Action runs Style Dictionary ? updated CSS/TypeScript drops into the component library. The whole pipeline runs in under 90 seconds with no manual file editing.
Where this breaks: teams that use Figma styles instead of variables for their token layer. Styles don't have the aliasing capability needed for proper semantic tokens. If you're still on styles, migration is worth the effort ? the delta in maintainability is massive.
Naming Conventions That Don't Break at Scale
Token naming is where most systems quietly collapse. After three months, no one can remember whether the token is btn-primary-bg or primary-button-background or color-bg-btn. The pattern that survives: category.concept.variant.state.
color.background.surface.defaultcolor.background.surface.hovercolor.text.feedback.errorspacing.component.gap.md
This structure reads left-to-right from broadest to most specific. It autocompletes predictably in IDEs, sorts cleanly in any token UI, and makes the intent obvious to both developers and designers.
Multi-Platform Output: One Source, Every Target
The real payoff of a token architecture built on W3C-spec JSON is platform-agnostic output. Style Dictionary transforms the same source into:
CSS custom properties for web
TypeScript constants for typed component props
Tailwind config extension (using CSS vars as the source)
React Native StyleSheet values
Swift UI asset catalog entries for iOS
For agencies and product teams shipping across web and mobile simultaneously, this is where the architecture pays for itself. A single brand update propagates everywhere in one build. No cross-team color sync meetings. No "which blue is the right blue" Slack threads.
Common Mistakes Worth Skipping
Skipping semantics entirely. Primitives in components = system that breaks on theming.
Too many tiers. Four or five layers of aliasing creates resolution hell. Three tiers is the ceiling.
Tokens without governance. Without a clear process for adding new tokens (who approves, when a new token is warranted vs. using an existing one), token sprawl degrades the system within months.
Treating tokens as a one-time export. If tokens aren't living in a pipeline that syncs continuously, they'll drift out of sync and erode trust.
When to Invest in This vs. When Not To
This architecture is the right investment when: you have 2+ platforms sharing a visual language, you're maintaining a component library across teams, or you're building a product that will need white-labeling or multiple themes.
It's overkill when: you're shipping a single-platform MVP with one designer, one theme, and no ambitions to scale the design system beyond the current team. In that case, CSS custom properties with clear naming conventions is sufficient. Build the full pipeline when you hit the scaling pain ? not before.
A design system is software. It needs the same engineering discipline as the products it serves ? versioning, testing, CI/CD, and governance. Tokens are its data layer.