Memorisely
Design Systems

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.

Naming by purpose keeps components stable when the colours underneath change.

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.

Each semantic token holds a value per theme, so components never need to know which one is active.

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.

Grouping by role with a few clear levels each makes the right token easy to find.

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-primary rather than action-blue
  • Name states consistently, such as action-primary-hover and action-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.

Keep reading

View all
View all

Optimize your AI for better experiences, not AI slop.

View all

AI Prototyping Skills

Prototype with AI using clean UI patterns and guardrails so flows feel product-grade, not generic template slop.

$99

AI UI Motion Skills

Motion and micro-interaction patterns that make AI-built UI feel designed, polished, and trustworthy in real products.

$99

Fix AI Slop Skills

Spot AI slop early and fix type, spacing, and components so your product looks intentional, not like a template.

$99

AI Responsive Design Skills

Responsive layout patterns for rails, sidebars, and breakpoints so AI-generated UI adapts cleanly from narrow to wide.

$99

AI Dark Mode Skills

Dark theme tokens, contrast, and surfaces that keep AI-generated UI readable and product-grade, not flat gray on black.

$99

AI Color Token Skills

Neutral and primary ramps with clear steps so AI palettes stay systematic, not a random set of accent hex codes.

$99
View all