Skip to content
Velloreth
Design 10 min read

Design Tokens: Bridging Design and Code

Design tokens as a shared source of truth: the W3C DTCG format, primitive/semantic/component layers, theming, build pipelines, and how to migrate off hex values.

By

A design token is a design decision stored as data. Instead of a component containing #2563eb, it references color.action.primary, and one file decides what that resolves to.

The idea is old — Salesforce’s Theo predates most of the current tooling — but the format only became portable in October 2025, when the W3C Design Tokens Community Group published the first stable version of its specification (2025.10). That matters because the previous state of the art was every tool inventing its own JSON shape, and every handoff requiring a converter.

What a token actually is

At minimum: a name, a value, and a type.

{
  "color": {
    "action": {
      "primary": {
        "$value": "{color.blue.600}",
        "$type": "color",
        "$description": "Primary button background, light theme"
      }
    }
  }
}

The $value is the payload. $type tells consumers how to interpret it — color, dimension, duration, fontFamily, shadow, number, cubicBezier, strokeStyle, and composite types like typography and gradient. Types matter: they are what lets a build step emit 16px for a dimension in CSS and 16.dp in Compose, or convert a color between spaces per platform.

$description is documentation that travels with the token. $deprecated marks a token as on its way out without deleting it, so consumers can be flagged while old references keep resolving.

References use a path syntax:

"$value": "{color.neutral.900}"

One source, many consumers. A theme is not a second copy of the file — it is a different resolution of the same names.

Three layers, and the rule that keeps them working

The structure that survives contact with a real product:

primitives    color.blue.500        raw ramps, no meaning
semantics     color.action.primary  meaning, points at a primitive
components    button.background     optional local override

Primitives are your ramps and scales: blue.100 through blue.900, spacing 4 through 128, the type steps. They encode no intent — blue.500 says nothing about where it may appear.

Semantics are where the system does its work: color.bg.canvas, color.text.primary, color.action.danger, border.subtle. These are the names components use.

Component tokens exist only where a component genuinely deviates: button.secondary.background if a secondary button is not simply color.surface.raised. Keep this layer small; a component token for every property of every component is a second design system nobody will maintain.

The rule: components never reference primitives. A component pointing directly at blue.500 breaks every future theme, because the semantic layer is the only place a theme gets to remap. Enforce it with a lint rule, not a code review convention — conventions decay, linters do not.

Why this beats variables in a stylesheet

CSS custom properties are an excellent output format and a weak source of truth. They have no type system, no cross-platform story, no documentation, no deprecation, and no way for a design tool to read them.

A token file has all of those, and compiles down to custom properties:

:root {
  --color-action-primary: #2563eb;
  --color-text-primary: #0f172a;
  --space-4: 1rem;
  --duration-fast: 150ms;
}
[data-theme="dark"] {
  --color-action-primary: #60a5fa;
  --color-text-primary: #e5e7eb;
}

The same source also emits Swift, Kotlin, and Figma variables. The value of the abstraction is exactly the number of targets it feeds — one target does not need it, five do.

Where tokens genuinely pay off

Theming. Light, dark, and high-contrast are three mappings of the same semantic names. Adding a theme becomes a mapping block, not a stylesheet.

Multi-brand. A second brand repoints layer two. This is the case where token systems usually justify their entire setup cost.

Design-tool parity. When Figma variables and the codebase read the same file, “the design says 8px” stops being a negotiation. Drift becomes a build failure rather than a review comment.

Auditable accessibility. Because every color goes through a semantic name, you can assert the contrast matrix for every token pair in CI and catch regressions at the source rather than in a component audit.

Onboarding. A new developer looking at color.text.muted learns the intent from the name. A new developer looking at #94a3b8 learns nothing and must go find the design file.

What tokens should not encode

Common over-reach:

  • Layout. Tokenizing padding-left-of-sidebar-in-collapsed-state is not a design decision, it is a magic number with better marketing. Reserve tokens for values that appear across components or carry brand meaning.
  • One-off values. If a value is used exactly once, a token adds indirection without adding leverage.
  • Component internals with no variation. button-inner-shadow-offset used by one button in one state is noise in the token browser.
  • Content. Wording belongs in a copy system or the product itself.

