An eval is a repeatable test that scores what an AI model produces. I wrote one for the rules my design system gives AI agents, expected a mountain of problems, and learned how easily a result can fool you.
You write a page of rules for an AI coding agent. Use the tokens, never a raw colour. Use the kit's button instead of building a new one. Then the agent builds something, it looks fine, and you move on. Whether your rules did any of the work, you never actually find out.
I wanted to find out, so I built an eval for the rules in my own design system. An eval is a repeatable test that scores what an AI model produces, the same way every time, so you can compare one version of something against another. I was expecting a mountain of things we had to fix. The real lesson was how easily a result can fool you.
The kit and its rules
nil-ds is a small design system I designed and built: design tokens, React components that use only those tokens, and a set of files written for AI agents as well as people. AGENTS.md holds the rules. DESIGN.md is generated from the tokens. registry.json describes the components. All three exist so that an agent building with the kit doesn't have to guess.
Writing them was the easy part. I just hadn't got round to testing them yet.
How the test works
Claude (Sonnet 5.5, running in Claude Code) got five small screens to build with the kit: a settings panel, a delete-project dialog, a chat composer, an app shell and a project actions menu. Each task ran in two arms. Arm A got the kit and its human docs. Arm B got the same, plus the agent files. Three runs each, so twelve per arm across the first four tasks.
The fifth task, the menu, was held out. Its results stayed sealed until the end, so I couldn't tune the rules to it. If the rules got better at the menu too, the improvement might be real. If they only got better at the four tasks I'd been staring at, I'd just taught to the test.
Ten rules scored every run, and every one of them is plain code: no raw colours, no invented token names, the kit's components instead of hand-rolled ones, types that compile, no accessibility violations in semantics or ARIA, and the behaviour the task asked for. No AI judged the work. Anyone can rerun every rule.
Break it and see
Before a single real run counted, I broke the checker on purpose. Every rule got a bad example that had to fail that rule and only that rule. Then each rule was switched off in turn, and a test had to go red. If switching a rule off changes nothing, that rule was never checking anything.
Here's that check, run against all ten rules:
mutation mode: disabled rule reports pass
R1 CAUGHT 8 tests failed; bad fixtures that noticed: R1, R1-css
R2 CAUGHT 2 tests failed; bad fixtures that noticed: R2
R3 CAUGHT 2 tests failed; bad fixtures that noticed: R3
R4 CAUGHT 8 tests failed; bad fixtures that noticed: R4
R5 CAUGHT 5 tests failed; bad fixtures that noticed: R5-css
R6 CAUGHT 2 tests failed; bad fixtures that noticed: R6
R7 CAUGHT 4 tests failed; bad fixtures that noticed: R7
R8 CAUGHT 1 tests failed; bad fixtures that noticed: R8
R9 CAUGHT 1 tests failed; bad fixtures that noticed: R9
R10 CAUGHT 8 tests failed; bad fixtures that noticed: R10-T1, R10-T2, R10-T2-focus, R10-T3, R10-T3-empty, R10-T4, R10-T5, R10-T5-arrows
Every rule, switched off, made at least one fixture test fail.
Don't just believe your thoughts. Test it, make sure, challenge it.
It's the habit I use on my own head, pointed at a test suite. I've already met a test that passed while checking nothing, and a checker that can't fail looks exactly like one that's passing.
The perfect score
Round 1 went better than I'd braced for. Arm B averaged 0.991 out of 1, and arm A 0.956. Then I changed one file, arm B's AGENTS.md, adding five lines based on what round 1 got wrong, and ran everything again. Arm B scored a perfect 1.000 on all twelve runs.
The results as the proof page shows them, read from the eval's own result files.
Two of the five lines I added:
5. Look a token up before you use it, never guess. Find its exact name in the token tables in `DESIGN.md` or in `src/tokens/tokens.css`. `DESIGN.md` has name tables for colour, border width, breakpoint and motion only. Use `tokens.css` for spacing and type.
**Destructive actions:** the kit has no danger `Button` yet. Use the primary `Button` and set only its `background` and `borderColor` to `var(--nil-color-danger)` through the `style` prop. Leave the text colour to the kit. Never set a raw colour.
(That second line was true of the kit the eval tested. Button has had a danger variant since.)
Why I'm still not convinced
Arm A didn't change at all between rounds. Same files, same tasks. It still moved, from 0.956 to 0.936, and on the held-out menu from 0.875 to 0.736. That drift is pure chance, and it's bigger than the gain I was celebrating. On the held-out task, the arm I didn't touch moved further than the arm I did.
Then I read what Claude actually wrote for the menu. That destructive-actions line was written for the dialog task. On the menu, Claude applied it word for word to the Delete item, and the runs that passed built Delete exactly the way the line describes. So arm B's gain on the held-out task looks like a copied sentence, not an understanding of menus. I can't prove that's the cause, but it's the only added line about destructive actions, and the code matches it.
This is the Delete item from one of those runs, as Claude wrote it:
The kit has its own Menu now, built after the eval. Its AGENTS.md calls a red button in a menu the wrong build, and marks the dangerous item with red text.
The kit's Menu today: Delete is marked with red text.
One change did hold up. Once the rules listed the exact token names, arm B looked tokens up before using them in 11 of 12 runs, up from 6. Arm A went from 2 to 3. Arm B runs that used a token name that doesn't exist went from one to none. Small numbers, all pointing the same way.
What three runs can and can't tell you
This is a probe, not a benchmark: three runs a cell, one model, one kit, five tasks. It ran in a simulated browser, so things like focus staying inside a dialog weren't checked, and colour contrast isn't part of it at all. I make no claim of statistical significance. What it does show is where to look next, and that a passing score and a working rule are two separate questions.
Before you trust your own agent rules
If you design and you're starting to write rules for agents, this is what I'd do first, and why:
Write the rule where the agent reads it. A convention that only lives in someone's head is one the agent will guess at.
Score with code. A rule checked by code gives the same answer every time, and anyone can rerun it.
Break the checker before you believe it. Give it a bad example and watch it fail. If it can't fail, it isn't checking.
Run the unchanged version twice. How far it moves on its own is your noise. A gain smaller than that is a guess.
Keep one task you never tune on. It's the only place a real improvement can show up.
Read what the agent wrote, not only the score. That's where I found the copied sentence.
Every rule, task and run is on the proof page and in the repo. You're welcome to try to break mine.