How Vercel teaches its agents design

In part 2 I called a team’s own design calls its case law, and said one team was keeping it: Vercel. In part 3 an agent kept up with 100 written decisions, and what grew was the reading for people.

So what does it take for a team to keep up? In June, John Phamous, a design engineer at Vercel, described how they do it.¹ Others record pieces of this. Evil Martians, for example, require a written reason for every exception to a design-system component.² Vercel’s is the only full practice for AI-built UI I’ve found published. Here’s what it looks like, and where it meets what I’m building.

The problem they start from

Agents copy a product’s style and patterns well. What they can’t see is why those patterns exist, because the reasons live in design reviews, pull request comments, Slack threads and people’s heads. As the post puts it: “For an agent, context that isn’t in the codebase doesn’t exist.”

Vercel’s answer is to treat accepted product decisions like code: kept in the repository, reviewed, and available to every agent working there.

What they built

Their test for what goes in lint is worth borrowing. If code can spot the problem without rendering the page, without false alarms, and there’s a concrete fix, it’s a lint rule. If it needs product judgment, it’s written guidance. If it sets a new standard, a person decides. A rule that needs many exceptions goes back to being guidance. It’s the spellchecker from part 1, with a clear test for what belongs in it.

What a decision looks like

Each decision is written up the same way.

Their advice on wording matches what I found in part 3. Skip adjectives like clear, polished or intuitive, and write decisions you can see in the result. “Destructive buttons use a verb and a noun” tells the agent what to build. A rule that buttons should be clear doesn’t. Rules also get stable IDs that state the rule, like rule/destructive-names-action. In part 3 the agent found the decisions it needed by their titles alone, so this is the same idea.

An accepted decision doesn’t always end up as text, either. It can become guidance next to the design system component, guidance in the skill, or a lint rule.

The weekly review

The weekly review is the part I find most interesting, because it’s an answer to the question part 3 left open.

Two details stand out. A comment from an experienced reviewer can raise a candidate’s priority, but the candidate still needs evidence. And no single screenshot, file or comment becomes a universal rule on its own.

The automation stops at the packet. Every change to the guidance goes through a person.

Who wins

The skill ranks its sources for conflicts. The higher one wins:

1. 01
   What the person asking wants, and the limits they set
2. 02
   Verified evidence about users and how the product behaves
3. 03
   The repository’s own guidance and the design system
4. 04
   Accepted decisions and examples, where the evidence holds
5. 05
   Patterns already shipped in the same area
6. 06
   General interface rules of thumb

Two things are worth noticing. The design system outranks the team’s accepted decisions. And shipped code ranks low, because it shows what exists, not why it’s right. In part 3, one sentence settled who wins between the decisions and DESIGN.md. Vercel wrote down the whole order.

The difference is when it’s caught

Arbiter works on the same layer. It records the design calls an agent makes while it builds, and a designer decides which become rules. Here’s Vercel’s decision template next to an Arbiter entry.

# Decision: {name}
Status: proposed | accepted | rejected
Scope:
Decision:
Rationale:
Evidence:
Exceptions:
Bad example:
Good example:
Assumptions:
Open decisions:

Vercel finds decisions after the fact, in the evidence a team already leaves behind. That gives every decision a source, but only if someone discussed it somewhere the collector can search. Arbiter catches calls as the agent makes them, including the option that lost, but it only sees the session, not the Slack thread or the review that led there.

Vercel’s record is stronger on evidence, exceptions and what’s still undecided. Arbiter’s keeps the option that lost, a screenshot, and a board for people who don’t read the code.

Case law, in practice

This is what case law looks like when a team takes it seriously: a written record, evidence behind each call, a person who decides, an order for conflicts, and tests. None of it needs Vercel’s size to start. Their own advice is to pick one surface where the same review comment keeps coming back, and write those decisions down first.