The test: does this value need to change together with other values? If yes, it is a token candidate — the relationship is what you are capturing. If it changes alone and only once, leave it in place.

Choosing your pipeline

Three levels, in increasing order of machinery:

1. Hand-written CSS custom properties. Zero tooling, first-class browser support, easy theming with data-theme. Correct for a single-platform project with one designer who also writes CSS. Genuinely not a compromise at that scale.

2. A token compiler. Style Dictionary, Terrazzo, or Tokens Studio read the token file and emit CSS, Swift, Kotlin, Android XML, and platform-appropriate transforms — units converted, colors gamut-mapped, names flattened or nested to your convention. Add this when you have more than one target or more than one person editing tokens.

3. A live pipeline. Design tool plugin syncing from the same source, tokens compiled on merge, generated files committed or built in CI, contrast assertions running against the output. This is where the W3C format earns its keep, because tools can now read and write the same shape.

The W3C 2025.10 specification added the pieces that were missing for production: theming and multi-brand support without file duplication, support for modern color spaces including OKLCH and Display P3, aliases and inheritance, and cross-platform generation. Reference implementations exist in Style Dictionary, Tokens Studio and Terrazzo, with support announced or shipped across Figma, Penpot, Sketch and others.

Before adopting a format, check that every tool in your chain reads it. A token standard that your design tool exports and your build step cannot import is a conversion problem wearing a standard’s clothes.

Naming, and the two schools

Two conventions, both defensible:

category.property.role.variant    color.text.primary.default
category.role.variant             color-text-primary

The dotted/grouped form maps cleanly onto the JSON structure and reads well in a token browser. The kebab form maps cleanly onto CSS custom property names without a transform. Pick one, write it down, and generate it — do not let individuals choose per file.

Whatever you choose, be consistent about:

  • Semantic names describe intent, not appearance. color.action.danger survives a palette change; color.red.600 does not convey that it is only for errors.
  • State is part of the name. hover, pressed, disabled, focus are variants, not separate tokens with unrelated names.
  • Themes are not in the name. color.text.primary.dark forces every consumer to know which theme it is in. Themes are a resolution layer; the consumer asks for the meaning.

A minimum viable token file

You do not need a hundred tokens to start. This is enough for a real product:

{
  "color": {
    "$type": "color",
    "neutral": {
      "0":   { "$value": "#ffffff" },
      "50":  { "$value": "#f8fafc" },
      "100": { "$value": "#f1f5f9" },
      "200": { "$value": "#e2e8f0" },
      "400": { "$value": "#94a3b8" },
      "600": { "$value": "#475569" },
      "800": { "$value": "#1e293b" },
      "950": { "$value": "#020617" }
    },
    "blue": {
      "400": { "$value": "#60a5fa" },
      "600": { "$value": "#2563eb" },
      "700": { "$value": "#1d4ed8" }
    }
  },
  "semantic": {
    "$type": "color",
    "bg":        { "$value": "{color.neutral.0}" },
    "surface":   { "$value": "{color.neutral.50}" },
    "text": {
      "primary":   { "$value": "{color.neutral.950}" },
      "secondary": { "$value": "{color.neutral.600}" },
      "muted":     { "$value": "{color.neutral.400}" }
    },
    "action": {
      "primary":        { "$value": "{color.blue.600}" },
      "primary-hover":  { "$value": "{color.blue.700}" },
      "on-primary":     { "$value": "{color.neutral.0}" },
      "danger":         { "$value": "#dc2626" }
    },
    "border": {
      "subtle": { "$value": "{color.neutral.200}" }
    }
  },
  "space": {
    "$type": "dimension",
    "2":  { "$value": "0.5rem" },
    "4":  { "$value": "1rem" },
    "6":  { "$value": "1.5rem" },
    "8":  { "$value": "2rem" }
  },
  "duration": {
    "$type": "duration",
    "fast": { "$value": "150ms" },
    "base": { "$value": "250ms" }
  }
}

