Where DESIGN.md fits

In part 1 I argued that agents follow a short list they always see far better than a long handbook, that detail should arrive when it’s relevant, and that the reason behind a rule is the first thing to get lost.

Meanwhile, designers have been busy. Google open-sourced DESIGN.md in April.¹ A community collection of DESIGN.md files passed 118,000 GitHub stars in six months.² Anthropic’s frontend-design skill has around 931,000 installs.³ And 18 of 21 major design systems now let agents look them up directly.⁴ So where does it all fit?

Five things designers have built

Designers have built plenty of general taste and plenty of written standards. Almost nothing holds a team’s own calls with the reason attached.

DESIGN.md, up close

DESIGN.md is one markdown file: exact values for colour, type and spacing at the top, prose describing the intent below, and a Do’s and Don’ts section at the end. It’s the one format here with a built-in place for the reason. Some community files add a Known Gaps section telling the agent what the file doesn’t cover, which is worth copying.

Atlassian tested it two ways.⁵ In a keynote demo, Figma Make built a dashboard from the same prompt with and without their DESIGN.md. Then, in their own test setup, agents built a login screen four different ways, nine runs each and five for the skill. Atlassian says it isn’t a research paper and doesn’t name the model, but the direction is clear.

The DESIGN.md runs used 92% more tokens than looking things up, varied far more in cost, and rebuilt Atlassian’s components from the description instead of importing the real ones. The file says what a button looks like, not which button to use. Atlassian’s full guidance for agents is about 2.5 MB, and the file holds 80 KB of it.

For prototypes it still helps: in the dashboard demo, the output went from generic to recognisably Atlassian. For production, Atlassian recommends looking things up plus lint. So DESIGN.md works best as the cheat sheet, with tokens, intent, Do’s and Don’ts, and pointers to the rest.

Taste packs are a design school

The most-installed design context is general taste: Anthropic’s frontend-design, Impeccable, Emil Kowalski’s skills and Vercel’s guidelines. They help, most of all with smaller models.⁶ Think of them as a short course at a great design school.

• It’s anyone’s taste. The same pack runs in hundreds of thousands of projects, and Impeccable’s creator admits skills like these make everything look alike.⁷
• Taste moves. frontend-design now warns against a cream background, a serif display face and a terracotta accent. That terracotta, #D97757, is Anthropic’s own brand accent.
• It doesn’t know your system. Your system has to win when the two disagree, so say so in writing.

The model itself may count for more than any pack. In Meta’s public nightly test, a plain, popular component library the models already know beats Meta’s own design system on most nights.⁸

Looking things up needs a nudge

Design system teams have gone all in on letting agents look things up. Part 1’s warning still applies: agents often don’t go and look. In a Storybook test, the agent made zero look-ups without a one-line pointer in its instructions, and failed. With the pointer, it made 22 to 30 and passed.⁹

The always-read file has a second job: telling the agent which tools to use, and when.

The strongest evidence comes from Sanity, who ran 30 builds per setup on three model sizes.¹⁰ For the mid-sized model:

Accessibility violations fell from 5.1 to 0.6 per build. The redesign of the system was tested alongside the new context, so not every gain belongs to the context, but the direction matches everything else: clear docs, real examples and checks. A census of 21 design systems summed it up: “Structure checks. Instruction hopes the model complies.”⁴

Reviewers check against someone else’s taste

The best-known design-review agent for Claude Code screenshots the changed flow at desktop, tablet and phone widths, then sorts what it finds from blockers down to nitpicks, described as problems a user would hit.¹¹ That’s good critique. Like most reviewers, though, it checks against general principles modelled on other companies. A reviewer is only as good as what it checks against, so give it your team’s decisions.

The empty shelf

Put it all together and you get a stack, from the most general knowledge to the most specific.

1. The model

   General taste

   Every AI lab

   Improving

2. Taste packs

   Generic taste, anyone’s

   frontend-design, Impeccable, Vercel’s guidelines

   Crowded

3. Written law

   Your tokens, components and usage

   DESIGN.md, Figma, Storybook, zeroheight, lint

   Growing fast

4. Case law

   Your team’s calls, with a reason, an owner and a date

   Vercel’s design team, in-house

   Nearly empty

5. Examples

   Approved screens and code

   Storybook stories, Figma frames, Mobbin

   Growing

The reasons exist, but they’re stranded. Figma’s agent chats are shared with everyone on a file, and there’s no documented way for a coding agent to read them. Design-rationale documents are written for stakeholders, not agents.

One team does keep case law. Vercel’s design team writes each decision up with a status, reasoning, evidence, exceptions and examples, and every week a person reviews new evidence and decides whether it becomes guidance, a lint rule, an example or nothing.¹² It runs in-house, with a person making every call, and it’s the clearest picture I’ve found of what case law for agents could look like.

Nobody has yet measured whether giving an agent the reason improves what it builds. I expect it does, but it’s still a hypothesis.

That’s the layer I’m building Arbiter for. It records the design calls an agent makes while it builds UI, with the reason and the option that lost, and a person decides which become rules. The demo board shows what that looks like.

How to put it together

1. 01
   Keep DESIGN.md short. Tokens, intent, Do’s and Don’ts, pointers, and a Known Gaps section.
2. 02
   Turn tokens into checks, so the agent can’t get them wrong.
3. 03
   Point to where the detail lives, so the agent actually looks.
4. 04
   Use a taste pack as the floor, and say in writing that your system wins.
5. 05
   Write down team calls with a reason, an owner and a date, somewhere the agent will see them.

Design school, written law, case law

This year designers built the design school and most of the written law. What’s still missing is the case law: the everyday calls a team makes, why it made them, and who can change them.

Open your DESIGN.md or rules file and count the lines that say why. That number is a good place to start.