A design token is a design decision stored as data: a name, a value, a type, and a description, in a format any tool or agent can read. That's the definition. The definition undersells it.
Because the interesting part isn't what a token is. It's what a token replaces. Before tokens, your design decisions lived in a mockup, a stylesheet, a Slack thread, and a senior designer's memory, all slightly disagreeing. A token takes one decision, gives it one name, and makes every other copy a reference. The decision stops being folklore and starts being data.
Since October 2025 there's finally a standard way to write that data down. The Design Tokens Community Group shipped its first stable spec, v2025.10: $value, $type, $description, in a .tokens.json file. Boring on purpose. When the format stops being a debate, the work moves up to where it matters, which is architecture and meaning.
And meaning is where the three tiers come in. This is the part I find people nod at and then skip, and skipping it is why their agents guess.
Tier one, primitive. gray.950 is a value. #0A0A0A with a name. It carries no opinion about when to use it. A primitive answers one question: what exists?
Tier two, semantic. color.text.primary is a decision. It says: of everything that exists, this is what body text uses. Semantics answer the question agents actually ask: what is this for?
Tier three, component. button.label.color is a commitment. This component, this part, this token, resolved through the semantic layer, no debate at the point of use. Component tokens answer: what happens here, specifically?
Each tier references the one below. Change the primitive and the change propagates through every semantic alias into every component, everywhere, from one source edit. That's the famous brand-change collapse: what used to be weeks of hand coordination becomes a pull request. Real, and worth the price of admission alone.
But the propagation trick is the lesser half. The greater half is what the tiers mean to a machine. An agent reading only primitives sees a paint store: hundreds of options, zero guidance. An agent reading semantics sees your decisions: this means danger, this means brand, this is what disabled looks like. An agent reading component tokens sees commitments it cannot misread. Every tier you add converts a guess into a lookup.
That's why "we have tokens" tells me almost nothing about whether a system is agent-ready. Plenty of teams have a flat file of primitives compiled to CSS variables and call it a token system. It's a palette with a build step. The test that matters: if I delete your components tomorrow, do your tokens still say what things mean? A one-tier system says no. A three-tier system says yes, and an agent rebuilding from it lands on your design instead of a plausible imitation.
The practical on-ramp is smaller than teams fear. You don't tokenize the world. You pick the decisions that are already stable (text colors, surface colors, the spacing scale, the type ramp), write them as DTCG primitives, then spend your actual effort on the semantic layer, because that's the layer that carries meaning. Component tokens come last and only where precision pays, which is usually buttons, inputs, and feedback states before anything else.
One honest caveat. Tokens are the boring foundation, not the whole stack. We shipped agent-built UI on tokens without an enforced contract and watched it hit 80 percent and slip on the component details. Values alone tell an agent what exists, not what it means or when to use it. The tiers get you to meaning. The layers above (machine-readable contracts, specs, runtime context files) get you to reliable.
But it starts here, with a mental shift small enough to fit on an index card: stop naming your colors. Start naming your decisions.
The free starter kit at tokenstoagents.ai/kit ships a working three-tier DTCG token set you can rename and build on. Take it apart and keep what's useful.