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

Written by AI

TLDR: Vercel describes building design.md, a public brand file for coding agents, cutting a known layout failure from 91 to 39 occurrences across matched test pages.
Best for: Anyone who keeps fixing the same things in AI-built pages, reports or proposals.
The tip: Rewrite your last ten corrections as rules you can check by looking, and keep them in one design.md file. When a page comes out wrong, fix the file.
What you need: v0
Codex
Claude
The prompt: Here are the last ten corrections I've made to AI-built pages: [paste]. Rewrite each as a rule someone could check by looking at the page. For example, 'Let evidence tables use the full available width' instead of 'Make the table feel less cramped'. Group them under scope, reader and task, observable decisions, and available primitives.
our prompt
Start here: Generate the page once with no design context and save it as your baseline.
Turn your last ten corrections into one file.
Generate again with the same input, model and viewport, file loaded, and compare.
Filed note: Vercel explains how it built design.md as a public brand file for coding agents, using repeatable visual evals to turn subjective guidance into rules that produce consistent pages.

Highlights: The naive approach we tried first was to simply port product-design into a public prompt, collapsing the skill's reference files into one file any agent could read from a URL.
first attempt that fell short
The pages generated with design.md had 39 of those failures. The pages generated without it had 91, which works out to 57% fewer in this test.
measured result of the file
We created a stylesheet because agents kept inventing their own typography, spacing, and layout, so we took those decisions away from the model entirely.
why a public stylesheet was added
Excerpt: Across Vercel, we use coding agents to design and build pages that have to look and feel like Vercel. The typography, color, and composition all need to carry the same judgment that we put into the pages we already ship ourselves.
From vercel.com