Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 36 ยท Design Systems and Variables

Design Tokens

Learn the three tiers of design tokens (primitive, semantic, component), how to name them in Figma variables and how they export to CSS.

A design token is a named design decision: color.text.primary, space.4, radius.md. Tokens are the shared language between design and code. In Figma, tokens are stored as variables; in code they become CSS custom properties, Swift constants or JSON entries. When both sides use the same names, "make the card padding space-4" means the same thing to everyone.

Figma cannot run on this site. The code is a labelled JavaScript stand-in that converts a token tree to CSS and checks naming. Figma's own export formats and plugins may differ.

Why raw values are not enough

If a button uses #2563EB, you do not know whether that is "the brand color", "the link color" or "an accident". If the brand changes, you must find every use. With a token named color.action.primary, you change one definition. Tokens also make theming possible: the same token name maps to different values in different modes.

Three tiers

Most systems use three levels:

  1. Primitive (global) tokens describe the raw palette and scales: blue-500, gray-900, space-4 = 16. They have no meaning, just values.
  2. Semantic (alias) tokens give meaning: color.action.primary -> blue-500, color.text.default -> gray-900. These change per mode (Light and Dark).
  3. Component tokens are specific to a component: button.background.default -> color.action.primary. Use these only where a component needs its own overrides.
flowchart TD
    A["Primitive<br/>blue-500 = #2563EB"] --> B["Semantic<br/>color.action.primary"]
    B --> C["Component<br/>button.background.default"]
    B --> D["Component<br/>link.text"]

Designers mostly apply semantic tokens; primitives stay mostly hidden.

In Figma, build one Primitive collection (hidden from publishing), a Semantic collection with modes, and optionally a Component collection. Use the slash in variable names to build groups (color/action/primary), which makes a tree in the variable list.

Naming tokens

Good names describe purpose, not appearance. color/text/danger survives a rebrand; color/red does not if danger turns orange. A common pattern is category/property/role/state:

  • color/text/default, color/text/muted, color/text/inverse
  • color/surface/default, color/surface/raised
  • color/border/focus
  • space/1, space/2, space/4
  • radius/sm, radius/md, radius/full
  • font/size/body, font/weight/bold

Tips: use lowercase, be consistent about singular and plural, and avoid numbers that depend on pixels in the name (space/16 is brittle; space/4 stays valid if the base unit changes).

Tokens to CSS

On the code side, tokens become CSS custom properties. Dots or slashes become dashes. The stand-in below transforms a nested token tree to a :root block.

JS Stand-in: token tree to CSS custom properties

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Dark mode in CSS is then a second block that redefines only the semantic custom properties, for example under a [data-theme="dark"] selector. Figma modes map to that directly.

Checking names automatically

A token set grows large. A tiny linter catches names that mix styles.

JS Stand-in: token naming linter

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Styles versus variables

Figma still has styles for text, effects and grids (and for paints, though variables now cover most color uses). Use variables for colors, numbers, strings and booleans. Use text styles for typography groups (family, size, weight, line height together), and bind their inner values to variables where supported. Effects such as shadows remain styles. This gives you tokens for most values and styles for composite ones.

Getting tokens out of Figma

  • Dev Mode shows variable names next to values, so developers see color/action/primary.
  • The Variables REST API (on plans that include it) lets scripts read and write variables.
  • Plugins can export variables to JSON, CSS, or Style Dictionary format. Treat a plugin as a convenience; the contract is the naming convention you agree on.
  • Many teams store the source of truth in JSON in the code repository and sync it into Figma, others do the reverse. Pick one direction and stick to it.

Common mistakes

  • Skipping the semantic tier and applying primitives directly, which breaks dark mode.
  • Too many component tokens. Start with none and add them when a component needs special handling.
  • Names tied to hue or pixels.
  • No documentation. Add descriptions to variables; they appear in the picker.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which tier gives meaning, such as color/action/primary?

    Semantic tokens alias primitives and describe purpose; they usually change per mode.
  2. 2. Which token name will survive a rebrand best?

    Purpose-based names stay valid when the actual hue changes.
  3. 3. How do tokens usually appear in CSS?

    Tokens map naturally to CSS custom properties.
  4. 4. Where should designers mostly apply colors in a mature system?

    Semantic variables keep modes and themes working.

Summary

  • Tokens are named design decisions shared between design and code.
  • Use three tiers: primitive, semantic and (sparingly) component.
  • Name for purpose, in lowercase with slash groups.
  • Variables hold most tokens in Figma; text styles and effects remain styles.
  • Agree on one source of truth and one direction of sync.

Next: Building a Design System