How our agents build on-brand pages with design.md
Across Vercel, we use coding agents to design and build pages that have to look and feel like Vercel.
Vercel has published design.md, a public file that lets coding agents build on-brand pages outside Vercel's own codebases, in tools that can't read the internal design system files. It extends Vercel's existing product-design skill, which already guides agents working inside Vercel's repositories, to one-off pages like reports and proposals.
Vercel says its first attempt, porting the internal skill into a single public prompt, failed: different models interpreted phrases like "keep the layout clean" differently, and without the shipped examples that sit alongside the skill in Vercel's codebases, each model rebuilt the visual language from scratch. The team rewrote the file instead, testing every change against seven fixed eval scenarios, including a usage report, a renewal proposal, a benchmark report, and a presentation deck, run on both Claude Opus 4.8 and Codex with GPT-5.5.
The resulting system has three parts:
- design.md, which guides how agents frame the reader's task, structure evidence, and choose a composition, down to asset rules for the Vercel wordmark and triangle logo.
- A public stylesheet that packages Vercel's design primitives, such as headers, tables, stat strips, and chart styles, as CSS classes an agent can reference by name instead of inventing its own typography and spacing. It loads in the browser at render time rather than entering the model's context.
- An evaluation loop that pairs deterministic checks, such as a table ignoring its available width, with human review of hierarchy and composition, feeding accepted corrections back into the file.
In one comparison described in the announcement, the same model, prompt, data, and viewport produced a generic SaaS dashboard without design.md loaded. With it loaded, the page instead led with the renewal recommendation, pulled the commercial evidence into one grid, and put peer values on a single scale for comparison.
