Rosemary, a machine‑readable design system
An eval of whether Claude follows a design system’s guidance

Rosemary is the design system behind this site, written for the people and the AI agents who build with it. I built an agent eval to find out whether Claude uses it correctly, asking it for nine everyday features with and without its guidance.
The challenge
Machine readable means its tokens, components, and guidance are written so that an AI agent can use them correctly, and the eval measures whether that works.
Designers now work in a repository where Claude writes much of the code.
When someone asks Claude for a dialog or a filter, the system either shapes the result or gets bypassed. A hardcoded color or a one-off button compiles and looks fine in a review, and the system slowly drifts away from the product built on it. Adoption of a design system depends on whether the right choice is also the easy choice, and that applies to an agent as much as to a designer.
I wanted to know whether guidance written for Claude changes what Claude builds.
I designed and built Rosemary myself, which gave me a small, complete system I could change freely and measure. The eval asks one thing: when a fresh Claude agent receives an everyday request, does it use Rosemary's tokens and components, or does it write its own values?
How might we make a design system as legible to Claude as it is to a designer, and find out whether it worked?
The approach
What I built
Rosemary has four parts that an agent can reach.
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-softor--surface-sunken, so dark mode works without extra work from the author of a page.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.
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.
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 runs in strict mode, so any value it finds stops the build. It gives an agent a way to catch its own drift, and it gives me a number to measure.
How I decided it
The eval tests the system, but the system came first, and most of the work in it is judgment.
The execution
The expressive layer
A system for agents has to cover more than tokens and components, because motion, illustration, and icons are where one-off decisions pile up fastest. Rosemary writes those down the same way. Its motion is three durations, three easings, and one stagger, and its illustration follows five rules that the code states and the shelf obeys.
The shelf on the homepage is the largest user of both. Its objects were drawn one at a time, and they read as one family because they share an ink, a shadow, a palette, and a box.
The details
Craft is easiest to miss in the places nobody looks, such as the ring that appears when you press Tab, the width of a digit, or what a button does under your thumb. Six of those details are below, and each one is live so that you can check it.
The research
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.
Two conditions
Every task ran in a fresh copy of the site. In the with condition the repository is exactly as committed. In the without condition the Using Rosemary section is cut from the instructions. The tokens, the components and the checker are all still in the repository, so an agent without the guidance could find them if it went looking.
Four scores
Off-system values per 100 CSS declarations the agent added, counted by the checker. Raw values in inline style attributes, which the checker cannot read. Whether the new markup uses a Rosemary component the task calls for. Whether the site still builds.
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.
The impact
What the numbers say
0
off-system values in 237 declarations written with the guidance, against 28 in 442 without it
27 of 27
runs with the guidance used the Rosemary component the task called for, against 9 of 27 without it
46%
less CSS added with the guidance, because the agent reused components instead of styling its own
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 it looks like
The checker counts values, so here is what those values look like on a page. These are a fresh run of the photo dialog request, with one new agent on each side, made for these pictures. The checker scored them 7 off-system values without the guidance and 0 with it, in line with the eval.




