The atomic layer underneath every well-built design system

A design token is a name given to a visual decision. Instead of a designer specifying 'use #1A73E8 for primary actions' and an engineer hardcoding that hex value into a stylesheet, a token called `color.action.primary` holds that value — and every component, across every platform, references the token instead of the raw value.

Tokens cover the full range of visual decisions:

• Colours (brand, semantic, neutral, feedback)
• Spacing (margins, padding, gaps)
• Typography (font sizes, weights, line heights, letter spacing)
• Border radii, shadows, z-index levels, and motion timing

The concept was formalised by Salesforce through their Lightning Design System and has since become the shared vocabulary across every major design system platform — Figma, Style Dictionary, Theo, and the emerging W3C Design Tokens specification.

CSS variables are a developer implementation detail. Design tokens are a shared contract between design and development that exists before any implementation happens.

The difference matters at scale. If a designer changes a colour in Figma and a developer updates a CSS variable, those two changes need to be manually coordinated — and there's nothing stopping them from drifting. Tokens introduce a single source of truth that flows from one place into both Figma libraries and production code.

For teams working across platforms — web, iOS, Android — CSS variables only cover one of those surfaces. Tokens are platform-agnostic. The token `spacing.md` has a value of `16px` on web, `16pt` on iOS, and `16dp` on Android. One decision, three correct implementations, no coordination overhead.

Here's a concrete example of why this matters.

Your product uses a specific shade of blue for all interactive elements — buttons, links, selected states, focus rings. That blue is hardcoded in 47 places across your codebase. Your brand team decides to shift the primary colour during a rebrand.

Without tokens: An engineer hunts through 47 instances, misses three, ships with inconsistencies, and the QA cycle takes twice as long as expected.

With tokens: One value changes in the token file. Every surface that references `color.interactive.default` updates automatically. The rebrand ships in an afternoon.

This isn't a hypothetical — it's why companies like GitHub, Google, and Adobe built their entire design systems on token infrastructure. The upfront cost of naming and structuring tokens pays back compounding returns every time a visual decision changes.

You don't need to rebuild your {{LINK:design-system}} to start using tokens. The practical entry point is a token audit:

1. Identify your most-used visual values — primary colour, background colours, base spacing unit, type scale
2. Name them semantically (`color.text.primary`, not `color.gray900`) so the name describes usage, not the raw value
3. Create a token file (JSON, YAML, or natively in Figma) that maps names to values
4. Start referencing tokens in new components and refactor existing ones incrementally

Semantic naming is the step most teams skip. If you name your tokens after their appearance rather than their role, you lose the abstraction that makes them useful. `color.blue500` tells you nothing about when to use it. `color.action.primary` tells you exactly when to use it and makes it trivial to swap the underlying colour later.

Our {{INTERNAL:/services/design-systems}} work almost always starts with a token audit — even for teams that think they don't have a design system yet.

Design tokens aren't a nice-to-have for mature design systems. They're the mechanism that makes a design system maintainable over time. Without them, your system is documentation plus screenshots. With them, it's a live, enforceable contract between design and engineering.

The question isn't whether tokens are worth implementing. It's whether you want visual consistency to be a manual process that depends on everyone remembering the rules, or an automated one that enforces them by default.

Related: {{LINK:design-system}}, {{LINK:ux-debt}}