Design tokens are the contract between design and code
Custom properties were defined on 28.6% of mobile pages in the 2021 Web Almanac, but almost none reference another value. That missing alias layer is the difference between variables and design tokens.
Contents
- Key takeaways
- What a design token is, precisely
- Three tiers, from primitive to component
- Naming is where token systems fail
- What the W3C community group is standardizing
- Accessibility decisions belong in the semantic tier
- What breaks when the token layer is skipped
- FAQ
- Define the tiers before the first component
A design token is a named, machine-readable value holding one design decision: a color, a spacing step, a type size. Design tools and code then read the same source. Tokens work in three tiers — primitive values, semantic roles that point at them, and component names that point at the roles.
Key takeaways
- The 2021 Web Almanac found CSS custom properties defined on 28.6% of mobile pages and 28.3% of desktop pages, so the mechanism is already widely deployed.
- Almost none of those values are aliases: nearly a third reference another custom property one level deep, and values two levels deep are close to absent.
- After a WordPress core entry, the most common custom property names are literal colors:
--red,--blueand--green, at 7.2% each. That is a primitive tier used as a semantic one. - The W3C Design Tokens Community Group published its first public editor's draft on 23 September 2021, aiming at a format design tools and build tools can share.
What a design token is, precisely
CSS has had the mechanism since 3 December 2015, when the W3C published Custom Properties for Cascading Variables Level 1. Author-defined properties cascade, inherit, and are substituted with var().
A token is not the same as a variable, though it usually compiles into one. A variable is a value with a name. A token is a decision with a name, stored outside any one platform. The same decision can then be emitted as CSS, as an iOS constant, as an Android resource, or inside a design tool.
The W3C Design Tokens Community Group aims to provide technology that products and design tools can rely on when sharing the stylistic pieces of a design system at scale. Its first public editor's draft appeared on 23 September 2021 (W3C).
Three tiers, from primitive to component
The primitive tier holds raw values with descriptive names: color-orange-500, space-4, font-size-3. It has no opinion about usage.
The semantic tier names roles and references primitives: color-action-primary points at color-orange-500. This is where brand decisions live.
The component tier covers the few places a component needs its own hook, such as button-primary-background. Most systems need far fewer of these than teams expect, and each one is another line to maintain.
The payoff is arithmetic. Change one primitive and every screen that inherits it changes. A rebrand touches one file instead of four hundred. It is the same logic behind treating a logo as a compressed carrier of meaning rather than a drawing.
Naming is where token systems fail
The web already shows what happens without a semantic tier.
In the 2021 Web Almanac, custom properties were defined on 28.6% of mobile pages. Among the pages that use them, the most common names after a WordPress core property are literal colors:--red,--blueand--green, each at 7.2% (HTTP Archive, 1 December 2021).
A property called --red is a primitive pretending to be a role. The first time the brand replaces red with terracotta, every --red in the codebase becomes either a lie or a rename across the whole repository.
Three naming rules survive contact with real projects. Name by role, not by appearance. Put the category first and the modifier last, so names sort into groups. Never encode a value in a name: --blue-600 on a warning state is worse than an unnamed hex code.
What the W3C community group is standardizing
The gap the group works on is interoperability. A token file written for one build tool usually needs translating before another tool or a design application can read it, and translation is where systems drift.
A shared format does not decide your naming or your tiers. It decides whether the file survives a change of tooling. That matters for the same reason digital transformation is an operations problem: the artifact outlives the tool that produced it.
Accessibility decisions belong in the semantic tier
Contrast ratios are properties of pairs, not of single colors. If the token system only names colors, every designer and developer re-checks contrast by hand on every screen. If it names pairs — a background role and the text role approved against it — the check happens once, where the pair is defined.
WCAG 2.1 sets a minimum contrast ratio of 4.5:1 for normal text and 3:1 for large text. User interface components and graphical objects needed to understand content also require 3:1 (W3C, 5 June 2018).
What breaks when the token layer is skipped
Without tokens, the design file and the codebase are two independent copies of the same decisions, and copies diverge. The symptoms repeat across projects: six greys that were meant to be three, a dark mode two quarters late, and a rebrand quoted as a front-end rewrite. Nobody can list where the old color is used.
None of that shows during the first build, which is why it surfaces at handover. Define the token layer while the identity is still being drawn, during the stretch between audit and handover. It is then paid for once, whichever architecture the site runs on.
FAQ
What is the difference between a design token and a CSS variable?
A CSS variable is a value with a name inside one platform. A design token is a design decision stored in a platform-neutral file, from which the CSS variable, the iOS constant and the Android resource are all generated. The token is the source; the variable is one output.
How many tiers does a token system need?
Three is enough for almost every product: primitive, semantic and component. Two works for a small site with one theme. Four or more usually means the semantic tier was named badly and a compensating layer was added on top of it.
Do tokens replace a design system?
No. Tokens are the value layer underneath components, documentation and usage rules. A token file without documented components produces consistent colors on inconsistent interfaces. That is a smaller problem, not a solved one.
Who should own the token file?
One named person, with changes reviewed like any other code. Shared ownership reproduces the drift tokens were introduced to prevent, because the cheapest way to ship a screen is always to add one more value.
Define the tiers before the first component
Write the primitive palette, then the semantic roles with their approved contrast pairs, then only the component tokens a component genuinely needs. Put the file under review and name an owner. Six months in, the measurable answer is whether a color change touched one file or many.
