22 min di lettura
The power of design tokens: one change, a whole new app
How a well-built design system of primitives, semantic tokens and themes turns a redesign into a one-line change.
In questa pagina
Picture this. Your team is building a new dashboard for a client. Five monthsOne week, a handful of developersagents, dozens of screens. Everything ships on time. Then someone puts the screens next to each other.
The yellow of the warning banner on the orders page is not exactly the yellow on the home page: one is #F5B400, the other is #F4B300, and a third screen uses #F7B731. The "Save" button is fully rounded on one screen, a little rounded on another, and square on a third. One page uses 16 points of space between blocks, the next one uses 12, and a third one mixes 4, 8 and 20. Each choice looks fine alone. Together, the product feels a little wrong, and nobody can say why.
Nobody really made a mistake. Every developer opened the design file, read the values in the inspector and typed them into their component: a hex code here, a corner radius there, a margin that looked more or less right. Do that with a few people, a few agents and dozens of screens, and the small differences grow fast. To fix them now, you must open every component, one by one, and hope you find them all.
Problem: consistency The problem is not the people, developers or designers. And it is not local: every single screen looks fine. The problem is global: every value was decided again in every place where it was used, and nothing kept the whole product consistent.
I know what you're thinking:
Not us. Our designers give us clean specs, we review every pull request, and our AI agents have guardrails for every color and spacing.
OK, maybe your first version really is pixel-perfect. But consistency on day one is only half the story. The other half comes later: when the brand changes, or when you just want to try something new.
Problem: change Now a second scenario. The dashboard is done. You see it complete for the first time and something feels wrong: too cold, too busy, not really the brand. You want a softer palette, rounder corners, more white space. How do you do it? Every color, radius and margin is inside a component, so every change means you work on every screen again. Experiments are almost impossible: to try three palettes, you must rebuild the app three times.
Both stories have the same solution: design tokens. In my experience, they are the part of a design system that gives you value first. A complete design system is a much bigger project, and we will talk about it later. Tokens are where you start.
Step one: name your values
So let's do the obvious thing. We don't type #F5B400 in one banner and #F4B300 in the next one. We decide every value once and give it a name: yellow500, teal700, radius10, radiusFull, space16. Components stop using raw values and use the names instead.
Now let's try an experiment: we set yellow500 to orange. One change, in one place.
Solved: consistency Every yellow in the app changes with it. Three yellows become one, and with radiusFull the three button shapes also become one.
Achievement unlocked
Level 1: primitives
You just built the first layer of a design token system. These raw values with a name are called primitives.
What primitives are
Primitives are the raw values that your product can use, and their name says what they are. Most of them are colors. Each color comes as a ramp: a row of shades from light to dark, with a number for the lightness. So yellow100 is pale and yellow900 is dark. Next to the colors there are a few corner radii, a spacing scale and the fonts.
Think of a paint shop: a primitive is a color sample. It doesn't know which wall it will go on.
The list is short on purpose. A short list also blocks mistakes: if #F4B300 is not in the list, nobody can use it.
Step two: give every value a job
Primitives fix consistency. But they also bring two new problems, and the orange experiment already showed you the first one.
Problem 1: The name lies
After the experiment, the token is still called yellow500, but now its value is #F2711C.
The name says what the color is, so when the color changes, the name is wrong. You have two options. You keep a "yellow" that is orange, and you explain it to every new person in the team. Or you rename it to orange500 everywhere it is used, and that is exactly the to-do list we wanted to avoid.
Problem 2: One color, many jobs
Let's undo the experiment: yellow500 is yellow again. A few weeks later the brand team asks:
Can the main buttons be teal?
Easy, you think. The buttons use yellow500, so you change yellow500 to teal. One line, done.
Brief: make the main buttons teal
yellow500 = #F5B400
The buttons are teal. But look at the whole dashboard again:
Brief: make the main buttons teal
primitive: yellow500 = #0D6B57 (teal)
The warning banner, the "pending" badge and the highlighted bar in the chart also use yellow500, so now they are teal too. Nobody asked for that, and a warning must still look like a warning. The only other option is to open every button and replace yellow500 with teal700 by hand: the to-do list again.
So we add one more layer. The name of a semantic token says what a color is for, not what it looks like. Each one points to a primitive:
actionPrimarythe color of the main action
used by buttons, the selected menu item
statusWarninganything that needs attention
used by warning banners, pending badges
dataHighlightthe bar a chart wants you to look at
used by the highlighted bar in a chart
surfaceCardthe background of a card
used by cards
The theme decides where each name points. Change it here, and no component notices.
Solved: both Now each request is a change to the theme, never to a component.
Orange instead of yellow? Add orange500 and point the three tokens to it. No semantic token has "yellow" in its name, so no name becomes wrong.
Your turn: point the three yellow tokens to orange500
Drag the round handles on the right. Components and token names never move.
Only the buttons teal? Point actionPrimary to teal700. The buttons and the selected menu item change; warnings and charts stay yellow.
Your turn: make only the buttons teal
Drag the round handles on the right. Components and token names never move.
Look at what happened on our dashboard. The orange rebrand moved three arrows; the teal buttons moved one. We didn't open a single component, and no name became wrong.
Brief: make the main buttons teal
yellow500 = #F5B400
Achievement unlocked
Level 2: semantic tokens
This second layer is semantic tokens. In my experience, it is where a design system gives you the most value.
Design tokens, defined
Put the two steps together and you have the whole idea: you make each decision once, you give it a name, and every screen uses the name, not the value.
"#F5B400" is a value. "The color of a warning" is a decision. When the decision has a name, the orders page and the home page can't be different anymore, because they both ask for the same token. The name comes from Salesforce, where Jina Anne and Jon Levine's team used it for its design system around 20141. Today tokens also have a shared format: the W3C Design Tokens Community Group published the first stable version of its specification in October 20252.
Why it works: two sets of links
Think of your app as a map of arrows, in two separate sets:
- Components point to semantic tokens. The button asks for
actionPrimary, the warning banner asks forstatusWarning. You set these links once, when you build the component. - Semantic tokens point to primitives.
actionPrimary→yellow500. This layer of links is the theme.
The two layers are independent. So to change the look of the app, you only change the second layer:
Three layers
Token systems are often described in three layers, and each layer is built on the one before it:
- Primitives: the raw palette and scales, named by what they are:
yellow500,radius10,space16. - Semantic tokens: the same values, named by what they're for:
actionPrimary,statusWarning,cornerCard. This is the level components use. - Component tokens: the decisions of one component, for example
button.primary.background. Some big systems, like Material 3, use them a lot; in my experience, most apps don't need them at the start. I explain why below.
The big systems use the same levels, with different names. Material 3 calls them reference, system and component (md.ref.palette.primary40, md.sys.color.primary, md.comp.filled-button.container.color)3. Brad Frost numbers them Tier 1, 2 and 34. Adobe Spectrum and GitHub Primer have their own version.
Defining good semantic tokens
Primitives are easy: choose the colors, number the shades, done. Semantic tokens are the real design work, because every name is a promise about how it will be used. This is how I do it, in four steps.
Step 1
Start from the interface, not from the palette
Open your main screens and make a list of everything that has a color. You will find the same things again and again:
- the page background and the cards
- primary and secondary text
- borders
- the main action
- the status colors: good news, bad news, warnings
This list is your first draft. In my experience, most apps start with about twenty semantic colors, plus a few tokens for corners, spacing and type.
Step 2
Name each one, from general to specific
Nathan Curtis wrote a widely quoted article about naming tokens5. The idea is simple: a name goes from general to specific, and you only use the levels you need.
| Level | Question it answers | Examples |
|---|---|---|
| Category | what kind of value? | color, space, corner, font |
| Element | what does it paint or measure? | background, text, border, icon |
| Role | what is it for? | action, surface, status |
| Emphasis | which one among similar ones? | primary, secondary, subtle |
| State | when? | hover, pressed, disabled |
Here are some example names built with these levels. In a big system you write the full path. In a small app, some parts are obvious, so you remove them (crossed out below). The short name is what is left.
- color.background.action.primary→
actionPrimarythe fill of the main button - color.background.action.primary.pressed→
actionPrimaryPressedthe same button while you press it - color.text.onAction.primary→
onActionPrimarythe label on that button - color.text.secondary→
textSecondarythe date under a title - color.border.status.critical→
borderCriticalthe red border of a field with an error - color.background.surface.card→
surfaceCardthe background of a card - corner.control→
cornerControlthe corners of buttons and text fields
Why can you drop them? color is obvious when the token is in a list of colors. background is obvious for an action or a surface, because they are always fills. Keep a part only if two tokens need it to be different. A text and a border can both be "critical", so textCritical and borderCritical keep it.
Step 3
Check the names against seven habits
Many big systems follow most of these habits (not all: Spectrum, for example, chains aliases). A simple test: after a redesign, the names on the right are still true. The names on the left are not.
| Habit | ✗ Avoid | ✓ Prefer |
|---|---|---|
| Name the purpose, not the look | blueButton, lightGray | actionPrimary, surfaceCard |
| Pair every surface with what sits on it | primary on its own | primary + onPrimary |
| Put the element first | criticalText, criticalBorder | textCritical, borderCritical |
| Pick one emphasis scale | light, soft, faded | muted, default, emphasis |
| States go last | hoverActionPrimary | actionPrimaryHover |
| Semantic tokens point straight to a primitive | statusWarning → actionPrimary → yellow500 | statusWarning → yellow500 |
| Stop when names are distinct | colorBackgroundActionPrimaryDefault | actionPrimary |
Three of these habits need a few more words:
-
Pair every surface with what sits on it. Every fill gets a partner token for the text and icons on top of it. For example, the main button:
actionPrimary→yellow500(#F5B400): the fill of the button;onActionPrimary→gray900(#1C1C1E): the color of its label.
You choose the two together and check their contrast together. Dark gray on this yellow has a contrast of 9.2:1, easy to read. White on the same yellow has 1.8:1, and nobody can read it. Without the pair, someone will put white text on the button one day. Material 3 does this for all its main colors:
primaryandonPrimary,surfaceandonSurface6. -
Put the element first.
textCriticalandborderCriticalboth start with what they paint. When you color a text, you typetextand you only see text colors, so you can't pick a border color by mistake. Shopify's Polaris does the same: its red text color is--p-color-text-critical, where--pis only the Polaris prefix and then comescolor,text,critical7. -
Pick one emphasis scale. Decide once which words mean "stronger" and "weaker", for example
muted,default,emphasis, and use only those. If one person writeslight, anothersoftand a thirdfaded, nobody knows if they are the same color. GitHub's Primer usesmuted/default/emphasis8; Apple useslabel/secondaryLabel/tertiaryLabel9.
Step 4
Spell it the same way in every tool
The name is the same everywhere; only the punctuation changes: action/primary in a design file, actionPrimary in Swift or Kotlin, --color-action-primary in CSS. Same decision, same name, three spellings.
Themes: a different one, a whole new app
So far we changed one color at a time. Now put it all together: primitives, semantic tokens, and components that only know the semantic names. And not only colors: corners, spacing and type can be semantic tokens too. In my proof of concept, type tokens are based on the system text styles, so if the user picks bigger text in Settings, your text gets bigger too.
Solved: change This is the key idea: a set of semantic tokens, each one linked to a primitive, is a theme. Nothing more. Change the links and you get a different app, without touching a single component.
This is the proof of concept I built for this series: one screen, four themes. Try the switches too.
Semantic tokens
- actionPrimary
- → gray900
- surfaceCard
- → gray100
- cornerCard
- → radius20
- fontBody
- → fontSystem
What themes are good for
When a theme is only a set of links, many big projects become small ones:
- Redesign or rebrand. A new look is a new set of links. You can even try three versions side by side before you choose one.
- Light and dark mode. Every theme has two sets of links, one for light and one for dark. Light or dark is one choice, the theme is another, and you can mix them freely.
- One app, many brands. A white-label product can ship one theme per client, with the same components.
- Personalization. Let users choose an accent color: only
actionPrimaryand itson-pair change. Android goes further: since Android 12, dynamic color can build an app's colors from the user's wallpaper10. - Accessibility. A high-contrast theme points the same tokens to stronger shades, for users who turn on Increase Contrast11. A legible theme changes only the type tokens, for example to Atkinson Hyperlegible, a free font from the Braille Institute designed for readers with low vision12.
Besides the four themes, the figure shows three more of these: light and dark, an accent you can choose, and the legible font. They all work with every theme, because they are only more links.
The bigger picture: tokens in a design system
At the start I said that a complete design system is a much bigger project. Now that tokens are clear, we can see where they fit in it.
Tokens are the first part of this definition: the decisions, written in a form that both designers and code can use. Everything else is built on them:
- Components use only semantic tokens, so they get every decision automatically.
- Guidelines say which token to use where.
- People decide when a new token is needed, and when an old one should go.
Many products don't have all of this written down. They have an implicit design system: in a design file, in the heads of a few people, and in hundreds of slightly different values in the code. Tokens are the easiest place to start making it explicit.
If you think in Atomic Design, tokens are the layer under the atoms: Brad Frost calls them subatomic particles14. Atoms, molecules and organisms use semantic tokens. Pages only combine them, and they never create a new color or radius.
The secret third layer
So far we built two layers: primitives, the raw values like yellow500, and semantic tokens, what each value is for, like actionPrimary. There is a third one. I named it once, in the three layers above, and then I kept quiet about it on purpose.
It's called the component token. Most apps don't need it, so I kept it for the end. Instead of starting with a definition, let's find the one problem that needs it.
The brief. Remember the teal buttons from step two? The selected menu item turned teal with them, because both use actionPrimary. Now the brand team writes again:
Keep the buttons teal, please. But the selected menu item goes back to yellow.
First try: use actionPrimary. It can't do it. The button and the menu item use the same token, so they always change together: point it to teal700 and both are teal, point it back to yellow500 and both are yellow.
Brief: teal buttons, the selected menu item stays yellow
change actionPrimary → teal700
Second try: add a semantic token. We add actionPrimaryButton and point it to teal. It works today. But only the button uses it, so it isn't a shared decision: it's a token for one component, hidden among the semantic ones. And it never stays alone. Next month another component needs its own exception, then another, then another:
- actionPrimaryshared
- statusWarningshared
- dataHighlightshared
- surfaceCardshared
Every new exception adds one more token to the shared list.
The solution: component tokens
We need a lever that only the button has: a token that belongs to the button and to nothing else. That is a component token. The button asks for button.primary.background, and by default this points to actionPrimary, so nothing looks different. For the new brief, the theme moves only this link, to teal700. The menu item still uses actionPrimary, so it stays yellow.
Brief: teal buttons, the selected menu item stays yellow
override button.primary.background → teal700
That's the third layer. Semantic tokens are decisions that many components share; component tokens are the decisions of one component.
Where does a component token live? With its component, not in the shared list.
- Semantic tokens live in one shared list. Any component can use them.
- Component tokens are local to their component. Only the button uses
button.primary.background, so it is defined together with the button: in a design file, in a group of variables just for the button; in code, inside the button component.
Local doesn't mean closed. By default the component token points to a semantic token, and a theme can still move that one link, like our teal button. So with a component token, a theme can move one extra link; components themselves still never change. The rest of the app never sees it.
Why I keep it secret
Why didn't I tell you at the start? Because most apps don't need component tokens.
They solve one problem: changing one component without touching the others.
- In one product, made by one team, this is rare.
- In a big system that many products theme in their own way, like Google's Material 3, it happens every day.
So a small app pays a cost every day (I'll show it in a moment), and gets the benefit once in a while.
What is the cost? A component token doesn't replace a semantic token. It adds one more name in front of it:
One extra name is fine. The problem is that it's never just one. The button doesn't only have a background. It has:
- 4 properties: background, label, border, radius;
- 3 variants: primary, secondary, tertiary;
- 3 states: normal, pressed, disabled.
4 × 3 × 3 = 36 component tokens, for one button. And almost all of them only repeat a semantic token: button.primary.label → onActionPrimary, button.primary.radius → cornerControl, and so on.
Now do the same for every component. In my experience, you end up with a few hundred names to choose, document and keep in sync, and you override maybe five of them.
What do I suggest? Grow the third layer only when you need it:
- Start with two layers. Components use semantic tokens directly.
- One component needs its own lever? Add one component token, only for that property. Our teal button needs
button.primary.background: one token, not 36. - About three components need the same exception? Then it isn't an exception anymore. It's a shared decision, so make it a semantic token, named by purpose (for example
actionEmphasis), not by component.
This is close to what Nathan Curtis recommends: start inside the component, and promote a token only when other components need it5.
Big systems make different choices, and each one makes sense for its size:
| Approach | Who does it | When it fits |
|---|---|---|
| A component token for most properties | Material 33 | a system that many products theme |
| Component tokens, but as few as possible | Adobe Spectrum15 | a large system that wants to stay readable |
| Base, functional and component tokens | GitHub Primer8 | you want to change one component without adding shared tokens |
| Start inside the component, then promote across components | Nathan Curtis5 | systems that grow with the product |
| Two layers, no component tokens | many teams, says Figma's guide to token architecture16 | one product, whole-theme changes |
Achievement unlocked
Design tokens: complete
Primitives, semantic tokens, themes: you have the whole system. One change, a whole new app.
In short
If you remember only four rules from this post, remember these:
- Screens and components use only semantic tokens (or, rarely, their own component token). No primitives, no hex values, no random numbers for radii.
- Semantic names say what a value is for, not how it looks.
actionPrimary, notyellowButton. A good name is still true after a redesign; if it isn't, the name is wrong. - Every background has its
on-foreground. Check the contrast of the pair, in every theme. - A theme is a different set of links. Never a copy of the components.
AI prompt to check your tokens
Reading about tokens is one thing; knowing the state of your own app is another. Here is this whole article as a prompt. Paste it into your AI coding agent from the root folder of your project, and you get an assessment of your tokens.
Further reading
Primitives and palettes
- Tailwind CSS colors
- Radix Colors, understanding the scale
- IBM Carbon, Color
- Adobe Spectrum, Colors
- Material 3, how the color system works
Naming and layers
- Nathan Curtis, Naming Tokens in Design Systems
- Andreas Kutschmann, Design Token-Based UI Architecture
- Material 3, Color roles
- Atlassian, Design tokens explained
- GitHub Primer, Token names
- Figma, Design token architecture
History and standards
- Brad Frost, The history of themeable user interfaces
- W3C Design Tokens Community Group, Design Tokens Technical Reports 2025.10
Next up: the same system built with Figma variables, then in SwiftUI.
Note
-
The W3C Design Tokens Community Group credits the Salesforce team and "Jon & Jina" with the name in the abstract of its 2025.10 report. Salesforce's token tool Theo dates from February 2014. Brad Frost tells the story in The history of themeable user interfaces (2025). ↩
-
W3C Design Tokens Community Group, Design Tokens specification reaches first stable version (28 October 2025). The report itself notes it is a Community Group report, not a W3C Standard. ↩
-
Material Web, Theming: component tokens map to system tokens, which map to reference values. Token overview: m3.material.io. ↩ ↩2
-
Brad Frost, The many faces of themeable design systems and Creating themeable design systems. ↩
-
Nathan Curtis, Naming Tokens in Design Systems: namespace, object, base and modifier levels; start tokens within a component, then promote them across components. ↩ ↩2 ↩3
-
Android Developers, Color roles and
ColorScheme:primary/onPrimaryand the other on-pairs. ↩ -
Shopify Polaris, Version 11 tokens guide, archived copy from December 2024. The original page now redirects to Shopify's developer docs. ↩
-
GitHub Primer, Token names: base, functional and component tokens, with names such as
fgColor-defaultandfgColor-muted(fgColoris foreground color, the color of text and icons). ↩ ↩2 -
Apple Developer Documentation, UI element colors:
label,secondaryLabel,tertiaryLabel,systemBackground,separatorand the other semantic system colors, which adapt to Dark Mode. ↩ -
Android Developers, Dynamic color: introduced in Android 12, it lets users personalize the color scheme from their wallpaper. ↩
-
Apple Developer Documentation,
colorSchemeContrast: the contrast between foreground and background colors,standardorincreased. ↩ -
Braille Institute, Atkinson Hyperlegible: a free typeface designed to improve legibility for readers with low vision. ↩
-
Nielsen Norman Group, Design Systems 101: a design system as a repository (style guide, component library, pattern library) plus the people who manage it. ↩
-
Brad Frost, Atomic Design, chapter 2, and Design Tokens + Atomic Design (2025), where tokens are the subatomic layer under the atoms. ↩
-
Adobe Spectrum, Design tokens: semantic tokens are the main way tokens are consumed; component-specific tokens are kept to a minimum. ↩
-
Figma Resource Library, Design token architecture. ↩
Serie · 3 parti
Design token, dall'idea al codice
Un design system in tre passi: l'idea, lo stesso sistema in Figma e lo stesso sistema in SwiftUI.
- 1The power of design tokensLo stai leggendo
- 2Lo stesso sistema in Figma, con le variabiliIn arrivo
- 3Lo stesso sistema in SwiftUIIn arrivo