Token architecture: building a scalable token system
Learn

Token architecture: building a scalable token system

Author Avatar
Written by
Jun 15, 2026

Understanding what a design token is and how the three-tier hierarchy works is the necessary first step. The harder question (and the one that determines whether your token system is still working for you in two years) is how to structure that hierarchy in practice.

Token architecture is the set of decisions you make before you name anything: how many tiers to use, what deserves a token versus what should stay hardcoded, how to handle platform differences, and where to draw the boundary between shared and component-specific values. These are structural decisions, and structural mistakes are the most expensive kind to fix later.

This article walks through those decisions one by one. It's tool-agnostic and focused on the single-brand case. If your system needs to support multiple brands or themes from the start, Article 07 covers the additional architecture considerations that introduces.

How many tiers do you actually need?

Article 02 introduced the three-tier model: global tokens → alias tokens → component tokens. Three tiers is the right answer for most systems, but it isn't always the right answer, and treating it as a universal rule leads to either unnecessary complexity or the wrong kind of simplification.

When two tiers are enough

For small, focused systems (a single-platform product, an early-stage design system, a team of fewer than five) two tiers can be perfectly adequate. Global tokens establish your palette and scale; components reference them directly.

The cost of skipping aliases is theming flexibility. If you know your product will never need dark mode, multiple brands, or significant visual pivots, and you want to keep the system lightweight, two tiers is a defensible choice. Just be honest about the trade-off: you're optimizing for simplicity now at the cost of flexibility later.

When three tiers are the right answer

Three tiers make sense whenever:

  • Your product needs or is likely to need dark mode or theme switching
  • Multiple platforms (web, iOS, Android) consume the same token source
  • Your design language has distinct semantic roles that aren't captured by raw value names
  • More than a handful of people are making decisions about tokens

The alias tier is cheap to add upfront and expensive to retrofit. If any of the above apply to your situation, build in aliases from the start.

When you might go deeper

Some large enterprise systems add a fourth tier (often called a "brand" or "theme" tier) that sits between the global and alias layers. This is primarily a multi-brand pattern, where different brands can override the same set of aliases without changing the component layer. Article 07 covers this in detail; for the single-brand case, three tiers is almost always the right ceiling.

What to tokenize, and what to leave hardcoded

One of the most common architectural mistakes is tokenizing everything. Tokens have overhead: they need to be named, documented, maintained, and governed. A token that isn't being used by anything is a liability, not an asset.

The useful test is: will this value ever need to vary?

Values worth tokenizing share some or all of these properties:

  • They repeat across more than one component or context
  • They encode a design decision that has semantic meaning (not just a convenient number)
  • They might need to change in a future theme, rebrand, or platform output
  • They're a candidate for a documented constraint: something you want to enforce rather than leave to individual judgment

Values that are often better left hardcoded:

  • One-off layout dimensions that are structural rather than designed (a specific column width in a documentation template, for example)
  • Magic numbers used to align a single, specific element
  • Values that are genuinely implementation details rather than design decisions

An example: your icon size of 24px is a design decision that applies across dozens of components: tokenize it. The 3px you're nudging a specific illustration by to optically center it in a card: leave that hardcoded.

The discipline isn't "tokenize everything you might ever want to change." It's "tokenize values that represent repeatable, communicable design decisions."

Global vs local scoping

Every token in your system is either globally scoped (available to any component or context) or locally scoped to a specific component.

Global tokens

Global tokens form the shared foundation of your system. Your color palette, spacing scale, type scale, radius values, shadows, and motion tokens all live here. They're available everywhere, and they're the single source of truth for your design language's raw materials.

The risk with global tokens is drift. Over time, teams add values to the global scale that aren't truly global. A specific shade added to satisfy one component's needs ends up in the palette alongside the intentional scale values, and the scale loses coherence. A practical guard against this: new global token values should require explicit review and sign-off, not just be added on demand.

Local (component) tokens

Component tokens are scoped to a single component. They reference global or alias tokens, and they exist to give the component an explicit, named override point.

The right time to introduce component tokens is when a component has design decisions that are meaningfully distinct from what the shared alias layer expresses. A button's padding might reference the global space-4 directly without needing a button-padding token. But if your button's background has a hover state, a pressed state, a disabled state, and a destructive variant (each with distinct color logic), naming those decisions as component tokens makes the component's behavior explicit and independently adjustable.

Component tokens also act as a firewall. When a consuming team wants to customize a component for their context (a slightly different radius, a different background color), a well-designed component token layer gives them a sanctioned override point rather than forcing them to override raw CSS. This is particularly important for design systems with multiple consuming teams or white-label use cases.

A practical rule: start without component tokens and introduce them when you have a clear reason. Premature component tokens add naming overhead without adding flexibility.

Platform divergence: web, iOS, and Android

One of the strongest arguments for a token system is cross-platform consistency. But achieving that consistency requires making deliberate decisions about where platforms share tokens and where they diverge.

