On this page

Every product has a colour for “error”, a size for “small gap” and a font for headings. Design tokens give each of those decisions a name, so designers and developers use the same one. This guide explains what tokens are, the three kinds you will meet, and a workflow that keeps Figma and code in step.

In short

  • A token is a named design decision: color.text.error instead of #D92D20.
  • Use two layers at least: primitives hold values, semantic tokens hold meaning.
  • Components use semantic tokens only. Then a theme change touches one layer.

What is a design token?

A design token is a name with a value. space.4 might be 16 pixels, color.brand.primary might be a purple. Everyone uses the name, so when the value changes, it changes everywhere at once: in Figma, on the website and in the apps.

Tokens now have a shared file format. In October 2025 the W3C Design Tokens Community Group published the first stable version of its format specification, version 2025.10. It is a community report rather than an official W3C standard, but Figma, Penpot, Sketch, Style Dictionary, Tokens Studio and others have said they support it or are building support. Here is a small but complete token system in that format: primitives, semantic tokens, spacing, type, motion and one component. Scroll inside the box to see all of it.

tokens.json
{
  "color": {
    "purple": {
      "400": {"$type": "color", "$value": "#8B63FF"},
      "600": {"$type": "color", "$value": "#6222FF"},
      "700": {"$type": "color", "$value": "#4E1BCC"}
    },
    "grey": {
      "50": {"$type": "color", "$value": "#F1EFED"},
      "500": {"$type": "color", "$value": "#6E6C75"},
      "900": {"$type": "color", "$value": "#15141A"}
    },
    "red": {
      "600": {"$type": "color", "$value": "#D92D20"}
    },
    "text": {
      "default": {"$type": "color", "$value": "{color.grey.900}", "$description": "Body text and headings"},
      "muted": {"$type": "color", "$value": "{color.grey.500}", "$description": "Captions, hints, secondary labels"},
      "error": {"$type": "color", "$value": "{color.red.600}"}
    },
    "background": {
      "surface": {"$type": "color", "$value": "{color.grey.50}"}
    },
    "action": {
      "primary": {"$type": "color", "$value": "{color.purple.600}"},
      "primary-hover": {"$type": "color", "$value": "{color.purple.700}"}
    }
  },
  "space": {
    "2": {"$type": "dimension", "$value": {"value": 8, "unit": "px"}},
    "4": {"$type": "dimension", "$value": {"value": 16, "unit": "px"}},
    "6": {"$type": "dimension", "$value": {"value": 24, "unit": "px"}}
  },
  "radius": {
    "md": {"$type": "dimension", "$value": {"value": 12, "unit": "px"}}
  },
  "font": {
    "family": {
      "body": {"$type": "fontFamily", "$value": "Inter"}
    },
    "weight": {
      "bold": {"$type": "fontWeight", "$value": 700}
    }
  },
  "motion": {
    "fast": {"$type": "duration", "$value": {"value": 150, "unit": "ms"}}
  },
  "button": {
    "primary": {
      "background": {"$type": "color", "$value": "{color.action.primary}"},
      "background-hover": {"$type": "color", "$value": "{color.action.primary-hover}"},
      "padding": {"$type": "dimension", "$value": "{space.4}"},
      "radius": {"$type": "dimension", "$value": "{radius.md}"}
    }
  }
}

Look at color.text.default: its value is not a colour but {color.grey.900}, a reference to another token written with curly braces. That reference is called an alias, and it is what makes tokens powerful: change the grey once and every alias follows. Dark mode is a second, smaller file that gives the same semantic tokens new aliases. Primitives and components stay untouched:

dark.json
{
  "color": {
    "text": {
      "default": {"$type": "color", "$value": "{color.grey.50}"},
      "muted": {"$type": "color", "$value": "{color.grey.500}"}
    },
    "background": {
      "surface": {"$type": "color", "$value": "{color.grey.900}"}
    },
    "action": {
      "primary": {"$type": "color", "$value": "{color.purple.400}"}
    }
  }
}

Why tokens matter

  • One source of truth. A colour is decided once, not copied into 40 screens and three codebases.
  • Themes for free. Light, dark, high contrast or a second brand become a new set of values, not a redesign.
  • Cleaner handoff. Developers see color.text.muted in the design, not a hex code they have to guess the meaning of.
  • Safer change. Renaming or retiring a token is a visible, reviewable change instead of a silent drift.
  • Better AI output. Tools that read your design file, such as Figma’s MCP server, can pass token names to coding assistants, so generated code uses your system instead of raw values.

