← All work

Rosemary, a machine‑readable design system

An eval of whether Claude follows a design system’s guidance

The Rosemary foundations in light and dark: six color ramps of eleven steps, Caudex and Instrument Sans, buttons, a badge, the Human and Machine switch, a Copied status note, and a row of Phosphor icons

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.

  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 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.

The homepage in dark mode with the unguided dialog open: the photo in a bright white frame over a black overlay, with a round dark close button on the photo
Without the guidance, in dark mode. The agent wrote its own lightbox with a white frame, a black overlay and a round close button. The frame stays white because its color was written by hand.
The homepage in dark mode with the guided dialog open: the photo on Rosemary's dark side sheet, with a Close button at the top
With the guidance, in dark mode. The agent used Rosemary's sheet and its secondary Close button, which turn dark with the rest of the page.
The same unguided dialog in light mode: a white-framed photo over a black overlay
Without the guidance, in light mode.
The same guided dialog in light mode: the photo on Rosemary's paper side sheet, with the room still visible beside it
With the guidance, in light mode.

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.

  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 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.

Make the photo on the homepage open a larger version in a dialog when it is clicked, with a way to close it.

The request, word for word. Expected: .sheet, .icon-button, .button.

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:120background: rgb(0 0 0 / 0.75);color: use a role or ramp step
  • src/pages/index.astro:138background: rgb(0 0 0 / 0.6);color: use a role or ramp step
  • src/pages/index.astro:139color: #fff;color: use a role or ramp step
  • src/pages/index.astro:140font-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.

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.

  • --duration-quick 150 ms

    Hover and press on controls: color, border and underline changes.

  • --duration-settle 350 ms

    Prints, shelf objects, the side sheet and page changes.

  • --duration-slow 700 ms

    Scroll reveals and the lightbulb.

  • --stagger 80 ms

    The gap between items that enter one after another.

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.

  • Athens CityScout
  • Theming
  • Retired Deprecation
  • Enablement
  • Button Components
  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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-right
  • arrow-left
  • external
  • close
  • menu
  • mail
  • download
  • calendar
  • play
  • sparkle
  • sun
  • moon
  • success
  • warning
  • danger
  • info
  • linkedin
  • medium
  • instagram
  • lock
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.

  1. The text face

    Instrument Sans Picked

    Writing & talks

    Writing & talks

    The same words at 100 and 75 percent width, one font file.

    Figtree

    x-height
    0.50, against 0.51
    Width
    Even
    Tabular figures
    Both have them
    Width axis
    None
    File size
    About 10KB, against 18KB

    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.

  2. The weight of a small icon

    Regular everywhere

    A 1px line beside text with a 1.46px stem.

    Match the text Picked

    A 1.5px line, the closest weight to the stem beside it.

    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.

  3. A short reply to an action

    Inline note Picked

    emailCopied

    Toast

    Email address copied

    Label swap

    Copied

    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.

New sticker!

Field notes

Little things are hidden around the site. Find all nine to earn one of my sticker designs.

On the shelf

  • The tea on the table looks a little too full.
  • Someone should top up that mug once it runs dry.
  • The plants around here like a little attention.
  • The paper lamp on the shelf has a switch.
  • The red book on the shelf opens.
  • Turn the lights off and look near the plants.

Beside the menu

  • There is a cord hanging beside the menu.

Writing & talks

  • The projector on Writing & talks is ready to roll.

Studio

  • The laptop on the Studio page could use more stickers.