Vercel's design.md keeps AI coding agents on-brand with a stylesheet and eval loop

From repo skill to a public file

Vercel runs coding agents that design and build pages meant to look and feel like the company's own work — the same typography, color and composition. According to a Vercel blog post, an internal skill called product-design handles this inside its repositories: the skill sits next to the code it governs and explains how agents should find and understand Vercel's design system, plus the product guidelines for whatever they are building.

That breaks down outside the repo. Reports, proposals and one-off pages still need to carry the brand, but they often get made in tools that cannot read those files. Vercel's answer was design.md, one file published at a public URL that any agent can load, no matter where it runs.

Why a straight port failed

Vercel's first attempt was to flatten product-design into a public prompt. The results disappointed: different models read the same description of the visual language and produced wildly different pages. Part of the problem, the company says, is that design language is subjective — asking for a "clean" layout can mean almost anything. The deeper issue was context: inside a repository, the skill sits surrounded by real components and shipped examples of the things it describes, while a standalone prompt has none of that, leaving every model to rebuild the style from words alone.

So Vercel started over, writing a new file from scratch and testing every change against a fixed set of eval prompts. It wrote seven, drawn from real use cases and paired with mock inputs: a usage and performance report, a renewal proposal, a benchmark report, an interactive planning page, a build-versus-buy brief, a security governance brief, and a presentation deck. The prompts stayed frozen while the file changed, so any difference in output traced back to the guidance.

The first measured result

For the first test, Vercel ran the renewal proposal eval twice in the same environment with the same model — once without design.md and once with it — keeping the prompt, data and viewport identical, with each version generated once and no rerolls. Without the file, the model produced a generic SaaS-style dashboard. With it, the page led with the renewal recommendation itself, pulled the commercial evidence into a single grid, placed peer values on one scale so they could actually be compared, and kept supporting detail available without letting it compete with the summary. Vercel concluded the file was shaping the page's structure and hierarchy, not just its styling.

Three layers: guidance, stylesheet, evals

The finished system has three parts:

• design.md itself, which tells agents how to shape a page for both a quick executive read and a detailed audit, write copy with concrete claims and honest caveats, compose hierarchy, typography and color so evidence and prose support each other, and publish as Vercel, down to asset rules for the wordmark and the triangle logo. It also names the recurring generated-design patterns Vercel never wants to see; giving those patterns names made agents far more reliable at recognizing and avoiding them.
• A public stylesheet. Because agents kept inventing their own typography, spacing and layout, Vercel took those decisions away from the model entirely. The stylesheet packages design-system primitives — headers, tables, stat strips, chart styles — as CSS served from a public URL, while design.md documents the class names and tokens so agents use them directly in the HTML. The agent never reads the stylesheet: it loads when the page renders in the browser, so none of that code enters the model's context, leaving more room for guidance.
• An evaluation loop. Deterministic checks catch mechanical failures, such as a table ignoring the width available to it, while people judge the subjective parts that cannot be automated — hierarchy, composition, and whether the page actually gives the reader what they came for.

How rules made it in

According to Vercel, nothing entered design.md except through this loop. Pages were generated from fixed scenarios, reviewed, and the accepted corrections encoded back into the file, then the scenarios were rerun to confirm each change stuck, because a fix that helped one artifact could quietly hurt another. A full round generates all seven pages against the current version of the file on both Claude Opus 4.8 and Codex with GPT-5.5, with narrower reruns for targeted changes such as a rule affecting only tables. Comparing the seven outputs side by side also showed the file was not pushing everything toward one template: the interactive planning page led with its controls, while the renewal proposal led with the recommendation.

Why it matters

This is one of the clearer public blueprints for agent-driven UI work. Its central lesson is that prose alone is a weak interface between a brand and a model, because subjective instructions get interpreted differently by every model reading them. The fix is to constrain the model deterministically — a stylesheet with named classes and tokens — and to convert human design judgment into an eval loop, mirroring the broader shift in AI engineering from hand-written prompts to tested, iterative guidance. The pattern generalizes beyond Vercel: any team whose agents generate user-facing pages can publish a guidance file plus a stylesheet and iterate against frozen scenarios, and letting the browser load what the model does not need to read is a cheap win for context efficiency.