Vercel DESIGN.md: Spec-Driven UI That Fights AI Slop

Update — September 11, 2026: Systems-software companion — SMART: design docs as the regenerable source of truth for ML performance code (arXiv 2609.05364). Same markdown-as-contract idea, applied past UI into agent-regenerated libraries.

Design systems as Markdown for machines. That is the move Vercel circulated between August 31 and September 1, 2026: a canonical design.md at vercel.com/design.md encoding colors, typography, spacing, and related rules so AI-generated pages inherit Vercel's visual language instead of default purple-gradient slop.

The post landed in a week already dense with interface experiments — Runway Solaris generating UI without HTML, micro-gesture writing UX rejecting chat-only controls — but Vercel's bet is different: keep code as the deliverable, tighten the spec agents read before they write it.

TL;DR

What vercel.com/design.md encodes

Vercel's public Markdown file is a machine-readable design contract: not a Figma export, not a loose README, but structured guidance an agent can load before emitting components.

Typical sections (exact headings live on the live file):

• Color roles — background, foreground, accent, destructive, muted — with hex values agents must not invent
• Typography — font stacks, sizes, weights, line heights tied to semantic roles (display, body, mono)
• Spacing rhythm — scale agents should reuse instead of arbitrary padding: 13px
• Component vocabulary — how Vercel names surfaces agents should prefer on v0/Vercel-branded output

The framing Vercel used on X: fight "slop" — visually plausible, brand-anonymous AI UI — by giving models the same document a human designer would onboarding to the system.

Pure UI (2015) → Markdown + stylesheet + tests

Vercel explicitly connected the file to Pure UI — the 2015 idea that UI should be a pure function of spec + data, not one-off JSX improvisations.

The 2026 stack adds three loops Pure UI did not have:

1. Markdown spec (design.md) — agent-readable intent + values
2. Stylesheet enforcement — tokens compile to CSS/Tailwind the agent must reference
3. Test loops — visual or accessibility checks before merge (WCAG linter patterns from the Google Labs spec are the same family)

That is spec-driven rendering with agents in the loop — not replacing engineers, but constraining degree of freedom on first draft.

What Vercel measured — and what the 57% number actually means

Vercel's engineering blog (August 31, 2026) published hard numbers alongside the public file — rare for a design-system launch. After more than 200 agent runs across seven frozen scenarios, the team ran a controlled A/B test on three desktop prompts: Codex with GPT-5.5 generated each page once with design.md loaded and once without, keeping prompt, mock data, viewport, and model identical. No re-rolls — first attempt only.

Deterministic checks then counted known failure modes the team had already seen and encoded (table width ignoring available space, evidence squeezed into prose columns, etc.):

Two caveats matter for builders copying the pattern:

1. The checks only catch failures you have already named. A 57% drop in recorded failure types says nothing about overall design quality or novel slop patterns the harness has never seen.
2. Zero pages shipped clean. Every page in the six-page test — with or without the file — still had at least one failure serious enough to block shipping without human correction.

That is the honest headline behind the hype: design.md is a regression harness for visual judgment, not a "press generate and deploy" button. It aligns with Ethan Mollick's spec-not-tricks framing — encode observable decisions, then measure whether first attempts improve. The same philosophy shows up in backend work too: SMART design docs as regenerable source of truth treats Markdown contracts as software artifacts agents can re-execute against.

Before and after on a renewal proposal

The first qualitative win Vercel documented was structural, not cosmetic. Without design.md, a renewal-proposal eval produced a generic SaaS dashboard. With it loaded, the same prompt led with the renewal recommendation, pulled commercial evidence into one comparable grid, and kept supporting detail subordinate to the executive read. Typography and color shifted — but so did information architecture. That is why explainx.ai treats DESIGN.md as an IA + brand contract, not a color palette dump.

Inside the three-part stack: guidance, VBG stylesheet, eval harness

Vercel's public file is only one layer. The full system has three parts that map cleanly onto how agent teams should split responsibilities:

The Vercel Brand Guidelines (VBG) CSS API is the mechanical half agents kept getting wrong when left to prose alone. design.md instructs agents to put .vbg-report on the page root, wrap standalone output in .vbg-shell, and use semantic HTML with only the primitives the scenario earns — stat strips for KPI rows, figure.vbg-chart for inline SVG charts, .vbg-calculator for interactive number widgets. Agents document which class names exist; the stylesheet enforces how they render. Because the CSS loads in the browser, none of the implementation bytes burn context window — a practical trick for any team publishing agent-readable specs.

Corrections route to the narrowest enforceable layer, per Vercel's blog:

• Judgment ("evidence tables should use full available width") → prose in design.md
• Repeatable mechanics (spacing, type scale) → stylesheet tokens
• Mechanical failures (table width violations) → deterministic check in code

That routing is why the file stays maintainable. Without it, every fix becomes another paragraph agents interpret differently — the exact failure mode of an over-long merged prompt.

@design-agent and the production feedback loop

Shipping the eval harness was not the end state. Inside Vercel Slack, @design-agent (built on eve) loads the current design.md, builds pages against the published stylesheet, and posts full-page screenshots plus deployment URLs back to the thread. Weekly, feedback from Slack, GitHub reviews, and Figma gets grouped; repeated complaints become proposed rule changes reviewed by a human and landed in the right layer (agent prompt, skill, design.md, CSS, or check).

