Design Token

The color in the mockup and the color on the screen kept coming out different. Designers picked colors inside their design file, engineers typed color values into code, and one mistyped character anywhere created a second source of truth. Those splits were hard to notice, so they usually surfaced six months later, when someone counted twelve shades of gray in a product meant to have three.

The real cost showed up the day a brand color changed. Darkening one blue sounds like a small edit, but nobody knew how many places in the code held that value. Searching and replacing one by one always left a straggler, and the straggler shipped in the next release still wearing the old blue.

Asking didn't help much either. "Which blue is that?" got answered with six hex characters, and those six characters said nothing about whether the color belonged to emphasis, to links, or to a warning.

A design token cuts the problem by making everyone say a name instead of a value. Write color-accent-default rather than #2F6BFF, and changing what that name points to in one place changes everywhere the name appears. Because the name carries the usage, the question mostly stops getting asked.

One token is a name paired with a value. A set of them holds four things.

1. The name, which describes usage. color-accent-default, space-4, font-body-size — each says where the value belongs rather than what it is. Agreeing on the order of the parts in advance keeps people from guessing when they add a token later.
2. The value that actually gets applied: #2F6BFF, 16px, 600.
3. The tier. Tokens usually come in three layers: a global token that names a raw value, an alias token that points at a global token under a usage name, and a component token used only inside one part. blue-500 is global, color-accent-default pointing at it is an alias, and button-primary-background pointing at that is a component token. Why three layers is worth it comes just below.
4. The category — color, spacing, type, corner radius, shadow — grouping values by what kind of thing they are. Categories make it easy to find whether a token already exists, and easy to notice which ones are missing. A set with forty color tokens and four spacing tokens is telling you where the next afternoon of work goes.

Add a theme on top and one name can carry several values. A theme swaps a whole set of token values to change the overall look. Attach white to color-background-default in light mode and a dark gray in dark mode, and both modes come out of the same screens with nothing redrawn. That's what the layers buy: a separate layer naming raw values is exactly what lets a usage name point somewhere different depending on the mode.

A designer and an engineer write it together, as a pair that owns the design system. A designer working alone produces a structure that's awkward to consume in code; an engineer working alone produces names nobody can call from a design file. The values themselves usually come from the brand guideline, the document setting out how the logo, colors and typefaces get used. Once that document fixes two brand colors, tokens take them in and spread them across the product's actual usages.

Three audiences read it. Product designers pick tokens inside their design tool, choosing a name from a list rather than sampling a color, which means colors outside the system can't be chosen in the first place. Engineers use the same names as variables in code, so comparing a mockup against the build no longer involves comparing hex values. And the build tooling reads it: keep the set in one file and a tool converts it into whatever format each platform expects — CSS custom properties for the web, a constants file for iOS, an XML resource for Android — so the same name survives on every platform without anyone retyping it.

The value of the whole arrangement is that those three share one name. The parts in the component library — the buttons, inputs and modals built once and kept together — are assembled out of tokens, so changing one token value pulls every screen using those parts along with it.

"Don't paste that color in, use the color-accent-default token."

A raw value went into the file, and it should be calling a name instead.

"There's no 6px spacing token, so I rounded it to 8."

The value needed isn't in the set, so the nearest existing one was used — and that gap is worth reporting rather than quietly working around.

"Dark mode comes out of a token swap — no screen changes needed."

The same names carry different values, so the screens themselves stay as they are.

Pagedeck changed its brand color twice. The first time was before tokens existed. Theo spent three days searching the codebase for color values and fixing them, and even then one notification email kept the old blue for a month before anyone noticed.

The second time came after Noa had organized the tokens. Changing the value of blue-500 took one line, every place pointing at that name followed, and the work that had taken three days finished before lunch. All that remained was scanning for spots where someone had written the old value in directly, and there were two, both in screens built during a deadline week the year before.

The most common misreading is that tokens are a color list. Color usually gets tidied up first, which makes the impression easy to form. But leave spacing and type sizes out and the screens stay as ragged as they were. A screen with correct colors and inconsistent padding reads as sloppy in the same way a screen with wrong colors does. Pinning spacing to multiples of four and naming those steps pays off about as much as the color work.

Putting the color's own name into the token name is the other frequent mistake. color-blue reads clearly on day one. Then dark mode attaches a different value to that slot and color-blue is no longer blue. A name built from usage keeps telling the truth after the value moves, which is the whole reason the alias layer exists between the raw value and the screen. This is why many teams write their naming rules into the style guide, the document covering when and how colors, typefaces and spacing get used.