The shared foundation

Most design decisions are genuinely platform-agnostic: your color palette, your spacing scale, your type scale, your border radius values. These should live in a shared token source that all platforms consume. One value, many outputs.

Your transformation layer (Style Dictionary or equivalent) takes the shared JSON and produces platform-specific outputs: CSS custom properties for web, Swift constants for iOS, XML resources for Android.

Where platforms legitimately differ

Some token values need to differ by platform for good reasons:

Typography: Font size and line height values that look right on web often need adjustment for native platforms. iOS and Android have different baseline grid conventions, and system font rendering differs. You may need platform-specific aliases that reference the same global scale but resolve to different values.

Spacing: Density conventions differ between platforms. Native mobile apps typically use larger touch targets and different whitespace rhythms than web interfaces. Alias tokens for layout spacing (space-layout-gap, space-component-padding) may resolve to different global values per platform.

Elevation and shadow: iOS and Android handle elevation differently at the OS level. Shadow composites may need platform-specific values even when the semantic intent (shadow-card, shadow-overlay) is shared.

Motion: Platform animation conventions differ significantly. iOS prefers spring-based motion; Android's Material Design has its own easing standards; web has its own norms. Motion tokens often need platform-specific values even when they share semantic names.

How to structure platform divergence

The cleanest approach is to keep the global tier platform-agnostic and handle divergence at the alias tier. Platform-specific alias files override only the values that need to differ, inheriting everything else from the shared base.

tokens/
  global/           # Shared across all platforms
    color.json
    spacing.json
    typography.json
  alias/
    base.json       # Shared semantic aliases
    web.json        # Web overrides
    ios.json        # iOS overrides
    android.json    # Android overrides
  components/       # Shared component tokens

This keeps the override surface small and explicit. A reviewer can look at ios.json and see exactly what differs on that platform. They don't have to diff an entire token system.

Designing for change

A token architecture should be designed with the assumption that things will change: new components will be added, the visual language will evolve, new platforms will be onboarded, and occasionally a rebrand will arrive.

A few structural habits that make systems more resilient to change:

Keep the alias tier honest: Alias token names should describe roles, not values. color-surface-primary ages well; color-white-background does not. When the surface color changes in dark mode, a role-based name stays accurate.

Don't expose raw values through aliases unnecessarily: If an alias token just restates a global token with a different name and no semantic purpose (brand-blue: blue-500), it adds a layer without adding meaning. Every alias tier token should answer the question: why does this value have this role?

Leave room in your scale: When building a spacing or type scale, avoid sequential integers with no gaps (space-1, space-2, space-3). They leave nowhere to go when you need a value between two existing steps. Two approaches extend more gracefully: name tokens after their actual values (space-4, space-8, space-16, space-32) so a new space-12 always has a logical home, or use T-shirt sizes (space-xs, space-sm, space-md, space-lg) which are easier to read but harder to extend predictably. Most systems opt for value-based naming at the global tier and T-shirt sizes at the alias tier.

Document architectural decisions: When you make a deliberate choice (using two tiers instead of three, keeping iOS spacing values separate, choosing not to tokenize a particular category), write it down. Future contributors (including future you) will make better decisions when they understand the reasoning behind what's already there.

Common mistakes

Premature abstraction: Creating deep alias hierarchies before you understand which decisions actually need semantic names. Over-engineered systems are harder to onboard, harder to maintain, and often have to be partially dismantled as the real usage patterns become clear. Grow the hierarchy in response to real needs.

Token sprawl: Adding tokens reactively, one at a time, in response to component needs rather than from a considered scale. Over time this produces a palette with 200 slightly-different grey values, a spacing system with arbitrary gaps, and no coherent structure that anyone can reason about.

Missing aliases: Building a large, detailed global scale but never adding a semantic layer. Components reference raw values directly (blue-500, space-4), and the system loses the ability to theme, branch by platform, or communicate design intent.

Inconsistent scoping: Some components have detailed component token layers; others reference aliases directly; others still have hardcoded values. Inconsistency makes the system unpredictable for consumers and makes governance harder. Choose an approach and apply it consistently, even if that means some components have slightly more structure than they strictly need.

Treating architecture as permanent: Token architecture is a living thing. The decisions that are right for a two-person team in year one will need revisiting at year three. Build with the expectation of evolution, and document decisions so that changes are informed rather than accidental.

What comes next

With the structural foundations in place, the next practical question is naming. How you name tokens (the conventions, the patterns, the things to avoid) determines whether your architecture is navigable by the people who need to use it.

Article 05 — Naming your design tokens picks up directly from here with a practical guide to naming conventions across all three tiers.

If you're thinking ahead to supporting multiple brands or themes from a single token system, Article 07 — Multi-brand, multi-product and white-label token architecture covers the additional structural layer that introduces.

Author Avatar
Try zeroheight
The design systems platform that keeps teams and agents in sync
Start for free
Share this post