If people start requesting page types never covered by the seven scenarios, those requests become new eval scenarios — the same pattern OpenDesign Harness pursues for design generation at large.

Seven frozen scenarios that stress-tested the file

Vercel did not tune design.md against vague "make it on-brand" prompts. Each scenario pairs a frozen prompt + mock inputs + render settings so the only variable is the guidance file:

1. Usage and performance report
2. Renewal proposal
3. Benchmark report
4. Interactive planning page
5. Build-versus-buy brief
6. Security governance brief
7. Presentation deck

Full rounds ran all seven on both Claude Opus 4.8 and Codex with GPT-5.5. Targeted reruns isolated table-only or copy-only rule changes. What reviewers noticed: pages shared Vercel typography and color but did not collapse to one template — the planning page centered controls because readers came to change numbers; the renewal page led with the decision because readers came to approve spend. Same visual language, different task structures — exactly what Google Labs' open DESIGN.md spec argues agents need to learn (semantic roles, not one layout to rule them all).

How to build your own design.md loop (Vercel's six steps, adapted)

Vercel published a build-your-own checklist. explainx.ai's read: start manual, automate only after comparisons pay off.

1. Pick one recurring artifact with a real reader (proposal, benchmark, microsite) — not "make everything on-brand."
2. Save a baseline — first generation without new context, with prompt, inputs, config, and screenshot frozen.
3. Mine your last ten manual corrections — rewrite each as an observable rule (evidence tables use full width, not table feels cramped).
4. Publish a stylesheet if agents keep inventing spacing; document allowed class names in your DESIGN.md.
5. Run one blind A/B — same input, same model, shuffle baseline vs guided output against a short rubric.
6. Encode corrections in the file, not in hand-edited HTML — rerun to see if first attempts actually improved.

Pair the file with steering rules for Claude Code or Cursor skills so every UI task loads the spec by default. Seed structure from explainx.ai's 65+ templates rather than a blank Markdown file — blank specs reproduce the "clean means anything" problem Vercel hit when they first ported product-design to a public URL.

Three DESIGN.md implementations worth comparing

None replaces the others. A team might: adopt the open spec shape, fork Vercel's discipline for their tokens, and seed from explainx.ai templates instead of blank files.

Browse registries: top DESIGN.md registries · design-md-templates-skills on GitHub.

What the community got right — and what still breaks

Reaction threads (August 31–September 1, 2026) clustered on two truths — now backed by Vercel's own failure counts, not just vibes:

Helps:

• First-pass pages stop randomizing fonts and grays
• Agents can validate against named roles before shipping
• Shared vocabulary between design and codegen (Mollick-style specs)
• Named anti-patterns — design.md explicitly lists recurring generated-design patterns to avoid, which models follow more reliably than vague "don't be generic" instructions
• Structural IA wins — renewal proposals and benchmark pages lead with the reader's decision, not widget grids

Does not fully solve:

• Unmaintainable code — nested components, dead props, no tests (Vercel's scope is standalone report pages, not long-lived app repos)
• Interaction logic — specs cover look and composition, not state machines or API wiring
• Drift over time — unless CI enforces spec diffs, agents revert to slop on edit pass 3
• Novel failure modes — deterministic checks lag one failure behind production; the 57% metric never claimed otherwise
• Subjective quality — hierarchy and "did this page answer the reader's job?" still need human review or model judges

That is why explainx.ai pairs DESIGN.md with skills (Garden collection, diagram-design), with Claude Code's design command for artboard-native workflows, and with OpenDesign Harness-style evaluation — spec is input; harnesses judge output.

In-repo vs out-of-repo: why two skills exist

Vercel's product-design skill lives beside production code — agents read real components, shipped examples, and tokens in context. design.md exists for the gap: proposals, security briefs, and one-off report sites built in Codex, v0, or Slack agents that cannot see the monorepo. Most teams need both: a repo-local skill for app work, a public URL spec for artifacts that leave the repo. That mirrors agent markdown files more broadly — CLAUDE.md for code, DESIGN.md for pixels.

Code path vs Solaris path

Runway Solaris asks: what if there is no code to maintain — only frames? Vercel's answer: code is the product for shippable web apps, so invest in spec discipline. Pick based on job:

• Ship and maintain → DESIGN.md + codegen (v0, Lovable, Antigravity artifacts)
• Prototype feel fast → Solaris-style world models or gesture demos

Practical checklist for your repo

1. Add DESIGN.md at repo root (or docs/DESIGN.md) — start from templates.
2. Point Claude Code / Cursor skills at it for every UI task.
3. Wire contrast/a11y checks in CI — spec without lint regressions silently.
4. For marketing pages, combine with seo-geo skill patterns so typography rules cover SEO headings too.
5. Re-read spec when agents refactor — slop often returns on edit passes, not first gen.

Vercel design.md contents and community quotes reflect public posts as of September 1, 2026; live token values may change on vercel.com/design.md without notice.

Related reading

• DESIGN.md: Google Labs open spec for AI design intent
• DESIGN.md templates: 65+ blueprints for AI agents
• Top 10 DESIGN.md registries (2026)
• Runway Solaris vs code-based UI generation
• Micro-gesture AI writing UX
• OpenDesign Harness beta
• Unreasonable effectiveness of HTML in Claude Code
• Agent markdown files complete guide
• SMART: design docs are all you need for ML performance (2026)