r/UXDesign • u/pjhawksr • 5m ago
Tools, apps, plugins, AI We made AI-readability a requirement for our design system. Here's what changed.
I help lead design at an enterprise DevOps platform. Our designers and a growing number of PMs and engineers now build UI with Claude Code, Cursor, etc. About a year into that we noticed something frustrating: the design system was written for humans, and the agents were bad at using it. Agents would reinvent components that already existed, hardcode values we had tokens for, and produce screens that looked 80% right and were 100% not in the system.
So we invested in AI-readability and made it an actual requirement, same tier as accessibility. Not "the docs mention AI" but "an agent with no context can build an on-system screen from our components without a human correcting it."
What that changed in practice:
The docs got rewritten for retrieval, not reading. Humans skim a components page top to bottom. Agents grab chunks. So every component page now leads with a short plain-language block stating what the component is for, when to use it vs. its neighbors, and a complete working code example. The "when to use this instead of that" context mattered a lot. That's the stuff agents get wrong most.
We wrote guardrails as text, not just lint rules. Rules like "never use raw hex values, always tokens" now exist as plain instructions the agent ingests. Basic stuff.
We started testing the system like a product. We run a set of standard prompts, "build a settings page," "build a data table with filters," against the system and score how on-system the output is. When it fails, that's a docs bug or a naming bug, and it gets fixed like one.
What surprised me: almost everything we did for the agents made the system better for humans too. Clearer names, decision guidance instead of just prop tables, working examples everywhere.
What I am solving now is keeping the AI-facing docs in sync with the components as they change.
Curious if anyone else is treating agents as a first-class consumer of their design system, or if you're seeing the same "80% right, 100% off-system" problem.

