"Tokens" is now a word everyone in design says and few people agree on. Some teams mean CSS variables. Some mean a JSON file. Some mean the color palette in Figma. The confusion matters, because tokens are only useful when they are something specific: a semantic layer.

Strip away the tooling and the format wars, and a design token is one simple thing. It is a named value that encodes intent. The name carries meaning; the value is just what happens to back that meaning right now.

The leap from a raw value to a token is the entire point, and most teams never actually make it.

A raw value is not a token

A hex code sitting in a Figma file is not a token. It is a value. It becomes a token only when it is given a name that says what the value is for.

Consider two ways of storing a brand color. The first is a swatch named "Orange" with the value #FF8A3D. The second is a token named color.brand.primary with the same value. They look similar. They are not the same thing.

The first says what the color looks like. The second says what the color means. The distinction is the difference between a style guide and a system.

The semantic layer

Think of tokens as a layer that sits between raw values and components. On one side are the raw values: hex codes, pixel sizes, font names. On the other side are the components that consume them. The semantic layer is the middle, where values get names that describe their role rather than their appearance.

The value of that middle layer is decoupling. When the meaning and the value are separated, the value can change without the meaning changing, and the whole system updates in one place. That is the entire promise of tokens, and it only works if the names are semantic.

Naming by role, not by appearance

The most common mistake is naming a token by its value or by a single use. --orange names the value. --button-background names a single use. Both fail for the same reason: they couple the name to something that will change.

If you name a token --orange and later rebrand to blue, you are stuck with a blue that is named orange. If you name it --button-background, it works until you want to use that same color for a link, and then the name lies.

Name tokens by role and category instead. color.brand.primary, not color.orange. space.4, not space.button-padding. font.size.heading, not font.size.24px. The name should survive the value changing.

Primitive and semantic tokens

A healthy token system usually has two tiers. The first tier is primitives: the raw palette, the full set of spacing steps, the complete type scale. These are value-oriented and deliberately unopinionated. A primitive might be color.orange.400.

The second tier is semantic tokens, which reference the primitives. color.brand.primary points at color.orange.400. Components consume the semantic tokens, not the primitives. The primitives are the raw material; the semantics are the vocabulary.

This indirection is what makes theming and dark mode cheap. You change what color.brand.primary points at, and every component updates, because no component ever referenced the raw value directly.

What semantics actually buys you

Three concrete outcomes follow from a semantic layer.

  • Rebrands stop being emergencies. A color change is a change to the mapping, not a hunt through forty screens.
  • Dark mode stops being a fork. A second mapping of the same semantic names is all it takes.
  • Design and code stop drifting. When Figma and CSS consume the same semantic names, they cannot disagree about intent.

None of these work with a style guide that names values by appearance. They are properties of the semantic layer specifically.

The discipline of naming

The hard part of tokens is not the values. It is the names. A name has to be specific enough to be useful and general enough to survive change, and it has to be agreed on by designers and engineers who think differently.

A few habits help. Avoid one-use tokens; if a token is used in exactly one place, it is probably a component detail, not a system token. Keep names consistent across categories. And write the naming convention down, because the convention is the system, more than any single value.

A token's name is its interface. The value is an implementation detail.

This is also where tokens become the foundation for a bigger thing. A system that treats tokens as a semantic layer is a system that can be versioned, adopted, and governed, which is exactly what it means for a design system to become a product.

The takeaway

Design tokens are not a style guide with a new name. They are a semantic layer between raw values and components, and the naming convention is where the value lives. If your tokens are named by appearance, you have a palette. If they are named by role, you have a system. The difference shows up the first time you need to change something.