How our agents build on-brand pages with design.md

One public file that carries our design judgment

At Vercel, coding agents routinely build pages that need to feel unmistakably like ours. Previously, we introduced product-design, a skill embedded in each repository that teaches agents how to work with our design system and product guidelines. That approach works when agents operate inside our codebases, where the relevant components and examples live. But reports, proposals, and one-off pages also need to look like Vercel, and they're often produced in tools that cannot read repository files.

The solution is design.md: a single public file that any agent can load from a URL. The goal was to replicate the benefits of having design guidance co-located with code, minus the repository itself.

Why a plain prompt wasn't enough

The first attempt was straightforward: port product-design into a public prompt by collapsing its reference files into one document. That failed. While the prompt described our visual language accurately, every model that read it produced a different interpretation. Design language is subjective; phrases like "keep the layout clean" mean different things to different models.

More importantly, the prompt omitted crucial context. Inside a codebase, an agent reads product-design alongside real components and shipped examples. A standalone prompt forces every model to reconstruct our style from words alone. The fix required distilling what that environment provides into a single file, and validating each change against a fixed set of eval prompts derived from actual use cases:

• Usage and performance report
• Renewal proposal
• Benchmark report
• Interactive planning page
• Build-versus-buy brief
• Security governance brief
• Presentation deck

Prompts stayed frozen while the file evolved, so any difference in output traced back to the guidance.

The file changes structure, not just styling

Initial tests showed design.md influenced more than visual polish. Running the renewal proposal scenario twice with the same model, data, and viewport—once with and once without the file—produced dramatically different pages. Without design.md, the model generated a generic SaaS dashboard. With it, the page led with the renewal recommendation, placed commercial evidence in a grid, plotted peer values on a single comparable scale, and kept supporting detail secondary. The file reshaped page structure and hierarchy, which was enough signal to continue building guidance iteratively.

Three layers that make it work

Testing revealed that a single file couldn't carry the full burden. The system now comprises three parts:

• design.md itself, which frames how agents should think about the reader's job, evidence, and composition.
• A public stylesheet that defines a bounded set of classes and tokens.
• An evaluation loop that converts human feedback into improved guidance and deterministic checks.

design.md guides agents on structuring pages for both quick executive reads and detailed audits, writing copy with concrete claims and honest caveats, and using composition, typography, and color so evidence and prose reinforce each other. It also covers publishing rules for our wordmark and triangle logo.

An important tactic was naming recurring generated-design patterns explicitly. Tagging anti-patterns with concrete names lets agents recognize and avoid them far more reliably.

The stylesheet exists because agents kept improvising typography, spacing, and layout. It packages design primitives—headers, tables, stat strips, chart styles—as CSS any page can load from a public URL. design.md documents the class names and tokens the stylesheet provides, so agents write HTML with those names instead of reinventing styles. A side benefit: the agent never reads the stylesheet itself. It loads only when the page renders in a browser, keeping the model's context free for design guidance.

The evaluation loop keeps the other two pieces honest. Deterministic checks catch mechanical failures like a table ignoring available width, while human reviewers assess inherently subjective qualities: hierarchy, composition, whether the page serves its reader.

How guidance earned its place

Every line in design.md came through the eval loop. We generated pages from frozen scenarios, reviewed outputs, encoded accepted corrections, and reran the scenarios to confirm each change stuck without harming another artifact. Nothing entered the file through any other path.

Scenarios and rounds

Each of the seven prompts becomes a scenario: the prompt, mock inputs, and render settings are locked together. The renewal proposal always runs against the same fake customer data at the same viewport, leaving design.md as the only variable. A full round regenerates every scenario on both Claude Opus 4.8 and Codex with GPT-5.5. When investigating something narrow, like a rule affecting only tables, we rerun the affected scenarios on a single model for tighter iteration.

Generating all seven pages together revealed that design.md did not force a single template. The interactive planning page led with controls because its audience opens it to change numbers and explore outcomes. The renewal proposal led with the recommendation and commercial comparison because its reader is deciding whether to renew. Both shared the same visual language but each structured itself around its reader's task.

Review workflow

Reviewing each round's output happens in a local app that renders full pages and runs blind A/B comparisons. That app grew into the eval harness, storing for each run the prompt, inputs, model config, design.md version, screenshots, and reviewer feedback—with every correction logged against the exact run that produced it.

Corrections land where they're most effective

Each recorded correction goes into the narrowest place that can consistently enforce it. Judgment changes become prose in design.md; reusable mechanics go into the stylesheet; anything mechanically checkable becomes a deterministic code check. Harness problems stay in the harness. A failure from a single model stays out of the rules until it recurs elsewhere.

One early renewal proposal demonstrated the process. Its commercial terms table rendered squeezed to the width of the surrounding prose despite having room to be twice as wide.

