TasteMaker Build your brand kit

What are design tokens? A working definition

Updated 2026-07-08 ยท 4 min read

A design token is a named design decision, stored in a format a machine can read. That is the whole definition. color.action.primary = #635BFF is a token. #635BFF on its own is a hex code.

The value of the name is that it can move. If the primary action color changes, one token changes and every button on every platform follows. If you had written #635BFF in forty places, you now have forty edits and a Slack thread about which three got missed.

Why the name is the point

Consider the difference between these two lines of CSS:

.btn-primary { background: #635BFF; }
.btn-primary { background: var(--color-action-primary); }

The first encodes a value. The second encodes an intent. Six months later, when someone asks "can we darken the buttons," the first requires finding every button. The second requires changing one line.

Now consider the same decision in a Figma file, an iOS app, an Android app, and a marketing site. Without tokens, those are four independent copies of a hex code that will drift. With tokens, they are four consumers of one source.

It is not complicated, and it is why design tokens exist.

The three layers

The structure that survives real use has three layers. Most token systems that fall apart skipped the middle one.

1. Primitives. The raw values, named by what they are. No opinion about usage.

blue-500: #635BFF
blue-600: #4F46E5
gray-900: #0A2540
space-2:  8px

2. Semantic tokens. The values, named by their job. These point at primitives.

color.action.primary:        {blue-500}
color.action.primary-hover:  {blue-600}
color.text.default:          {gray-900}
color.background.surface:    {white}

3. Component tokens. Optional, and only when a component needs to diverge.

button.primary.background: {color.action.primary}
button.primary.radius:     {radius.md}

The rule that makes this work: application code never references layer 1. A component that reaches for blue-500 has hardcoded a decision. It should ask for color.action.primary and let the token layer decide what blue that is today. Dark mode is then a matter of repointing semantic tokens at different primitives, not rewriting components.

Spotify's Encore is the clearest public example of what this buys at scale. Encore is not one design system. It is a foundation layer of color, type, motion, and spacing, with separate web and mobile systems and further local systems on top, all sharing tokens. Forty-plus surfaces stay coherent because they agree on a vocabulary, not because they share a codebase.

What a token file looks like

There is a standard, from the W3C Design Tokens Community Group. It is JSON, and a token is an object with $value and $type:

{
  "color": {
    "action": {
      "primary": { "$value": "#635BFF", "$type": "color" }
    }
  },
  "space": {
    "2": { "$value": "8px", "$type": "dimension" }
  }
}

The DTCG format matters because it is the interchange format. Figma exports it, build tools consume it, and every framework-specific format (CSS custom properties, Tailwind config, shadcn theme, Radix scale, Swift, Kotlin) can be generated from it. Author once in the canonical format, emit many.

That resolve-once-emit-many shape is worth designing for deliberately. You want one place where colors, type, radius, and spacing get resolved into a coherent set, and then a pure function per output target. Adding support for a new framework becomes writing one function, not rethinking the model.

The four mistakes

Naming tokens after their value. color-blue is a token that becomes a lie the day the brand turns green. Name the job: color.action.primary. This is the single most common failure, and it is unrecoverable without a rename across the codebase.

Skipping the semantic layer. Going straight from blue-500 to components feels faster and is faster, right up until dark mode. Then you learn that you have no way to say "this blue, but in dark mode" without touching every component.

Tokenizing everything. A token for every one-off value is a spreadsheet with extra steps. If a value is used once, it is not a decision, it is a number. Tokens earn their cost by being referenced.

Letting the design file and the code disagree. Tokens only pay off if there is exactly one source of truth. Two synchronized sources are zero sources of truth. Pick which artifact is canonical, generate the rest, and never hand-edit a generated file.

Where tokens are going: agents as consumers

Until recently the consumers of a token file were a build pipeline and a designer. Now there is a third: the coding agent.

An AI agent asked to "add a settings page that matches our brand" has no taste and no memory of your palette. It will invent a blue. What it can do, reliably, is read a structured file. Hand it a token set, in a format it understands, and the guessing stops. This is the practical reason to formalize tokens even for a one-person project that will never have a design team: the tokens are the context you give the machine.

TasteMaker is built on this idea. It captures brand decisions through side-by-side comparisons, resolves them into a canonical token model, and emits per-target files (CSS variables, W3C DTCG, Tailwind, shadcn, Radix) plus a live MCP server that a coding agent can read your brand from directly. The token file stops being a build artifact and becomes the thing the agent asks.

Getting started without a design system

You do not need Encore. Start here:

  1. Write down the colors you already use. Deduplicate them. You will find three grays that should be one.
  2. Give each survivor a role: primary action, text, muted text, surface, border, destructive.
  3. Put them in one file as semantic tokens pointing at primitives.
  4. Replace hardcoded values in your components with references, starting with the ones you change most.
  5. Do the same for spacing (one 4px or 8px scale) and type (one scale, five sizes).

That is a week of work and it is the difference between a codebase that can be redesigned and one that has to be rewritten.

Next: choosing brand colors covers how to pick the values in step 1, and brand guidelines examples covers where tokens sit in a full brand guide. Or build a token set from your own taste in a few minutes.

Sources

Keep reading

TasteMaker turns your design taste into a brand kit AI coding tools read directly: design tokens, an Agent Skill package, and a live MCP server. Free to build.

Build your brand kit