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.

Optional further reading for CS 4550 / CS 5610 — not required for labs or grades. If you already use agents on labs, treat a public design brief as optional context rather than a substitute for understanding the React you submit. Follow the original Vercel post for the eval loop and stylesheet setup.

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

Related in the book: Chapter 1