Review flagged that evidence tables should use all available width. Checking previous outputs showed the failure everywhere, so the fix landed in two places:

• A rule in design.md stating the intended behavior.
• A deterministic code check to catch the same layout failure in future runs.

Later renewal proposal rounds came back with correct full-width tables. We verified changes by rerunning affected scenarios, and at milestones ran blind A/B rounds comparing the updated file against an earlier version to decide whether to keep, revise, or revert each change.

Measuring the difference

Building the file consumed well over 200 runs across full rounds, targeted checks, dry runs, and dead ends. A model judge also wrote critiques for each round alongside the human reviewers, and every round's feedback improved the next run.

To measure whether encoded corrections actually prevented their target failures, we selected three desktop scenarios and had Codex with GPT-5.5 generate each page twice—once with design.md loaded, once without. We kept first attempts only, no re-rolls. Running deterministic checks over all six pages, the sets generated with design.md showed 39 known failures versus 91 for those without, a 57% reduction in this test.

Two caveats apply. The checks only catch failures already seen and documented, so they say nothing about overall design quality. Six pages is far too small a sample for claims about reliability, and every page—with or without the file—still had at least one blocking issue. What the test confirms is mechanical: once we name a failure and encode a guard against it, that failure tends to stay gone.

Keeping design guidance honest

A document only stays useful if it is tested against reality. At Vercel, that happens through @design-agent, a Slack agent built on eve. Anyone can mention it in a thread for a design critique, copy alternatives, icon suggestions, or a report built from pasted data. For website requests, the agent loads the current design.md, builds against the published stylesheet, and posts a full-page screenshot and deployment URL back to the thread.

Each of those threads is a live test case: a real request, a real output, and the feedback that followed. Weekly, that feedback is pooled with comments from GitHub reviews and Figma. Automation clusters repeating comments, and each cluster becomes a proposed change. A person then reviews every proposal, checks whether the system already handles it, and decides where the fix belongs——@design-agent, the product-design skill, design.md, the stylesheet, or a deterministic check. A page type people ask for but that was never tested becomes a new eval scenario.

The metric is simple: how often a given complaint appears in similar work over time. After a fix is encoded, that count should fall. If it does not, the rule is likely unclear, not loaded when needed, inexpressible with current stylesheet primitives, or too mechanical for prose—and better handled as a deterministic check.

A minimal loop you can run

You can build the same system starting with one artifact and one manual comparison:

1. Pick one repeated artifact. Choose a recent task with a real reader and real inputs—a proposal, performance report, benchmark, or microsite. Write a short rubric before generating anything. It should verify the supplied facts survived, the reader's decision is clear, and the correction you keep making by hand is actually resolved.
2. Save a baseline first. Generate the page once without any design context. Keep the prompt, inputs, configuration, and a screenshot. A rough first output is fine; without a before, you cannot tell whether new context helped.
3. Start from your last ten corrections. Pull the feedback you give repeatedly in reviews or Slack, and rewrite each one as something observable. Prefer Let evidence tables use the full available width over Make the table feel less cramped—only one is checkable. Put these decisions in one file with sections for scope, reader and task, observable decisions, and available primitives. That is your first design.md.
4. Constrain repeatable mechanics. If outputs keep inventing typography, spacing, or layout, publish a stylesheet and document the exact classes and tokens the agent may use. Keep judgment in prose, and push mechanics into CSS or deterministic checks.
5. Run one matched comparison. Regenerate the page with the same input, model, and viewport, now with your file loaded. Shuffle it with the baseline and score both against your rubric without knowing which is which.

A single trial reveals the large, obvious failures, so you do not need a full runner or a model judge to start. For reliability, run multiple independent first-attempt trials (Anthropic's guide to evals for agents) and report how often the result holds.

6. Encode the correction. Compare the output with any follow-up prompts you had to send, and ask:

• What did the user have to repeat or steer manually?

• Is a rule missing or unclear?

• Can the stylesheet express the correction?

• Is the failure mechanical enough to check in code?

• Does the correction generalize beyond this output?

Update the guidance rather than hand-tuning the generated page. The next comparison will show whether first attempts actually improved.

Add tooling once the manual loop is paying off:

• Include scenarios where the guidance should and should not apply.

• Keep a small holdout hidden while editing.

• Record model and guidance versions.

• Automate mechanical checks.

• Use multiple blind reviewers.

However far you take automation, keep final changes human-reviewed. Keep the loop running on a cadence, and watch whether each kind of complaint becomes less common after you change the guidance. A passing evaluation matters less if people keep correcting the same mistake in production.

Working examples are public. Vercel loads design.md into tools like v0, Codex, and Claude daily, and the eve design agent template will get you a Slack design agent like the one Vercel runs.