Tokens Before Components: Build Your Design System in the Right Order

Starting with components creates inconsistency at scale. Start with tokens and foundations first, then build reusable components on top of stable system decisions.

Almost every design system kickoff I've ever observed starts in the same place. Someone, usually a senior designer, opens a Figma file and starts designing a button. Then a card. Then a modal. Within a fortnight there's a small library of components, a sense of momentum, and a quiet conviction that the system is well underway. Six months later, the same team is wondering why nothing scales: why every product surface needs a custom variant, why dark mode broke everything, why the component library feels like a museum nobody visits.

The reason is almost always the same. The team started with components when they should have started with tokens. Tokens are the boring foundation that makes everything above them possible. Skip them, and the components you build are just hardcoded screenshots of decisions you didn't fully think through. Build them properly, and the component library becomes a thin, almost trivial layer on top of a system that already does most of the work.

What tokens actually are

A token is a named, semantic decision about a single attribute: a colour, a spacing value, a font size, a border radius, a shadow depth. It's the smallest unit in a design system, and it's the most important. "Background-default" is a token. "Spacing-3" is a token. "Radius-medium" is a token. They sound trivial. They are not. The names you choose at this layer determine the vocabulary of every conversation your team will have for years.

Most teams underinvest here because tokens look like a tidying-up exercise. They feel less satisfying than designing a beautiful card. They produce nothing visible to a stakeholder. And so the work gets skipped, or done shallowly: three colours named after their hex values, a spacing scale based on whatever the first developer chose. Then the system tries to scale, and the cracks show up everywhere at once.

The two-layer token model that actually scales

The single most important architectural choice in any design system is to use a two-layer token model. The first layer is your raw palette: the actual values. "Blue-500: #4945FF." "Spacing-100: 8px." "Radius-200: 4px." These are descriptive tokens. They describe what the value is, not what it's for.

The second layer is your semantic palette: the meaning. "Action-primary: blue-500." "Spacing-card-inset: spacing-200." "Radius-button: radius-200." These are intentional tokens. They describe how the value is used. Components reference only the semantic layer, never the descriptive one. This sounds pedantic. It is the single decision that makes dark mode possible, that makes brand refreshes possible, that makes accessibility audits tractable.

If components come before tokens, drift is inevitable. Stable foundations create faster delivery, cleaner theming, and fewer expensive refactors later.

Why this order matters in practice

When we did the rebuild at LQID Bank, we resisted the urge to ship components for the first six weeks. The team was uncomfortable. Stakeholders were anxious. "Where are the buttons?" was asked more than once. We held the line. We shipped a tokens layer first, with semantic naming, full dark mode coverage, and accessibility-aware contrast pairs. By the time we started on components two months later, we built the first twenty in less time than it normally takes to build five, because every decision they encoded had already been decided at the token layer.

Better still, when the brand team came back six months later with a refreshed palette, we updated the descriptive layer in an afternoon and every component automatically picked up the change. No PRs to component code. No testing of fifty button variants. The brand refresh that would have been a quarter-long project at most companies took us less than a week. That's the dividend tokens pay, and it's a dividend you only get if you do the work in the right order.

The naming exercise that does most of the work

Most of the value of a tokens system is in the naming. Bad token names lock you into bad decisions; good ones make future change cheap. Here are the rules I use, refined across four design system projects.

  1. Descriptive tokens describe the thing: its colour family, its size, its scale position. "Blue-500" not "primary-blue."
  2. Semantic tokens describe the use: the role in the interface, not the visual property. "Border-subtle" not "border-grey."
  3. Avoid component names in tokens. "Button-primary-background" couples the token to the component; "action-primary" can be reused everywhere.
  4. Build pairs for contrast: every text token should have a paired background token it's guaranteed to be accessible against. Encode the relationship in naming.
  5. Plan for at least two themes from day one, even if you only ship one. The naming discipline is most of the work.

Spacing, radius, motion: the tokens nobody talks about

Colour tokens get all the attention. The other token families get neglected, and they shouldn't. Spacing tokens dictate the rhythm of every layout. Radius tokens dictate the personality of every surface. Motion tokens dictate how alive the product feels. If you don't tokenise these, every component will encode its own opinion, and the system will feel inconsistent in ways you can't quite articulate.

The teams I've seen ship the tightest design systems treat spacing with the same rigour as colour: a defined scale, semantic names for common roles ("page-margin," "inline-tight," "stack-loose"), and ruthless enforcement that components only reference these tokens. A linter is your friend here. A culture of "just this once we'll use a custom value" is how systems quietly die.

How to retrofit tokens onto an existing system

If you've inherited a design system that started with components and never properly built a tokens layer, you can fix it without burning everything down. The trick is to do it incrementally, surface by surface. Pick one component. Audit every value it uses. Promote each to a semantic token. Update the component to reference the token. Move to the next component. Within a quarter, most of the system can be retrofitted without disrupting product teams. The work isn't glamorous. The result is a system that suddenly behaves like one.

Tokens before components isn't a religious belief. It's the practical observation that systems built in this order survive change, and systems built in the other order calcify into expensive maintenance burdens. If you're starting a new system, start at the bottom. If you're maintaining an old one, start retrofitting it. Either way, the buttons can wait.

In short

Tokens create the stable foundation that lets components scale, adapt, and survive change. Starting with components first usually creates expensive rework later.

Practical checklist

  • Define token foundations (colour, type, spacing, elevation) first.
  • Map component variants back to token decisions.
  • Establish naming and governance before scale-up.
  • Pilot migration on one high-traffic journey.
  • Track drift and refactor cost to prove token-first value.

When to use this approach (and when not to)

  • Use this approach when decisions carry customer, revenue, or delivery risk.
  • Use it when multiple teams need consistent quality standards.
  • Use it when you need repeatable outcomes, not one-off output.
  • Do not seed components from one-off hex codes and informal spacing—freeze foundations first.
  • Do not try to tokenise every edge case in week one—anchor the families everything inherits from.
  • Do not let stakeholders confuse token work with visible UI progress—show the dependency chain.

When to break this rule

Break the tokens-first rule only for narrow exploratory spikes where speed of learning matters more than system integrity. Even then, set a clear deadline to tokenise before scaling the pattern across teams.

Frequently asked questions

Why start with tokens instead of components?

Tokens define foundational decisions like colour, spacing, and typography. Without them, components drift and scaling becomes expensive.

Can teams retrofit tokens later?

Yes, but it is usually slower and riskier. Retrofitting often requires broad refactoring across products, documentation, and implementation.

Can we adopt tokens after components already exist?

Yes, but plan a phased migration with clear priorities to avoid broad disruption.

What is the risk of skipping token governance?

Naming drift and inconsistent theming, which increase maintenance cost over time.

When can component-first be acceptable?

In small exploratory spikes, as long as tokenisation is scheduled before scale and cross-team reuse.