Vercel published the design file its coding agents read before building pages

Vercel published design.md on 31 August, a single file at vercel.com/design.md that its coding agents load before they build a page that has to look like Vercel. The post that announces it, written by John Phamous, also describes the evaluation the team ran to see whether the file actually helps.

What the file is

design.md is a plain Markdown brief covering typography, colour, composition, information architecture, and copy voice. It points to a companion stylesheet at vercel.com/geist/vercel-brand.css. The file exists so that agents running outside Vercel's own internal environment can still reach the same design knowledge as agents running inside it. Phamous writes that the team needed a way for the pages coming out of external tools to "still look like something we designed ourselves."

The evaluation Vercel ran

The team built the file across more than 200 agent runs, counting full rounds, targeted checks, dry runs, and failed attempts. They then tested it against seven fixed scenarios: 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.

Pages generated with design.md loaded had 39 known failures. Pages generated without it had 91. Vercel says that works out to 57 percent fewer failures in this test.

The post is careful about what that number means. Phamous writes: "Six pages is also far too small a sample to make claims about quality or reliability, and every one of them, with or without the file, still had at least one failure serious enough to block shipping." A 57 percent drop on a test set of six pages is a reason to keep going, and every generated page in the test still needed correction before it could be released.

The pattern is worth copying even if the file is not. A stable brief the agent loads on every run, kept as source in the repository and reviewed like any other config, is a way to write down judgment that would otherwise exist only in a designer's head. Pairing it with a small, fixed evaluation set that any change to the brief has to run through turns prompt work into something with a before-and-after number attached, rather than a feeling that the output looks better today.

The larger point is that Vercel is treating the instructions given to its agents as software: versioned in a repository, reviewed on change, and measured against an evaluation set that decides whether a change is accepted.

Source

Primary source: Vercel blog, 31 August 2026. Coverage: The New Stack, 2 September 2026.