Primitive, semantic and component tokens

Most systems organise tokens in layers. Each layer points at the one below it.

Layer
What it holds
Example
Who uses it
Primitive
Raw values: the full palette, the spacing scale, font sizes
color.purple.600
Only other tokens
Semantic
Meaning: what a value is for
color.action.primary
Designers and components
Component
One part of one component
button.primary.background
That component only

Primitives describe what a value is. Semantic tokens describe what it is for, and they are the layer that changes per theme: color.text.default points at a dark grey in light mode and a near-white in dark mode. Component tokens are optional. Add them when a component needs to differ from the general rule, for example when buttons must change colour without changing every link.

Two rules keep the layers useful. Components use semantic tokens, never primitives. And a semantic token must add meaning: color.blue pointing at color.blue.500 is just a second name for the same thing.

How to name tokens

A good name reads from general to specific. A common pattern is category, property, role, state:

token names
color.background.surface
color.text.muted
color.border.error
color.action.primary.hover
space.inset.md

Some tips:

  • Never put a value in a semantic name. color.text.purple breaks the day the brand turns green.
  • Pick one size scale and keep it (xs to xl, or 100 to 900) across colour, spacing and type.
  • Write names in lowercase with one separator. The specification groups tokens with nesting and dots; Figma shows the same groups with slashes.
  • Add a description to every semantic token: where to use it and where not to.

What can be a token?

The 2025.10 format defines simple types and composite ones, which bundle several values.

Kind
Types
Simple
colour, dimension (sizes and spacing), font family, font weight, duration, cubic bezier (easing), number
Composite
typography, shadow, border, stroke style, transition, gradient

In Figma, variables hold four types: colour, number, string and boolean. Simple tokens map to variables. Composite tokens such as a full text style or a shadow stay as Figma styles, and the styles use variables for their parts, for example a text style whose size and line height come from number variables.

A workflow that works

  1. Audit. Collect every colour, size, radius and font in use. Expect duplicates such as five almost identical greys. Merge them.
  2. Primitives. Build the palette and scales. Keep them complete but boring.
  3. Semantic layer. Start small: text, background, border, action, status. Alias each one to a primitive. Add more only when a real screen needs it.
  4. Themes. Give the semantic layer a mode per theme (light, dark, brand). Primitives do not change between themes.
  5. Figma. Store tokens as variables. Hide primitives from publishing and limit where each variable appears, so designers pick semantic tokens by default. Our Figma themes guide walks through it.
  6. Export. Export the variables as JSON in the shared format. Figma added native import and export aligned with the specification; plugins such as Tokens Studio cover more cases.
  7. Build. A build tool such as Style Dictionary or Terrazzo turns the JSON into CSS variables, Swift, Kotlin or a Tailwind theme.
  8. Version and review. Keep the token files in Git. Every change is a pull request with a short note on what changed and why.
  9. Retire safely. Mark old tokens as deprecated (the format has a $deprecated field), point them at the replacement, and remove them a release later.

Figma or code: where tokens live

Pick one home for tokens and treat everything else as a copy.

Home
Good for
Watch out for
Figma variables
Design-led teams; designers own the values
Exports must run on every change, or code drifts
JSON files in Git
Several platforms; strict review of every change
Designers need a plugin or a sync step to see changes

Small teams usually start in Figma and export. Teams shipping web, iOS and Android usually move the source into Git and sync it back to Figma. Either works if only one place is ever edited by hand.

Common mistakes

  • Too many tokens too early. A token for every pixel is as hard to use as none. Start with fewer, broader semantic tokens.
  • Primitives in designs. If screens use purple.600 directly, dark mode will not switch it.
  • Names that describe looks. color.text.grey instead of color.text.muted.
  • Two sources of truth. Editing values in Figma and in code means they will differ within a month.
  • No owner. Someone must review new tokens, or the system grows a duplicate per sprint.

DESIGN SYSTEMS

Want a token system your team will actually use?

We can set up primitives, semantic tokens and themes in Figma and in code, and keep them in sync.

Plan your token system

Fresh from the blog

Short, practical reads on design, AI, and growth from Growth Geeks, an AI growth agency in Berlin.

Leave a Reply