Make the design system easy for an agent to use
Expose real component examples, token roles, and enforceable constraints through the simplest useful interface.
Say your agent keeps picking the wrong button. It usually isn't ignoring you — it can't find the right one, see how it's meant to be used, or check its own work. A few clear examples beat a big new filing system.
Data your tools can read (machine-readable data) helps your tools find things. It won't make your agent follow rules or make things accessible on its own.
Why this matters
An agent that cannot discover the right component, token, or variation will invent one. Discovery plus a way to check the result prevents a second shadow system growing beside yours.
What to understand
Give the agent the token source and each token's role, import paths and key variations, an everyday example plus a hard one, layout ownership and small/large behavior, and how to tell a wrong result. Back the rules that matter with checks that run: lint for forbidden imports, types for invalid combinations, runtime schemas for bad shapes, rendered checks for readability. Generate repetitive lists from code; keep guidance close to the code or in a short DESIGN.md.
Watch for
- A description that claims readability without a checked color pair.
- Broad bans that block good one-off work instead of mistakes you have seen.
- Assuming file access means clean code mapping, full state coverage, or rule enforcement.
- Claiming fewer errors without a test you can repeat yourself.
Strong default
Add small checks tied to real mistakes, not blanket "use tokens" sentences. Expose JSON only when a consumer needs it, in the format it expects, with your extra fields labeled as yours. Add a helper service only when finding things, size, or freshness is the actual problem.
When this doesn't apply
A tidy local setup does not need to become a service to count as professional. If retrieval is not the problem, a connector adds surface without fixing behavior. Same for structured token formats — use them for a real consumer, not on principle.
In practice
If the tool that handles your tokens needs JSON, use the format it expects. The Design Tokens Community Group format defines properties such as $value, $type, and $description. Label your own extra tooling fields clearly as your addition, not part of the standard.
{
"text": {
"default": {
"$type": "color",
"$value": {
"colorSpace": "srgb",
"components": [0.09, 0.13, 0.2],
"alpha": 1
},
"$description": "Primary text on the default reading surface."
}
}
}Check the actual pair for readability, and confirm your tools support the version you picked. Give your agent a realistic task with your system: which components it imported, what it built, how it recovers, how it behaves. Write down what it guessed wrong, then fix the example or add a small check.
Verify
Which components did it import? Does the result recover when something fails? Is the color pair actually readable where used? Repeat the task and confirm the fix holds.
Related skills
Use $system and $context to improve existing guidance, and $craft to judge what the agent actually made.
Last updated on