Your agent invented 14 shades of blue: auditing AI-generated design tokens
AI coding agents love inventing tokens: bgPrimaryBlue, color-blue-1, primary_hover_2. Here's a 15-minute audit that catches naming chaos, missing semantics, and accessibility failures before they fossilize in your codebase.
Ask an agent to "build the settings page" and it will. It will also invent bgPrimaryBlue, color-blue-1, and primary_hover_2, three names for the same hex value, none of them in your token system. Multiply by every AI-assisted PR and your design tokens quietly become a junk drawer.
The fix isn't banning agents from touching styles. It's a 15-minute audit you run before the chaos fossilizes.
The audit
Pull your token file (JSON, CSS variables, Tailwind config, whatever you use) and check five things:
1. Raw values in components
Search your components for raw hex, rgb, and pixel values that should be tokens. Every hit is a token the agent invented instead of reusing.
# hex colors hiding in component files
rg -g '*.tsx' -g '!*.test.*' '#[0-9a-fA-F]{3,8}\b' components/ | grep -v 'token'
Zero is the target. Anything above zero is a fix-or-token decision.
2. Two names, one value
Dump every token value and look for duplicates. #2563eb called primary in one file and brand-blue in another means the agent couldn't find the existing token, which usually means your naming is undiscoverable, not that the agent is lazy.
3. Mixed casing, mixed conventions
bgPrimaryBlue next to color.background.primary next to BLUE_500. Pick one convention (we like category.property.variant, all lowercase, dot-separated) and normalize. Agents copy the patterns they see, mixed conventions in, mixed conventions out.
4. Missing states
Agents generate the happy path: default, maybe hover. Audit for the states they skip:
disabledandfocus-visiblevariants- Error/destructive tokens (not just success)
- Dark mode values, if you support it
A token system without disabled states isn't a system; it's a demo.
5. Contrast ratios
Run your text/background pairs against WCAG AA (4.5:1 for body text). Agents pick colors that look right in the mockup and fail in the audit. This is the one machines are actually good at checking; automate it and never think about it again.
Make it stick
The audit is a one-time cleanup. The system that prevents the next mess:
- A tokens file agents can read. One canonical file, documented at the top: "use these, invent nothing."
- A lint rule, not a guideline. Stylelint or ESLint plugin that fails the build on raw values in components. Agents respect CI; they ignore wikis.
- The audit in CI. Steps 1–3 are scriptable. Run them on every PR and the junk drawer never refills.
Design tokens are a contract between design intent and code reality. Agents don't break that contract out of malice, they break it because nobody showed them the contract. Show them, then enforce it.
Related articles
AI wrote your migration: trusting database changes you didn't write
Agents write migrations fast, and database mistakes are the ones you can't roll back from coffee. What to verify before an AI-generated migration touches production data.
Context files that actually work: a field guide for coding agents
Every coding agent reads your CLAUDE.md or AGENTS.md, and most of them are wishlists, not instructions. Here's what makes context files actually change agent behavior, from rules that stick to conventions agents follow.
The prompts that survive contact with real codebases
Most prompt advice is written for demos. Real codebases fight back: undocumented modules, tribal knowledge, tests that lie. The prompt patterns that hold up when the codebase is messy and the stakes are real.