Teaching Claude to use a design system

The question

How might we make a design system as legible to Claude as it is to a designer, and find out whether it worked?

What I built

Rosemary has four parts that an agent can reach.

1. Tokens as the only source

   Color, type, space, motion, layers and icons are defined once in rosemary/tokens/ and built into CSS variables. Every color is a role such as --text-soft or --surface-sunken, so dark mode works without extra work from the author of a page.

2. Fourteen components

   Button, input, switch, filter, badge, card, index rows, facts list, sheet, nav links, empty state, photo print, quote and status note. Each has a short document that says when to use it.

3. Guidance written for an agent

   The project's instructions file has a section called Using Rosemary. For each kind of decision it names the tokens and components to reach for, and it says what to do when something is missing: add it to the system and record the decision, instead of writing a one-off value on a page.

4. A checker that runs before every build

   A script reads the styles and flags any raw color, font size, spacing, radius, motion value or z-index that bypasses a token. It gives an agent a way to catch its own drift, and it gives me a number to measure.

How the eval works

I wrote nine requests of the kind a site owner makes: a newsletter sign-up, a dismissible banner, a back-to-top button, a filter on the writing page, three quotes from colleagues, a copy-email confirmation, a photo that opens in a dialog, a speaking page, and a now page. Each task names the Rosemary components a good answer would use.

Each copy got its own fresh Claude agent, started from a Claude Code session, with edits allowed and no way to ask questions. The eval folder is left out of every copy, so an agent never sees the tasks or the scoring. The second run repeated each task three times in each condition, for 54 runs with Claude Sonnet.

What the numbers say

Without the guidance, the 28 off-system values were 12 raw colors, 6 spacing values, 5 radii, 3 font sizes and 2 motion values. Examples include a 999px radius on the Writing page, a hardcoded rgb(0 0 0 / 0.75) behind a photo dialog, and a 0.15s transition that skipped the motion tokens.

The component result is the larger difference. On five of the nine tasks, the quotes, the copy confirmation, the photo dialog, the speaking page and the now page, agents without the guidance never used a Rosemary component in any of three tries. They built their own versions. With the guidance, all three tries used the system component each time. The unguided runs also produced the only failed build in the eval.

What the first run changed in the system

I ran the eval once before the second run, with one sample per task, and it showed me where Rosemary itself had gaps. In the testimonials task and the copy-email task, agents built their own quote and their own Copied message, because Rosemary had neither. The tasks at that point expected a card and a badge, which did not fit either job.

I added two components, a quote for someone else’s words with a name and a role, and a status note for a short reply to an action such as Copied. I updated the guidance and the two tasks, then reran the eval with three samples per task. The first run measured 1 off-system value per 100 declarations with the guidance and a component reuse rate of 7 of 9. The second run reached 0 and 27 of 27. The eval did the job a design system team asks of product teams, which is to report recurring gaps back into the system.

What the eval can and cannot show

I would rather give the limits than let the numbers speak for more than they should.

1. I wrote the system, the guidance, the tasks and the checker

   The guidance was written with the checker in view, so a clean score is partly the guidance doing what I designed it to do. A result from a system I did not author would be stronger evidence.

2. One model and small samples

   All 54 runs used Claude Sonnet, with three samples per task. The pattern was consistent across tasks, and I have not tested whether it holds for other models or for larger tasks.

3. The checker measures drift

   It counts values that bypass a token. It cannot tell whether the result is well designed, and a page can be fully on-system with a poor layout, so visual review of the output remains my job.

4. The site is a small system

   Rosemary has a fraction of the surface of an enterprise system. Whether the same guidance holds up across hundreds of components and several platforms is an open question, and it is the one I most want to work on.

I dropped a tenth task from the eval because the site already did what it asked. I built the eval itself with Claude Code, and it keeps the scripts, the tasks and the results of both runs.

What I would do next

The eval measures whether Claude follows the system. The part I have not done is judging the output visually, so I would add a review step that renders each result in light and dark and scores it against the system’s own principles, since an on-system page can still be a bad page. I would also run the same tasks across several models, add tasks that need a component Rosemary does not have, and measure whether an agent adds it to the system the way the guidance asks.

The same method applies to a larger system. The guidance, the checker and the eval are small enough to carry over to an enterprise design system, where a team could learn which parts of its documentation Claude actually reads.