How Vercel Builds Brand-Aligned Pages with design.md
1. Outside the repository, brand context was lost
Vercel needed a way for agents to use the same design judgments even outside the codebase.
- Inside the repository, the product-design skill could read the design system, components, and real launch examples together.
- External tools for creating reports, proposals, and standalone pages did not have that context.
- Simply moving the existing guide into a public prompt was not enough either.
- Subjective phrases such as “clean layout” were interpreted differently by each model.
- The same instructions still produced results with very different structures and styles.
2. They separated roles among design.md, a stylesheet, and an evaluation loop
Rather than leaving brand consistency to the description in a single file, they structured it into three layers: judgment, means of expression, and verification.
- design.md guides judgments about the reader’s task, the evidence structure, composition, and copy.
- They also named the bad design patterns that agents repeatedly create so they could avoid them.
- A public CSS stylesheet restricts classes and tokens for typography, spacing, tables, and charts.
- Because CSS is loaded in the browser, it does not take up model context.
- It prevents the agent from reinventing repeatable visual elements each time.
- The evaluation loop uses human design judgment together with deterministic checks.
- Hierarchy and composition are compared by humans in blind A/B tests.
- Mechanical failures such as tables that ignore width are checked in code.
3. Not only the style, but also the page structure and error rate changed
They kept only the rules that improved real outcomes through repeated comparison under fixed conditions.
- They applied the same prompt, data, model, and viewport to seven scenarios taken from real work.
- The results using design.md were not limited to changes in color and typography.
- A refreshed proposal page surfaced recommendations first and reorganized commercial rationale into a comparable structure.
- Even different pages kept an information architecture suited to each reader’s purpose, rather than the same template.
- In a test comparing three desktop scenarios after more than 200 runs, known failures dropped from 91 to 39.
- That was about a 57% reduction, but the sample was only six pages, and all results still had failures that blocked release.
4. Repeated feedback is turned into rules for the next run
Even after passing fixed evaluations, they update the system by tracking whether the same complaints decrease in actual use.
- Slack’s @design-agent loads design.md and the stylesheet, creates the page, and shares screenshots and the deployment URL.
- Feedback from Slack, GitHub, and Figma is collected weekly and turned into change proposals for recurring issues.
- Problems of judgment are reflected in design.md, reusable expression in CSS, and mechanical errors in inspection code.
- Even when automation proposes changes, a person reviews the final application.