Request by request
The numbers above are totals. The explorer below shows them one request at a time, so you can see what Claude wrote for a photo dialog or a speaking page with and without the guidance, along with the exact lines the checker flagged and the section of instructions the guided runs had.
Each side of the explorer is the total of three runs with one model, so it shows a pattern across three runs.
The gaps it found
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.
The insights
Where it falls short
I would rather give the limits than let the numbers speak for more than they should.
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.
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.
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.
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 comes 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.
Interactive
Nine requests, two conditions
Pick a request to see what fresh Claude agents wrote for it with and without the Rosemary guidance. Each side is the total of 3 runs.
Add a small newsletter sign-up to the site footer: an email field and a Subscribe button. It does not need to submit anywhere yet.
Without the guidance
- Values outside the system
- 0 in 22 declarations
- Rosemary component used
- 3 of 3 runs (.input 3, .button 3)
- Site still builds
- 3 of 3 runs
The checker found nothing to flag.
With the guidance
- Values outside the system
- 0 in 19 declarations
- Rosemary component used
- 3 of 3 runs (.field 3, .input 3, .button 3)
- Site still builds
- 3 of 3 runs
The checker found nothing to flag.
Add a banner at the top of the homepage that says I'm open to senior product design roles, with a link to the About page and a button to dismiss it.
Without the guidance
- Values outside the system
- 1 in 28 declarations
- Rosemary component used
- 2 of 3 runs (.button 2)
- Site still builds
- 2 of 3 runs
- src/pages/index.astro:114
border-radius: 0.5rem;radius: use --radius-s, --radius-m or --radius-round
With the guidance
- Values outside the system
- 0 in 47 declarations
- Rosemary component used
- 3 of 3 runs (.button 3, .icon-button 3)
- Site still builds
- 3 of 3 runs
The checker found nothing to flag.
Add a back-to-top button that appears in the bottom right corner once a visitor has scrolled down a long page, and scrolls smoothly to the top when clicked.
Without the guidance
- Values outside the system
- 0 in 56 declarations
- Rosemary component used
- 1 of 3 runs (.icon-button 1)
- Site still builds
- 3 of 3 runs
The checker found nothing to flag.
With the guidance
- Values outside the system
- 0 in 36 declarations
- Rosemary component used
- 3 of 3 runs (.icon-button 3, .button 1)
- Site still builds
- 3 of 3 runs
The checker found nothing to flag.
On the Writing & talks page, add a way to show only talks, only articles, or everything.
Without the guidance
- Values outside the system
- 3 in 50 declarations
- Rosemary component used
- 3 of 3 runs (.filter 3)
- Site still builds
- 3 of 3 runs
- src/pages/writing.astro:154
border-radius: 999px;radius: use --radius-s, --radius-m or --radius-round - src/pages/writing.astro:149
border-radius: 999px;radius: use --radius-s, --radius-m or --radius-round - src/pages/writing.astro:148
border-radius: 999px;radius: use --radius-s, --radius-m or --radius-round
With the guidance
- Values outside the system
- 0 in 5 declarations
- Rosemary component used
- 3 of 3 runs (.filter 3)
- Site still builds
- 3 of 3 runs
The checker found nothing to flag.
Add a section to the About page with three short quotes from colleagues, each with a name and role. Use placeholder text for now.
Without the guidance
- Values outside the system
- 0 in 51 declarations
- Rosemary component used
- 0 of 3 runs
- Site still builds
- 3 of 3 runs
The checker found nothing to flag.
With the guidance
- Values outside the system
- 0 in 9 declarations
- Rosemary component used
- 3 of 3 runs (.quote 3, .quotes 3)
- Site still builds
- 3 of 3 runs
The checker found nothing to flag.
When someone clicks the email link in the footer, copy the address to their clipboard and briefly show a small "Copied" message.
Without the guidance
- Values outside the system
- 4 in 28 declarations
- Rosemary component used
- 0 of 3 runs
- Site still builds
- 3 of 3 runs
- src/components/Footer.astro:49
padding: 2px var(--space-2);spacing: use --space-N or --gap-* - src/components/Footer.astro:50
border-radius: 4px;radius: use --radius-s, --radius-m or --radius-round - src/components/Footer.astro:58
transition: opacity 0.15s;motion: use --duration-*, --ease-* and --stagger - src/components/Footer.astro:48
transition: opacity 0.15s;motion: use --duration-*, --ease-* and --stagger
With the guidance
- Values outside the system
- 0 in 4 declarations
- Rosemary component used
- 3 of 3 runs (.status-note 3)
- Site still builds
- 3 of 3 runs
The checker found nothing to flag.
Make the photo on the homepage open a larger version in a dialog when it is clicked, with a way to close it.
Without the guidance
- Values outside the system
- 15 in 102 declarations
- Rosemary component used
- 0 of 3 runs
- Site still builds
- 3 of 3 runs
- src/pages/index.astro:120
background: rgb(0 0 0 / 0.75);color: use a role or ramp step - src/pages/index.astro:138
background: rgb(0 0 0 / 0.6);color: use a role or ramp step - src/pages/index.astro:139
color: #fff;color: use a role or ramp step - src/pages/index.astro:140
font-size: 1.75rem;font-size: use a text style, --step-N or a display size
With the guidance
- Values outside the system
- 0 in 62 declarations
- Rosemary component used
- 3 of 3 runs (.sheet 2, .button 3)
- Site still builds
- 3 of 3 runs
The checker found nothing to flag.
Create a Speaking page at /speaking with a short intro and a list of upcoming events showing the date, event name, and city. Use two placeholder events and link the page from the site navigation.
Without the guidance
- Values outside the system
- 5 in 43 declarations
- Rosemary component used
- 0 of 3 runs
- Site still builds
- 3 of 3 runs
- src/pages/speaking.astro:42
padding-block: var(--space-7, 3rem);spacing: use --space-N or --gap-* - src/pages/speaking.astro:46
margin: var(--space-5, 1.5rem) 0 0;spacing: use --space-N or --gap-* - src/pages/speaking.astro:52
gap: var(--space-4, 1rem);spacing: use --space-N or --gap-* - src/pages/speaking.astro:53
padding-block: var(--space-4, 1rem);spacing: use --space-N or --gap-*
With the guidance
- Values outside the system
- 0 in 30 declarations
- Rosemary component used
- 3 of 3 runs (.index-list 3, .index-row 3)
- Site still builds
- 3 of 3 runs
The checker found nothing to flag.
Create a /now page that lists three things I'm currently working on, each with a title, a status label such as "In progress", and a sentence of description.
Without the guidance
- Values outside the system
- 0 in 62 declarations
- Rosemary component used
- 0 of 3 runs
- Site still builds
- 3 of 3 runs
The checker found nothing to flag.
With the guidance
- Values outside the system
- 0 in 25 declarations
- Rosemary component used
- 3 of 3 runs (.badge 3)
- Site still builds
- 3 of 3 runs
The checker found nothing to flag.
What the agents read
This is the section of the project's agent instructions that the "without" runs do not have. The tokens, components and checker are in the repository either way.
## Using Rosemary (applies to all styles on this site)
Every page takes its look from Rosemary. When writing or editing styles:
- **Type.** Use the text styles (`.text-hero`, `.text-display`, `.text-title`,
`.text-heading` and the rest) or `var(--step-N)`. Page titles use
`.text-display`, and the homepage name uses `.text-hero`. Never set a font
size in rem or px, or name a font: use `--font-display`, `--font-text` or
`--font-mono`.
- **Space.** `--space-1` to `--space-6` inside components, `--gap-s` to
`--gap-xl` between sections, `--gutter` at the page edges. The only other
allowed patterns are `em` insets on inline elements and
`clamp(var(--space-a), Nvw, var(--space-b))`.
- **Color.** Use roles (`--text-soft`, `--surface-sunken`, `--accent` and the
rest) so dark mode works. Drawings use the `--il-*` roles and ramp steps.
No hex, `rgb()` or `hsl()` values outside `rosemary/tokens/`.
- **Motion and layers.** `--duration-quick`, `--duration-settle` and
`--duration-slow` with `--ease-out` (controls, sheets, reveals),
`--ease-spring` (objects you touch) or `--ease-in-out` (sway), and
`--stagger` between items. Stack with `--layer-raised`, `--layer-sticky`,
`--layer-fixture`, `--layer-float` and `--layer-skip`, never a bare
z-index. Ambient motion over a second and infinite loops set their own
period.
- **Components.** Reach for the Rosemary component first: button, input,
switch, filter, badge, card, index rows, facts list, sheet, nav links,
empty state, photo print, quote, status note. Someone else's words with a
name and role use the quote. A short reply to an action, like "Copied" or
"Message sent", uses the status note beside the control that caused it. They are documented in `rosemary/components/`.
Page openings use `src/components/PageHeader.astro`.
- **Something missing?** Add it to `rosemary/tokens/` or
`rosemary/components/` and record the decision in `rosemary/README.md`,
rather than writing a one-off value on a page.
`npm run check:rosemary` lists values that bypass the system. It runs before
every build in strict mode, so any value it finds stops the build, on Vercel
as well as locally. A token with a written fallback, like
`var(--radius-s, 4px)`, counts as a miss, since the fallback can drift from
the token. It skips drawings, the case study layout and
Converge, which follow their own rules. A line that truly needs a literal
can carry a `rosemary-ok` comment with the reason.Interactive
Motion as tokens, live
Every transition on this site uses one of three durations and one of three easings. These dots use the same variables, so they move the way the controls do.
cubic-bezier(0.2, 0.8, 0.2, 1)
Settle: controls, sheets, reveals and page changes.
cubic-bezier(0.3, 1.5, 0.5, 1)
A small overshoot, for objects you touch.
cubic-bezier(0.45, 0, 0.55, 1)
Loops and swaying, such as the clothesline.
--duration-quick150 msHover and press on controls: color, border and underline changes.
--duration-settle350 msPrints, shelf objects, the side sheet and page changes.
--duration-slow700 msScroll reveals and the lightbulb.
--stagger80 msThe gap between items that enter one after another.
Your system asks for reduced motion, so the dots jump instead of travelling. The site does the same.
The expressive layer
Illustration as rules
The shelf's objects were drawn one at a time, and five rules keep them one family. They are written down in the code the way a component's rules are.
- CityScout
- Theming
- Deprecation
- Enablement
- Components
One ink
Every line is --il-line, a dark walnut, at 1.5px, and it stays that weight on screen however large the object is drawn. Joins and ends are round.
One shadow
Each object has a single hard shadow on the side away from the light, painted with no outline so that it reads as paint and not as drawing.
One palette
Drawings use only the 21 --il-* roles, each mapped onto a Rosemary ramp. In dark mode one night filter darkens them, so no drawing is redrawn.
One box
Each object fits a 100 by 100 box with its ground line at y = 96, so any object can stand on any shelf.
Light is the hover
Hovering a compartment switches its light on, and the object answers with one small movement of its own, such as the temple's scaffold coming down or the keycap pressing, using the motion tokens.
--il-line--il-wood-hi--il-wood--il-wood-lo--il-wood-deep--il-cream--il-cream-lo--il-in-back--il-in-wall--il-in-floor--il-sage--il-sage-lo--il-teal--il-teal-lo--il-terracotta--il-terracotta-lo--il-plum--il-wisteria--il-ink--il-ink-lo--il-glow
Icons, stated plainly
Rosemary does not include a custom icon set. Its 20 icons come from Phosphor (MIT, version 2.1.1), vendored into the repository, and the system's work is in how they are set: the weight follows the text beside the icon.
arrow-rightarrow-leftexternalclosemenumaildownloadcalendarplaysparklesunmoonsuccesswarningdangerinfolinkedinmediuminstagramlock
- 16px, bold
- Beside small text, captions and tags.
- 20px, regular
- Beside body text, in links and in buttons.
- 24px, regular
- Standing alone: previous, next, close.
Interactive
Six details, each one live
Craft is easiest to miss in the places nobody looks, so these are here to check, not to take on trust.
Focus you can see
Press Tab. The ring uses step 600 of the palette, the only step that clears 3:1 against the page in both light and dark.
- Trained2,500+
- Teams168
- Increase109%
- Instances1.4M
Numbers that line up
Figures in tables and stat rows are set tabular, so the digits keep their width and the columns read straight.
A press that settles
Things you touch use the spring easing, which overshoots a little. Controls that only change color use ease-out, so each kind of movement has its own curve.
Checking your setting.
Motion that stays still
When a system asks for reduced motion, the site's transitions and loops switch off. The dot sways only when your setting allows it.
text-faint, dark4.97:1
focus-ring, dark3.53:1
border-control, dark3.60:1
Contrast, measured
90 pairs are checked on every build in both themes, and the build fails if one drops below its minimum. These are the three tightest, drawn in their own colors, and they need 4.5:1, 3:1, 3:1.
- 24px, the WCAG 2.2 minimum40px, Rosemary's
Targets bigger than required
Icon buttons are 40px square, above the 24px that WCAG 2.2 asks for, so they are easy to hit with a thumb as well as a pointer.
How it was decided
Three decisions, with the options I set aside
I built Rosemary one decision at a time. Each one started as real options on the screen, and the pick became a rule in the system's record. These three show the kind of evidence each choice rested on.
The text face
I measured both, and they came out even on x-height, width and figures. Instrument Sans won on its width axis, which lets the navigation tighten on a phone without shrinking the text, and on flat-cut terminals that stay crisp at caption sizes. It costs more bytes, and its capital I and lowercase l are the same stroke, so codes and IDs go in the monospace face.
The weight of a small icon
Phosphor draws its icons in weights rather than adjustable strokes, so each size had to pick one. I measured the stem of Instrument Sans at the small text style and gave every icon the weight whose line matches the text it sits beside: Bold at 16px, Regular at 20 and 24px.
A short reply to an action
The eval found this gap: agents asked for a "Copied" message built their own each time. The inline note appears where the reader is already looking, never covers the page, and keeps the status rule of a colored icon with plain ink text. A label swap only works when the action has a button, and a toast floats far from what was pressed.