design.md: teach agents on-brand pages outside the repo

On August 31, 2026, John Phamous explained how Vercel agents build on-brand pages when they cannot read the repo. The internal product-design skill works in-repo; design.md is a single public URL for reports, proposals, and one-offs that live outside the codebase. A naive port of that skill into one prompt failed because models interpreted vague design language differently without real components nearby.

The team rebuilt around seven fixed eval prompts — usage report, renewal proposal, benchmark, planning page, build-vs-buy, security brief, and a deck — and measured outputs. The system has three parts: design.md guidance, a public stylesheet of classes and tokens (the agent documents class names; CSS loads in the browser so it does not fill model context), and an evaluation loop with deterministic checks plus human review. On matched trials, known mechanical failures fell from 91 without design.md to 39 with it (57% fewer). The sample is small, and pages can still have ship-blocking issues. Weekly feedback from Slack @design-agent (eve), GitHub, and Figma keeps the file current.

The eval loop and public stylesheet are how the agent stays on-brand, next to the React you build in Chapter 1.

Read original: How our agents build on-brand pages with design.md — Vercel

Related in the book: Chapter 1