How Vercel Builds Brand-Aligned Pages with design.md

Image source: Vercel · John Phamous

AI summary focused on the core points of the original article.

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.

XPLORED View

This is an example of how brand-like results become stable when observable rules, limited means of expression, and repeated evaluation are connected rather than relying on long prompts.

Good to read when

You want to reset the team’s review standards because the variance in agent-made UI is too large
You want to extend your design system into generative workflows outside the codebase

Takeaways

Turn vague taste into observable decisions and place them where they can be enforced as narrowly as possible
Instead of manually polishing the first result, accumulate recurring revisions into rules for the next run

Read original

This article is summarized and interpreted by XPLORED based on publicly available original sources and related materials. Rights to the original source and materials included in it belong to their respective rights holders. If a rights holder requests a correction or removal, we will review and respond promptly.

Get the week's signal by email, every Saturday.

A short read on the tools and articles added that week.