Semantic tokens explained
Naming values by purpose so themes just work.

Zander Whitehurst
9 min read
If primitive tokens are the palette, semantic tokens are the decisions about where each colour goes. They name values by purpose rather than appearance, and they are the reason a well built product can switch to dark mode, adopt a new brand or support a second product without anyone rewriting a single component.
I resisted semantic tokens for longer than I should have. They felt like an extra layer of naming for the sake of it. Then a client asked for dark mode two weeks before launch, and I spent a long weekend hunting through hundreds of hard coded greys. By Sunday evening I was a convert, and slightly more tired than I would like.
What a semantic token is
A semantic token describes a job. text-default, surface-raised, border-subtle and action-primary all tell you where the value should be used, not what it looks like. Each one points at a primitive underneath.
{
"text-default": "{grey.900}",
"text-muted": "{grey.600}",
"surface-default": "{white}",
"surface-raised": "{grey.50}",
"action-primary": "{blue.600}"
}
The component asks for text-muted. The token decides which grey that means today.
Why purpose beats appearance
When a component uses grey-600, it is making a visual decision. When it uses text-muted, it is making a meaning decision. The second is far more stable.
Visual decisions change all the time. Brands refresh, accessibility reviews push contrast up and dark mode flips everything. Meaning rarely changes. Muted text is still muted text, whatever colour it happens to be this year.
How themes just work
This is where semantic tokens earn their keep. Each semantic token can hold a different value per theme:
:root {
--text-default: var(--grey-900);
--surface-default: var(--white);
}
[data-theme="dark"] {
--text-default: var(--grey-50);
--surface-default: var(--grey-950);
}
Every component that uses --text-default adapts automatically. Nobody touches the button, the card or the table. You change the mapping in one place and the whole product follows.
Group by role
Most semantic tokens fall into a few clear groups. Organising them this way makes them easier to find and harder to misuse:
- Surface. Backgrounds for pages, cards, panels and overlays
- Text. Default, muted, inverse and link text
- Border. Subtle dividers, default outlines and strong emphasis
- Action. Primary, secondary and destructive interactive elements
- Status. Success, warning, danger and information
Within each group, a small number of clear levels beats a long list of nuanced ones. Three surface levels is plenty for most products.
Naming that holds up
Good semantic names read naturally in a sentence. "The card uses surface raised with a border subtle" sounds like something a designer would say. Names that need explaining, like surface-alt-2, usually point to a missing idea.
A few habits help:
- Use the same order everywhere, such as role first then variant
- Avoid colour words in semantic names, so
action-primaryrather thanaction-blue - Name states consistently, such as
action-primary-hoverandaction-primary-pressed
Do not go too far
There is a trap on the other side. Some teams create a semantic token for every single component, like pricing-card-header-background. That is not semantic, it is just hard coding with extra steps.
Keep the semantic layer general. If several components share a purpose, they should share a token. Component specific tokens are occasionally useful, but they should be the exception and they should still point at semantic tokens rather than primitives.
I once reviewed a system with over six hundred semantic tokens. The team was very proud. Nobody could find anything, and most designers had quietly gone back to using primitives because it was faster. Fewer, clearer tokens would have served them far better.
Spotting a missing token
When someone reaches for a primitive inside a component, it is a signal. Either they did not know the right semantic token existed, or it does not exist yet. Both are worth fixing.
Keep a short list of these moments. If the same gap appears more than once, add a semantic token for it. Your system grows from real needs rather than imagined ones.
Why agents need them
AI agents rely on names more than anything else. An agent reading text-muted understands its purpose immediately. An agent reading grey-600 has to guess. Semantic tokens turn your system into a vocabulary that both people and agents can use correctly, which means far less tidying up after generated work. The AI Color Token Skills teach your agent to reach for these names by default.
Start with surfaces and text
You do not need to define every semantic token at once. Start with surfaces and text, because they cover the majority of any interface. Create three surface tokens and three text tokens, map them to your primitives and swap them into your most used components. Then try a dark theme by changing only the mappings. The first time it works without touching a component feels a little bit like magic. We build a full token system like this in our AI Design Systems Bootcamp.
Memorisely