What Is a Design Token — And How One Line Recolors Your Whole App

Let's unpack something that looks boring right up until the moment you change your brand color in a forty-screen project.
The Design Tokens spec defines a token bone-dry: "A (Design) Token is information associated with a human readable name, at minimum a name/value pair." Sounds like nothing. But the whole power is hiding in there: a token isn't a color. A token is a name. The color is secondary and can become something else at any time.
A token is a name for a value
Ordinary code looks like this: the button is #D4A373, the icon is #D4A373, the link is #D4A373. Three places, one value, and no connection between them. A month later you can't tell "this is gold because it's the accent" from "this is gold because it happened."
Tokens add a layer of names:
{
"color": {
"accent": { "$value": "#D4A373", "$type": "color" }
}
}
Now the button references color.accent. Change one line and it changes everywhere the meaning is accent — and stays put everywhere that just happened to be a similar shade.
Per the spec, only the value — $value — is strictly required. The type ($type) is technically optional, but if it's never set anywhere, tools must treat the token as invalid: without a type there's no way to know #D4A373 is a color rather than a string.
Aliases: the two layers that make dark mode work
This is the move that separates "I named some variables" from real tokens. The spec allows a value to be a reference to another token: "A design token's value can be a reference to another token. The same value can have multiple names or aliases."
That gives you a two-layer scheme:
- Primitives — the raw palette:
gold-300,graphite-900. They just exist and mean nothing. - Semantic tokens — roles:
text.primary,surface.card,border.subtle. Their values are references to primitives.
Components use only the second layer. And then dark mode stops being a repaint: you don't touch a single component, you swap which primitives the roles point at. surface.card pointed at cream yesterday and at graphite today. Done.
Why a format, and not just variables
Fair question: why does this need a whole specification when CSS variables exist? The answer is right there in its stated goal — to "facilitate better interoperability between tools ... by defining a standard file format for expressing design token data."
The point is that design doesn't live in one place. The same accent color is needed on the web, on iOS, on Android, in the design editor. Tokens in neutral JSON are the single source of truth that every other format gets generated from.
That's exactly how it works in KODiQ: one design-tokens.json, and a script lays the colors out into Swift, Kotlin, and CSS. Changing a shade is one edited line and a generator run, not a search across three codebases.
Tailwind runs on the same idea, by the way: its theme is a set of tokens in CSS variables that you can override or wipe entirely.
How to name tokens so you don't redo them later
The name is the one thing that survives every palette change, so pick it by one rule: name the role, not the appearance.
color.danger— good: the role holds even if errors turn orange tomorrow.color.red— bad: in a year you'll have acolor.redthat is actually orange.spacing.gap.card— good.spacing.16— tolerable for primitives, not for components.
Formally the spec restricts very little: a name can't start with $ and can't contain {, }, or a dot — those are reserved for the reference syntax. Everything else is convention, but adopt it once and don't move: renaming a token six months in means editing every place at once.
A practical naming shape goes general to specific: category first (color, spacing, font), then role (text, surface, border), then the qualifier (primary, muted, inverse).
Why bother if AI draws your interface
Because tokens are the most compact way to explain your style to a model.
A model can't guess your palette. Say "make it in our brand style" and you'll get somebody else's. But fifteen lines of names and values fit into any prompt, and with them the model stops inventing — it uses the names you gave it. This is also the working cure for AI making every interface look identical.
The practical minimum to start with: colors, a spacing step, font sizes, corner radii. Four groups already cover 90% of the benefit.
How is a token different from a CSS variable?
A variable is a storage mechanism in one technology. A token describes intent independently of language: from it you generate the CSS variable, the Swift constant, and the style in the design file. Plus a token has a type and can reference another token.
Is this the same token AI charges me for?
Not at all — just the same word. A token in language models is a chunk of text your request is priced by. A design token has nothing to do with billing, lives in the design system, and never touches a model.
Where do I start if the project already exists?
Don't rewrite everything. Collect what's already in use — you'll usually find a dozen nearly identical colors. Collapse them into five or six roles, give them names, and migrate components one at a time. Start with colors: they show results fastest. From there this grows naturally into a design system.
The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.





