design.md: Getting AI Agents to Produce On-Brand Pages

From Scattered Prompts to a Unified Design Spec

Vercel's team recently shared their approach to getting AI Agents to build "on-brand" pages, and the core of it is a single file called design.md. What looks like a simple idea actually addresses a persistent pain point in AI-assisted frontend development — AI-generated interfaces tend to lack visual and brand consistency.

Today's mainstream AI Coding Agents (GitHub Copilot, Cursor, v0, etc.) are essentially LLM-based code generation systems. They perform well when generating individual components or pages, but struggle to maintain consistency across pages and sessions. That's because LLM generation is probabilistic — each call is an independent inference with no persistent "memory" to carry style decisions forward. Ask a model or Coding Agent to generate a page and it'll output something that looks workable, but the color choices, spacing, typography, and component styles may differ every time. Without a unified constraint, dozens of pages stitched together will feel inconsistent and off-brand. Vercel's solution: encode all design decisions into a single file that the Agent always references during generation.

Three Core Mechanisms of design.md

According to Vercel's official write-up, the system has three components that form a complete feedback loop.

One File to Encode Design Decisions and Usage Guidance

design.md serves as the "single source of truth" for the design system. It's not a simple stylesheet — it captures design decisions and usage guidance in a combination of natural language and structured rules.

Design systems are core infrastructure in modern frontend engineering. Well-known examples include Google's Material Design, IBM's Carbon Design System, and Shopify's Polaris. Traditional design systems typically consist of three layers — Figma files, Storybook component libraries, and CSS/token variables — and they're built for human designers and engineers. The innovation with design.md is that it adds a new layer on top: a format readable by AI Agents. By re-encoding design decisions in natural language and structured rules, models can directly understand and follow brand guidelines. Think of it as a "design system manual" tailored specifically for AI. This approach echoes ideas from OpenAI's system prompt engineering and Anthropic's Constitutional AI: using explicit constraints to shape the boundaries of model output.

The practical benefit is clear: Agents work from context, and a Markdown file is a format models are well-suited to understand and follow. Compared to asking an Agent to parse CSS variables scattered across a codebase or interpret a Figma file, a focused, semantically clear design.md gives the model a much more accurate picture of "what our brand should look like." It covers both hard constraints (primary color values, type scale) and soft guidance (principles like "headings should be concise and punchy").

Shaping Output Quality Through an Eval Harness

A spec alone isn't enough. Vercel emphasizes that Agent output is "shaped" by an eval harness — an evaluation framework.

Eval harnesses are key infrastructure in LLM application engineering, originally used widely in model benchmarking (such as EleutherAI's lm-evaluation-harness) and more recently evolved into quality gates in production systems. In AI-generated content pipelines, an eval harness typically includes three types of checks: rule-based checks (do color values match token definitions? do components come from the approved library?), semantic checks (does the page copy align with brand tone?), and visual regression checks (screenshot comparisons to detect layout drift). Vercel applies this mechanism to design consistency validation — essentially borrowing the quality gate concept from CI/CD pipelines. Any output that doesn't meet the spec gets caught before it reaches production, rather than relying on manual review as a safety net.

This is worth paying close attention to. It means AI-generated pages are no longer a one-shot "generate and ship" action — there's an automated quality check in the loop. The eval harness verifies whether generated output meets the standards defined in design.md: correct colors, spec-compliant components, on-brand layout. Non-compliant output is flagged before it ever reaches production.

This is essentially a migration of the software engineering concept of "test-driven development" into the more subjective domain of design consistency. By making evaluation quantifiable and automatable, the subjective quality of "visual feel" gets translated into metrics that can be verified through engineering.

Production Feedback Closes the Loop

The third component is what makes the loop complete: feedback from production gets fed back into the cycle.

This design philosophy has a deep structural similarity to Reinforcement Learning from Human Feedback (RLHF) in machine learning. RLHF is the core training mechanism that allows modern dialogue models like ChatGPT and Claude to align with human preferences — the model generates output, humans score it, and those scores feed back to optimize model behavior. Vercel's loop doesn't involve updating model weights, but it reproduces the same logic at the engineering level: production performance (real user behavior or team review) → evaluation signal → spec iteration → improved generation quality next time around. This "software-layer RLHF" gives the system continuous improvement capability without waiting for the underlying model to be updated.

In practice, real-world performance after a page ships — whether that's user behavior data, team review, or newly surfaced edge cases — becomes the basis for improving both design.md and the eval harness. This gives the whole system the ability to evolve continuously, rather than being a static ruleset.

Why This Approach Is Worth Borrowing

Zooming out, design.md represents an emerging AI engineering paradigm: rather than chasing a more powerful model and hoping it improvises correctly, give the Agent clear context constraints, verifiable output standards, and an iterable feedback loop.

This practice arrives at an industry inflection point. Between 2024 and 2025, AI Coding Agents have rapidly evolved from "productivity assistance tools" toward "semi-autonomous execution roles" — systems like Devin, SWE-agent, and OpenHands are now taking on complete development subtasks. That trend makes "how to constrain and verify AI output" a cutting-edge engineering problem. The industry uses terms like "AI Engineering" or "LLMOps" to describe the engineering discipline built around prompt design, eval frameworks, and feedback mechanisms. The "Context Engineering" approach that design.md represents — controlling model output through carefully designed input constraints — is becoming a core methodology in LLMOps practice, not unlike defensive programming in traditional software engineering.

Taken together, the three components map directly to the three pillars of software engineering: spec, test, iterate. Vercel simply applies them to the specific challenge of getting AI to produce on-brand pages.

For any team exploring AI Agents for frontend or content generation work, this pattern is highly replicable:

• Establish a single spec file: Consolidate your design system and brand guidelines into an Agent-friendly format, rather than relying on scattered prompts.
• Build an evaluation mechanism: Don't trust one-shot output — use automation to verify that results meet expectations.
• Close the feedback loop: Let production data feed back into the spec to drive continuous improvement.

Takeaway

Vercel's design.md practice looks like "just constraining AI with a Markdown file" on the surface, but it demonstrates how to apply engineering thinking to tame the unpredictability of AI generation. As AI Coding Agents become more widely adopted, ensuring output quality and brand consistency will become a key dividing line between "toy" and "production-grade" tools. This "spec–eval–feedback" loop — combining design system engineering, LLM evaluation infrastructure, and an RLHF-like iteration mechanism — may well be the foundation of the answer.