A design token is a platform-neutral design decision stored as structured data: a name, a value, a type, and a description in a .tokens.json file. A CSS variable is one place that decision lands after compilation: a runtime value in a stylesheet, scoped to the web. The token is the source of truth. The variable is an output. If your system treats the variable as the truth, everything downstream of the web (iOS, Android, email, design tools, and now AI agents) is on its own.
That's the whole answer. The rest is why it matters more in 2026 than it did when people first started asking.
Start with what a CSS variable actually knows. --color-text-primary: #0A0A0A tells the browser one thing: when asked, resolve to this value. It has no type. It has no description. It doesn't know whether it's a color or a length until the moment it's used. It can't tell you why it exists, what it replaced, or which components depend on it. It lives on one platform, and its meaning lives in the head of whoever named it.
Now the token version:
"color": {
"text": {
"primary": {
"$value": "#0A0A0A",
"$type": "color",
"$description": "Default text color for body copy on light surfaces."
}
}
}Typed. Described. Versionable in git. Platform-neutral, because since the Design Tokens Community Group shipped its first stable spec (v2025.10), this format is a standard, not a house style. From this one source you compile CSS custom properties for the web, XML for Android, Swift for iOS, JSON for your documentation site, and whatever the next platform turns out to be. Style Dictionary and its peers exist precisely to make the variable an artifact of the token, never the other way around.
So when someone says "we already have CSS variables, aren't those tokens?", the honest answer is: they're one-third of one. You have names and values on a single platform. You're missing the type system, the meaning, and the neutrality. Which used to be a pedantic distinction, and then the audience changed.
Because the newest consumer of your design system doesn't read your stylesheet. It reads your data. An AI agent asked to build UI against your system can do one of two things. It can infer your intent from compiled CSS, which is archaeology: guessing at meaning from artifacts. Or it can read a token file that states the intent outright: this is a color, it's for body text, it sits on light surfaces. The first is a guess that looks right until it doesn't. The second is a lookup.
I've watched this difference in production. On our platform (8,000 users at a Fortune 250 utility), agent-built UI held at the structural level and slipped exactly where meaning wasn't machine-readable: which value applies to which element in which state. A CSS variable can't close that gap, because the gap is semantic and a variable carries no semantics. A token does, and the tiers above it (semantic aliases, component tokens) carry more.
The practical migration, if you're standing on a pile of CSS variables today, is more renovation than rebuild. Inventory the variables you have. Promote each one to a DTCG token with a $type and an honest $description; the description matters because it's documentation an agent can read at query time. Rebuild the reference chain so semantic tokens alias primitives instead of repeating values. Then compile back to the exact CSS variables you started with. Your stylesheets don't change. Your source of truth does. From the outside, nothing happened. From an agent's perspective, your design system just became legible.
One fairness note: CSS variables are excellent at their actual job. Runtime theming, cascade-aware overrides, dark mode via media queries: that's variable territory, and tokens don't replace it. The point isn't that variables are bad. The point is that an output format makes a poor source of truth, and for ten years we got away with pretending otherwise because every consumer was a human who could fill gaps with judgment. The new consumer can't. Feed it decisions, not leftovers.
The free starter kit at tokenstoagents.ai/kit includes a three-tier DTCG token set with the compile config, ready to diff against your own variables.