Most design systems are written for people. More and more of the code that uses them is written by AI agents. So I tried a simple test: give an agent my design system and see what it builds when I’m not in the room.
The system is Nova, an open-source, retro-modern design system I built from an AI assistant concept: warm bone hardware, soft raised keys, one orange status light. It has one tokens file that generates four themes, a set of components, and a rules file called AGENTS.md that coding agents like Claude Code, Codex and Cursor read before they write anything.
The test
A fresh agent with no context. One prompt, the kind anyone would type:
Read AGENTS.md first. Build a settings screen for a voice assistant using only Nova: online status, wake word, save history, voice speed, theme, account name, sign out. Then list every component you needed but didn’t have, and any rule you were tempted to break.
That last line matters. An agent that has to explain itself tells you where your system is unclear.
Run one: it followed the rules and still found the holes
The screen compiled. No raw colors, no made-up shadows, one primary button. On paper, a pass.
Then I opened it in a browser and used it.
- The keyboard was broken, and that was my bug. In the option switcher, the arrow keys changed the selection but focus stayed behind. A keyboard or screen reader user would lose their place. My own docs page never caught it, because it had only ever been clicked with a mouse.
- Text fields spilled out of their panels. My docs page had a global CSS reset that quietly fixed the sizing. In a fresh app, it wasn’t there. The system only looked finished in the one place I’d tested it.
- There were no headings. Panel titles looked like headings but were styled text, so the screen had no structure for a screen reader.
- There was no way to lay things out. With no spacing component, the agent wrote nine inline styles and two raw sizes. It did that honestly, and it listed “no layout component” first in its notes.
- One rule was vague. “One primary button per screen” doesn’t help when every setting applies instantly. The agent picked one anyway.
The agent’s notes caught three of these. It never opened the screen, so it couldn’t catch the other two. When I asked it to check all four themes, it answered honestly: no.
What I changed
Version 0.2 took the notes literally:
- New components for layout (Stack), page width (Page) and body text (Text), so a screen never needs an inline style.
- Real headings: panel titles now render as h2 to h4.
- Visible labels on the option switcher by default.
- Fixes: focus now follows the arrow keys, and every component sizes itself without depending on a global reset.
- Clearer rules: layout sizes count as raw values too. If a screen has no single main action, it gets no primary button. Anything destructive needs a confirmation, and if Nova can’t provide one yet, say so.
Run two: same prompt, a new agent
| Run one (v0.1) | Run two (v0.2) | |
|---|---|---|
| Inline styles the agent wrote | 9 | 0 |
| Raw sizes (px, rem, vh) | 2 | 0 |
| Raw colors | 0 | 0 |
| Heading outline | none | one h1, an h2 per section |
| Primary buttons | 1 | 0, correctly |
The second screen looked like it came from the same hardware as everything else, in all four themes. Its notes still found gaps: there’s no page title component, no settings row, and no success message. That’s the v0.3 list.
What I took from it
An agent is the most honest new hire your design system will ever have. It doesn’t ask a teammate or copy a nearby screen. If a rule is vague, you get a vague screen. If a piece is missing, it builds a workaround in seventy seconds and tells you exactly why.
“It compiled” is not “it works.” Both agents passed the type check, and neither one looked at what it made. The keyboard bug only showed up when I used the screen like a person would. It’s the same lesson I keep relearning with AI: decide how you’ll check it, then check it yourself.
The rules file is now part of the design system. Tokens and components used to be the system. Now there’s a third layer: the instructions an agent reads before it touches anything. Writing that layer is design work, and you can test it.
Nova is free and open source. The live docs show every component in all four themes, and the repo on GitHub has the AGENTS.md file and both test screens with the agents’ notes, so you can run the same test on your own system.