011 min
The problem design tokens solve
When Jina Anne joined Salesforce, the first project was a small productivity app for tasks and notes, built by a team with three designers. Anne designed its web app, its marketing site, its Android app and its iOS app. For the web, Anne could build the buttons and type styles in code and hand over working code.
For the Android and iOS apps, Anne could not write the code, so the hand-over was redline specs: drawings that give every spacing, font size and colour on a screen, so an engineer can build it.
Each app had many screens, and many screens had extra versions for each state, such as what a screen shows after a tap. The specs were saved to Dropbox and explained in a wiki. When a colour or a size changed, every affected spec had to be found and redrawn by hand.
The deeper cost sits in the code. In a setup like this, the web stylesheet, the Android files and the iOS code each store the same colour as a separate literal value. Nothing links the copies. Over time they stop matching, and nobody reading the code can tell which value was the intended one and which was a close guess.
Anne's answer was to stop writing values into specs and code at all, and to write each one once, as data.
021 min
Where design tokens come from
The idea of design tokens came from a side project. On the open-source Sass website, Anne kept colours, type and spacing in a YAML data file. A script read that file and produced both the style guide and the Sass variables, so contributors never had to update the two by hand.
In Anne's own account, showing that setup to the Salesforce team is where design tokens began, and the team then built a tool called Theo to do the conversion. Jina Anne and Jon Levine described how design tokens worked in Salesforce's Lightning Design System in a talk in 2016. Lightning was used by Salesforce's own teams and also by the partners and customers who built their own apps on Salesforce.
There is no research paper behind design tokens and no measured law. They are practitioner convention: a working method that one design team made public and that other teams copied because it removed the same repeated work.
032 min
How design tokens work
Every design token has two parts: a name and a value. The name says what the decision is for. The value is the raw data: a colour, a size, a duration. The tokens sit in one source file, usually JSON or YAML, that no product reads directly. Teams call this file the single source of truth, meaning the one place where a value may be changed.
A build tool reads that source file and writes one output per platform. The web gets CSS custom properties or Sass variables. Android gets XML resource files. iOS gets code in the form its developers use. Product code then refers to the name from its own output. A web button says it uses the primary text colour, and never says #000000.
At Salesforce this mattered beyond its own teams. Developers wrote Java, React, Angular and PHP, inside Salesforce and at partner companies. Each group received the same decisions in the format its own stack expected.
Why the token build step does more than copy values
Platforms do not write the same value the same way. A transparent colour, for example, is an eight-digit hex code on Android and an RGBA value on the web. So the build tool converts each value for each platform. Theo splits the job into two parts: transforms, which convert each value, and formats, which write the output file. A designer edits one value and never types the Android or web syntax by hand.
One token change, three platforms
The payoff shows when a value is wrong. When a colour failed a contrast check, Anne changed it once, and the Android, iOS and web teams got the new value the next time they pulled the latest tokens. No team had to be told about the change. No one had to search their code for the old value.
042 min
The three tiers of design tokens
One flat list of design tokens works until a product needs a second theme. Then one name, such as the default text colour, must hold a dark value in one theme and a light value in another.
Most mature systems handle this with three tiers, and each tier points at the one below it. Adobe's Spectrum design system publishes a clear example:
| Tier | What it holds | Example from Spectrum |
|---|---|---|
| Primitive (also called global) | The raw values the system allows | blue-900 is rgb(59, 99, 251); spacing-100 is 8px |
| Semantic | A purpose, pointing at a primitive | accent-content-color-default points at accent-color-900 |
| Component | A decision for one component only | tooltip-maximum-width |
Primitive tokens say almost nothing about where to use them, so Spectrum's guidance is to reach them through semantic tokens. Semantic tokens carry the meaning: accent-content-color-default is for text that should stand out. A token that points at another token, instead of holding a value, is called an alias.
How a design token theme switch works
The tiers are what make dark mode one change instead of thousands. Components refer to semantic names. Semantic names point at primitives. Spectrum lets one token name hold a different value in the light theme and in the dark theme. To switch themes, the system changes which primitive each semantic name points at. No component changes, because no component ever named a primitive.
Why Spectrum keeps component tokens rare
The third tier can grow without limit. If every button, card and tooltip gets its own colour and padding tokens, the token list becomes as long as the stylesheet it replaced. Adobe's Spectrum keeps component tokens rare and tells teams to use reusable semantic tokens first. A component token is worth adding when one component has a need that no shared purpose covers, such as the maximum width of a tooltip.
051 min
How to name design tokens
Tiers only help if people can find the right design token, and that depends on its name. Atlassian, the company behind Jira and Confluence, builds each token name from up to three parts:
- Foundation: the kind of style, such as color, elevation or space.
- Property: the part of the interface it applies to, such as text, background, border or icon.
- Modifier: any extra purpose, such as a role, an emphasis or an interaction state. Not every token has one.
So color.icon.success is the colour for an icon that reports success, and color.text, with no modifier, is the default body text colour.
Name the purpose, not the appearance:
color.icon.success, notgreen-600.
A name like green-600 describes how the token looks today. A name like color.icon.success says where it belongs, and it stays true after a redesign changes which green is used. Numbered names are still right for primitives. Spectrum's spacing-100 is simply the 8-pixel step on its spacing scale, because a primitive's only job is to be a value.
062 min
How design tokens show up in real products
Atlassian is the clearest applied case of design tokens today. It uses one set of token names for its light, dark and high-contrast themes. Its guidance also lists themes that are not about colour: compact or comfortable density, reduced motion and custom type styles. A developer writes color.text once, and the active theme decides the value. When Atlassian changes its visual style, the change is made once in the tokens, not by finding and replacing hard-coded values across every app.
Salesforce's Lightning Design System shows the cross-platform side: one token source feeding web, Android and iOS teams and outside partners. Spectrum shows the tiers. All three publish their token names, so anyone can check them.
Choosing a design token because the colour matches
The most common misuse happens in teams that already have tokens. Take an illustrative case. A developer on a project-tracking app needs a green line under a chart. They search the token list, find color.icon.success, see the right shade of green and use it. The light theme looks correct. Later, the design team changes the success colours in the dark theme so icons stay readable on a dark background. The chart line changes too, even though it never meant success.
Atlassian's guidance warns against exactly this: choose a token by its meaning, not by its value. A value that matches in one theme may not match in another. The fix is a token whose name matches the job, such as a chart or border colour, even when its value is the same today.
071 min
Design tokens and colour contrast
Design tokens help accessibility in one direction and can hurt it in another. They help because a fix reaches every screen at once, as the Salesforce contrast fix did. WCAG 2.2 Success Criterion 1.4.3 Contrast (Minimum) sets 4.5:1 as the lowest contrast ratio allowed between normal text and its background. Readers with low vision are the people who need that ratio most. When a text token fails it, one change to the token fixes every screen that uses it.
Contrast belongs to a pair of design tokens
Tokens can also hide a failure, because contrast is not a property of one token. It is a property of two: a text colour and the background behind it. A text token can pass in the light theme and fail in the dark theme, because its background partner changed value. A high-contrast theme adds a third set of pairs to check.
So check pairs, theme by theme. Write down which background tokens each text token is allowed to sit on. Then test each pair in every theme before a release.
082 min
Design tokens vs. CSS variables and design systems
Two other things are often confused with design tokens: CSS custom properties, often called CSS variables, and the design system that tokens belong to. The axis that separates them is scope: where the decision lives and who can use it.
| Design tokens | CSS custom properties | Design system | |
|---|---|---|---|
| What it is | Named design decisions in a platform-neutral source file | A browser feature for reusable values inside CSS | The full set of components, guidance and code a team shares |
| Where it works | Any platform, through a build step | Web pages only | Across a product's design files and code |
| How they relate | One layer of a design system | One common output of tokens on the web | Contains tokens, components and documentation |
Design tokens are not just variables
The most common question about tokens is why they need a new name at all. Anne has said the confusion comes from teams that only describe tokens as Sass or CSS variables. A variable lives inside one codebase. A token is the decision plus the process around it: one source file, a build that writes each platform's format, and tiers that say how the decision is shared. On the web a token often becomes a CSS custom property, so the two look the same in a browser. They differ in where the decision is owned.
092 min
How design tokens became a shared standard
As more companies adopted design tokens, each tool stored them in its own way, and a token file from one tool did not open in another. Amazon's Style Dictionary, an open-source build tool, does the same job as Theo with its own file shape. A team that changed tools had to convert its token files.
The W3C Design Tokens Community Group formed to agree on one file format, and Anne co-chaired it with Kaelig Deloumeau-Prigent. On 28 October 2025, the Design Tokens Community Group published the first stable version of its specification, numbered 2025.10. The format is JSON. Each token has a $value, a $type can sit on the token or on its group, and a token can point at another token by writing that token's path in curly braces. A composite token groups values that are always used together, such as the colour, offsets and blur of one shadow.
Style Dictionary, Tokens Studio and Terrazzo were named as reference implementations. Figma, Sketch and Penpot were among the design tools listed as supporting the format or adding support for it.
How a design token reference gets its type
The format also settles a question that tools used to answer differently: what type is an alias? When a token's value is a reference, the format gives it the type of the token it points to. So if accent-content-color-default points at a colour, it is a colour, and every tool reads it the same way. The format also tells tools never to guess a type from what the value looks like.
The standard does not change the method Anne's team described in 2016. It makes the source file portable, so a team can change its design tool or build tool without rewriting its tokens.
102 min
Applying design tokens
The Salesforce problem was many copies of one decision, and applying design tokens means removing those copies. These moves do it, in order of payoff:
Take an inventory.
List every colour, font size, spacing value and shadow in your code and design files. Expect near-duplicates, such as several greys a few shades apart.
Collapse them into primitives.
Keep one value per real step on each scale, such as one type scale for font sizes.
Add semantic names
for the decisions people make every day: text, background, border, success, danger. Point each one at a primitive.
Pick a build tool
that reads one source file and writes every platform's format. Style Dictionary and Theo both do this, and the 2025.10 format keeps the source portable between tools.
Replace hard-coded values one component at a time
, starting with colour, because colour is what themes change.
Version the token package
and publish a short change note with each release, so product teams know which values moved and can plan the update.
When one global set of design tokens is not enough
Platforms differ, and a token set that ignores those differences gets bypassed. Salesforce handled this by giving every product one global token set that it could change or add to for its own context. Allow overrides, but keep them in the token source, so each exception is visible and reviewed.
When design tokens are not worth the cost
A single web app with one theme and a small team can get most of the benefit from CSS custom properties and a short naming rule. The build step, the tiers and the review process cost real time. Tokens repay that cost when a second platform, a second theme or a second brand arrives.
111 min
How to spot design tokens going wrong
Even with design tokens in place, the copies can come back. These signs can be checked in code, in design files or in the bug queue:
- Raw hex codes or pixel values in component code that equal a token's value.
- Components that use primitives such as
blue-900directly. They will not change when the theme changes. - Two tokens with different names and the same value, used for the same purpose.
- A dark-theme bug where an unrelated element changed colour along with a status colour.
- A design file and the code showing different values for the same token name, which means one side is not reading the source.
- A token list that gains several new tokens with every new component.
?5 questions
Questions people ask
Do design tokens replace a style guide?
Who owns design tokens, designers or developers?
Can design tokens store motion and animation?
How many design tokens should a system have?
Do I need a paid tool to use design tokens?
§9 sources
Sources
Drew McLellan and Jina Anne, “Smashing Podcast Episode 3 With Jina Anne: What Are Design Tokens?”, Smashing Magazine, November 2019.
Robin Rendle, “What Are Design Tokens?”, CSS-Tricks, 3 April 2019.
Salesforce UX, “Theo”, open-source repository.
Style Dictionary, open-source repository.
Show all 9 sourcesShow fewer sources
Adobe, “Design tokens”, Spectrum design system.
Atlassian, “Design tokens explained”, Atlassian Design System.
W3C, “Understanding SC 1.4.3: Contrast (Minimum)”, WCAG 2.2.
Kaelig Deloumeau-Prigent, “Design Tokens specification reaches first stable version”, W3C Design Tokens Community Group, 28 October 2025.
Design Tokens Community Group, “Design Tokens Format Module 2025.10”.