Design tokens an agent can understand: DTCG format and semantic layers
A design token an agent can read uses the DTCG format: $value, $type and references between layers. How to write them and why they keep AI from guessing colors.
{color.action.primary}, it knows what to use without guessing a hex code.What is a token and why does it matter with agents?
A token is the smallest named piece of a design system: a color, a size, a shadow or an animation duration. Design teams have used them for years to keep things consistent. With agents, the token has a new job: it is how the AI knows which color to use without you repeating it in every prompt.
If the agent has no tokens, it fills the gap with values that look reasonable. That produces colors and spacing nobody approved, and complicates token parity between design and code. The problem is not that AI is “bad with colors.” You gave it a description with no source of truth.
What format should you use?
In October 2025 the Design Tokens Community Group published version 2025.10, the first stable release of its specification. It is a W3C Community Group, but the document is not a W3C Standard. The basic rules of the format are:
- Each token is an object with
$value(required). $typedeclares the type (color,dimension,fontFamily,duration,number…). It is optional on each token, because the type can come from elsewhere: an alias inherits the type of the token it points to, and otherwise the token inherits it from the closest parent group that declares one.- Tools must not guess the type by inspecting the value: if the type cannot be determined by either route, the token is invalid.
- An alias uses curly braces:
{color.blue.500}. - A group has no
$value; it only organizes.
A minimal file looks like this:
{
"color": {
"blue": {
"500": { "$type": "color", "$value": "#1F4FD8" }
},
"action": {
"primary": { "$type": "color", "$value": "{color.blue.500}" }
}
}
}
You do not need to memorize the specification. What matters is that the file is valid JSON and every token’s type is explicit, on the token itself or on its group, so any tool, and any agent, reads it the same way.
The specification defines simple types (color, dimension, font family, font weight, duration, cubic Bezier, number) and composite types (shadow, border, transition, gradient, typography). It also supports modern color spaces such as Display P3 and Oklch.
Before relying on a tool, check which version of the format it supports. Style Dictionary, for example, has first-class support for the DTCG format since version 4, but its documentation says version 2025.10 is not fully supported yet and that this is planned for version 5. Figma, Adobe, Sketch, Penpot, Tokens Studio and Zeplin are listed among adopters of the format in the group’s FAQ.
How should the layers be organized?
For agents, the most useful split is two layers:
| Layer | What it holds | Example | Who changes it |
|---|---|---|---|
| Primitive | Raw values | blue.500 = #1F4FD8 | Brand design, rarely |
| Semantic | Usage roles | action.primary = {blue.500} | Product design |
The agent should always use the semantic layer in component code. If it needs to change dark theme, you change which primitive each role points to, not each component. For a broader view of how layers are organized, read token architecture.
How does an agent read them?
The agent reads the file at the start of a task, if you tell it to. Two things help:
- An instructions file in the repo that says where the tokens are and that they must be used. What you write in CLAUDE.md or AGENTS.md enters the context every time.
- A build step, such as Style Dictionary, that converts tokens into CSS variables, for example
--color-action-primary. The agent writes CSS with those variables and the result lives in one place.
This is context engineering applied to design: you do not ask the agent to remember the colors, you give it the file where they are.
When should you NOT use a token file?
- When the product is a one-day prototype. Maintaining tokens has a cost; if you will throw the code away, use direct values and do not waste time.
- When the team disagrees on the names. A file with names nobody uses is worse than none, because the agent will use it anyway.
- When you change values directly in the code instead of in the file. Then there are two sources of truth and the agent will pick whichever it sees first.
Example
Illustrative example: a team has the primary button’s #1F4FD8 written in 14 files. They create tokens.json with a primitive and a semantic layer, and generate tokens.css with Style Dictionary. Then they change action.primary to point to another blue and run the build. The 14 files change without being touched. Later they ask the agent to create a secondary button; the agent uses --color-action-secondary because it found it in the generated CSS.
The real change is not the color. It is that the agent no longer has to decide which blue to use.
Common mistakes
- Putting direct values in components and leaving the tokens “for reference.”
- Naming tokens after their color (
light-blue) instead of their role (surface-subtle). When the brand changes, the name lies. - Leaving a token with no type and no group that declares one, and expecting the tool to guess. Under the specification, that token is invalid.
- Using circular aliases (A points to B and B points to A). The specification requires tools to report them as errors.
- Letting the agent create new tokens without review. Ask it to propose the change in the file and approve it yourself.