Ninety lines, two layers, and it covers a small application. Note semantic.action.on-primary — the text color that sits on the primary action. Naming the pairing explicitly is what stops someone from hardcoding #fff over a lighter accent later.

The trap at this stage is building the ramp for all eleven brand hues before you have used three. Add primitives when a semantic token needs them, not in advance.

Governance: who is allowed to change a token

Token repositories are shared infrastructure, and they fail socially before they fail technically. Three rules prevent most of it:

Changing a primitive value is a breaking change. blue.600 shifting from #2563eb to #1e40af alters every semantic token pointing at it, which alters every screen. Treat it like an API change: review it, verify contrast after it, and announce it.

Adding a semantic token requires a use case. “We might need a warning color” is not a use case. “The CSV import flow needs a non-destructive warning state” is. Every token added without a consumer becomes permanent cruft that people have to scroll past.

Deprecate, do not delete. Mark with $deprecated, leave a note pointing at the replacement, and remove it after consumers have migrated. Deleting a token that an older branch still references turns a cleanup into a build failure two months later.

Assign an owner — one person or a small group — rather than “the design systems team” with no names. Tokens sit on the critical path for both design and engineering, so ambiguity about ownership turns into a queue.

Testing tokens, not screens

The advantage of having one source is that you can assert on it directly:

  • Contrast assertions. For each semantic text token and each surface it can appear on, compute the ratio at build time and fail below the threshold. Run it per theme.
  • Reference integrity. Every {path.to.token} resolves, and no cycle exists.
  • Coverage. Every theme defines every semantic token. A missing key in a new theme is otherwise discovered by a user seeing an unstyled component.
  • Purity. No hex literals in component stylesheets. The inverse of the token invariant.
  • Size. If you are emitting CSS, watch the output. Tokens that are all included regardless of usage can add kilobytes to a stylesheet where one class would have done; emit only what the build references, or accept the cost consciously.

None of these require a design review, which is the point — the checks run on every merge and the review budget goes to decisions instead of verification.

Migrating an existing product

Do not attempt a big-bang replacement. This sequence works:

  1. Inventory. Extract every distinct color, size, and font value from the codebase with a script. You will find roughly 30 values doing 90% of the work, plus a long tail of one-offs.
  2. Cluster and name. Group them into ramps and scales. This is where you discover the four slightly different grays that were all meant to be “muted text”.
  3. Introduce semantics. Map the top 20 usages to semantic tokens and wire them through CSS custom properties. No component changes yet — the property names stay the same.
  4. Audit. Run a contrast check across the semantic tokens in both themes. You will find real failures; fix them as part of the migration so the baseline is clean.
  5. Replace opportunistically. Every file touched loses its hardcoded values. No freeze, no rewrite weekend.
  6. Connect the design tool once the code side is stable, so the sync starts from a known-good state rather than a half-migrated one.

Most teams get the majority of the value by step 3.

The test for a working system

Ask three questions six months in. Can a designer change the brand color in one place and have it correct across every platform? Can a developer tell from a token’s name whether it is allowed on this surface? Can you add a theme without editing component styles?

If all three are yes, the tokens are doing their job — and the interesting part is that nobody thinks about them anymore, which is what a good abstraction looks like from the inside.

Frequently asked questions

What exactly is a design token?
A named design decision stored as data — a color, size, duration, or font — with a value and a type. Instead of a component hardcoding `#2563eb`, it references `color.action.primary`, which a build step turns into whatever the current value is.
How does the W3C design token format work?
Tokens live in JSON where each key holds a `$value` and optional `$type`, `$description`, and `$deprecated`. Groups nest to form namespaces, and `$value` can reference another token with a path like `{color.blue.500}`. The 2025.10 stable specification added theming, aliases, and support for modern color spaces.
Do I need a token build pipeline?
For a website you can start with CSS custom properties and no build step, which is genuinely enough for many projects. Add a pipeline like Style Dictionary when you need multiple platforms from one source, themes, or strict naming conventions — not before.
How do tokens and component styles relate?
Components consume semantic or component-level tokens and never raw primitives. That indirection is the entire point: it is what lets you change the brand, add a theme, or ship a high-contrast mode without editing a single component stylesheet.