A design token is one design decision, given a name and stored in one place. “Our main button colour is this exact orange.” “Medium spacing is 16 pixels.” “Headings use Archivo.” Designers and developers both use the name, never the raw value, so when the decision changes, it changes everywhere at once.

That’s it. The rest of this article is why such a simple idea matters so much, using real tokens from Somnia DS, the design system this site is built on.

The problem tokens solve

Without tokens, a colour like #C13D0A gets typed into hundreds of places: in Figma, in stylesheets, in emails. Then someone slightly mistypes it. Then the brand changes, and someone has to find every copy. Then you add dark mode and need a different orange in half of those places but not the other half.

With tokens, the orange is written down once, and everything else refers to it by name.

Two kinds of token

Primitive tokens: the raw ingredients

Primitives name every value the brand has, plainly, without saying what it’s for. In Somnia DS:

"color": {
  "ember": {
    "600": { "$value": "#C13D0A", "$description": "Light accent" },
    "400": { "$value": "#FF7A3D", "$description": "Dark accent" }
  }
}

ember.600 is a colour. It doesn’t know if it’s a button, a link or a warning.

Semantic tokens: the jobs

Semantic tokens name a job and point at a primitive. Light mode:

"action": {
  "primary": { "$value": "{color.ember.600}" }
}

and dark mode, the same name pointing somewhere else:

"action": {
  "primary": { "$value": "{color.ember.400}" }
}

Components only ever use the semantic name, color.action.primary. The button doesn’t care which orange it gets; the theme decides.

Why the two layers matter

That small indirection is what makes the big changes cheap:

  • Dark mode is a second set of semantic tokens pointing at different primitives. No component changes. (More in light and dark mode, done properly.)
  • A second brand is the same again. Somnia DS has four: switch between them at the top of any component page and watch every example follow.
  • A rebrand is mostly editing primitives.
  • Accessibility fixes happen once. If a text colour fails contrast, fix the token and every screen passes.

You can try it in our theme builder: choose two colours and two fonts, and it generates a full set of semantic tokens for light and dark, checks the contrast, and hands you the files.

More than colour

Tokens cover any small decision you want to keep consistent:

Kind Somnia DS example Value
Colour color.action.primary {color.ember.600}
Font font.family.heading Archivo
Font size font.size.label 12px
Spacing space.4 16px
Corner radius radius.md 10px
Motion duration.fast 150ms

See them all on Somnia DS’s tokens page.

One file, many places

Tokens are written in a standard JSON format from the W3C Design Tokens Community Group, which published its first stable version in October 2025. Because the format is shared, one file can be turned into:

  • CSS variables for websites (Somnia DS’s build turns color.action.primary into --somnia-color-action-primary)
  • Figma variables, so designers pick from the same names
  • iOS and Android values for apps

So the design file, the website and the app all use the same decisions, from the same source.

A few tips if you’re starting

  • Name by job, not by look. color.text.secondary, not color.grey-text. Looks change; jobs don’t.
  • Start small. A dozen colours, a type scale and a spacing scale go a long way.
  • Make the raw values hard to reach. Somnia DS’s build fails if a component uses a primitive directly, so nobody can skip the semantic layer by accident.
  • Write descriptions. One line on what each token is for saves a hundred questions later.

New to the vocabulary? Our plain-English dictionary covers tokens, components and the rest.

Thinking about tokens or a design system for your product? Get in touch. We design, build, document and host them.

See a design system working

Somnia DS is the design system this website runs on, published in full: tokens, components, patterns, accessibility and governance. We build systems like it for clients, prototype on it, and host and look after the documentation for you.

Same components, different brand:

← Back to all insights