DESIGN.md vs MCP Servers

Why does this debate exist?#

Since DESIGN.md arrived in spring 2026, "give the agent your design system" has had one obvious, file-shaped answer: put a DESIGN.md in the repo. Then Atlassian ran the experiment that everyone had been hand-waving about.

In Atlassian's published test, they compared two ways of feeding their design system to coding agents: a DESIGN.md file capturing tokens and usage rules, and their own MCP server, together with skills, exposing the design system as live, queryable context. Their headline numbers:

• The MCP server and skills covered roughly 80% of Atlassian's design system.
• The DESIGN.md file managed only about 30% coverage of the same system, and needed roughly 92% more tokens than the MCP approach when used as the sole source (7.21M vs 3.75M average tokens).
• And yet: for one-shot prototyping, DESIGN.md produced the best results, taking generated UI, in Atlassian's words, "from generic 'slop' to something recognizably Atlassian."

That last point is why this is a genuinely interesting comparison rather than a knockout. The approach that lost on coverage and token efficiency won on the thing many teams actually do with agents all day: getting a believable, on-brand first draft in a single prompt.

To keep the comparison fair, both sides deserve a precise description. DESIGN.md is an open-source file format from Google that stores a complete design system in a single Markdown file: machine-readable design tokens (colors, typography, spacing, components) in YAML frontmatter, plus human-readable rationale in Markdown prose. AI coding agents like Claude Code, Cursor, and Copilot read it to generate UI that consistently matches your brand. (New to the format? Start with what DESIGN.md is.)

MCP (the Model Context Protocol) is an open standard introduced by Anthropic that lets AI agents connect to external servers for tools and data. A design-system MCP server exposes tokens, components, and guidelines as resources the agent queries on demand: instead of swallowing the whole design system up front, the agent asks for exactly what the current task needs, the current primary color, the props of the card component, and gets fresh answers straight from the source of truth. It is a serious, production-minded architecture, not a workaround.

How do DESIGN.md and MCP compare?#

Read the table honestly and the pattern is clear: this is a static-artifact vs. live-service trade-off, the same shape as "config file vs. API." Neither side dominates all criteria, which is why the right question is not "which is better" but "which failure can you afford."

A note on the "coverage" numbers: they describe how much of Atlassian's production design system (an enterprise-scale one) each approach exposed to the agent. A startup whose entire system is 30 tokens and a dozen components can plausibly reach full coverage in one DESIGN.md; a mature enterprise system with hundreds of components cannot. Scale is the hidden variable in every row of the table above.

When does DESIGN.md win?#

• One-shot prototyping. This is the empirically strongest case: it is the one result where Atlassian's test favored the file. A compact bundle of tokens plus prose rationale gives the model the intent it needs for a coherent first draft. Clearly described intent shapes a generated design more than exact values do, and DESIGN.md's prose layer is built to carry exactly that intent.
• Cross-tool portability. The same file works in Claude Code, Cursor, and Copilot (via a pointer in each tool's config; none of them read it automatically) and reportedly natively in Google's Stitch. An MCP server helps only clients that speak MCP and are configured for it.
• Small teams and zero infrastructure. A file needs no deployment, no auth, no uptime. npx @google/design.md lint DESIGN.md is the entire toolchain.
• Theming and variants. Handing an agent a second DESIGN.md is a complete theme swap; the CLI's export even emits Tailwind v4 @theme blocks or W3C DTCG JSON for the code side.
• Review and versioning. Design decisions ride through pull requests like any other change, and design.md diff before.md after.md flags token-level regressions with a non-zero exit code: CI-friendly governance a server does not give you for free.

Atlassian's own stated conclusion lines up with this list: they see DESIGN.md's best fit as high-level art direction, quick prototyping in unfamiliar environments, design-tool interoperability, and customer theming, with one caveat worth repeating in full: "if your agent supports MCP or skills, those give better results at reduced cost."

When does an MCP server win?#

• Production work on a large design system. 30% coverage is fine for a prototype and unacceptable for shipping components. If agents need the full component API surface, live queries beat any hand-curated summary.
• Token budgets at scale. A median-sized DESIGN.md costs ~7,050 tokens per task, every task, and Atlassian's test found that using it as the sole source needed roughly 92% more tokens overall than querying the MCP server. Across hundreds of agent runs a day, that gap is real money and real context headroom.
• Live tokens, one source of truth. When the design system changes weekly, every DESIGN.md copy in every repo is a staleness liability. A server is never out of date.
• Governance and access control. A server can log queries, enforce deprecations ("that component is retired; use this one"), and gate internal-only patterns, none of which a static file can do.

Atlassian's criticism of the file-based approach deserves to be stated plainly, not softened: for their production-scale system, DESIGN.md captured well under a third of what agents needed, at almost double the token cost. For a company with a mature design platform team, the MCP server was the better production tool. Nothing in the DESIGN.md spec (still version "alpha", and explicitly under active development) currently contradicts that.

The hybrid pattern: portable design context plus a live server#

The emerging answer is not either/or. It helps to name what the file actually is:

Portable design context is design-system knowledge packaged to travel with the request rather than live on a server: a self-contained, machine-readable artifact, typically a DESIGN.md file, that any AI agent or tool can consume without extra infrastructure. Because it is plain text in the repository, it is versionable, diffable, and works across tools and offline.

An MCP server optimizes for depth and freshness; portable design context optimizes for reach. A workable hybrid looks like this:

1. DESIGN.md as the entry point and fallback. Every repo carries the file; any agent, any tool, any offline session gets at least the core identity: the thing that took Atlassian's prototypes from generic 'slop' to something recognizably Atlassian.
2. MCP for production surfaces. Agents working on shipping product query the server for the full, current component catalog.
3. One generation pipeline. Derive the DESIGN.md from the same source of truth the server reads, so the file is a compressed snapshot, not a fork. Check it in CI with design.md lint and design.md diff.
4. Route by task. Prototype, marketing page, email template → file. Product component work → server. The instructions file (AGENTS.md or CLAUDE.md) encodes the routing; see DESIGN.md vs AGENTS.md for how those files divide the labor. In practice the routing is a few lines:

## Design context
- Prototypes, marketing pages, emails: read DESIGN.md and
  use only tokens defined there.
- Product UI in packages/app: query the design-system MCP
  server for current tokens and component specs.
- If the MCP server is unavailable, fall back to DESIGN.md
  and flag the output for design review.

Both approaches are ways to build the same thing: a design system agents can actually use. That broader frame, including where Storybook docs and custom rules files fit, is covered in our guide to agentic design systems.

What does this mean for the spec's future?#

DESIGN.md is young and moving fast: the spec was open-sourced on April 21, 2026, the CLI added Tailwind export formats in 0.2.0 (May 26), and 0.3.0 (June 15) shipped a ninth lint rule. The format's version field still says alpha, and Google describes spec and CLI as under active development.

Our read, clearly labeled as interpretation, not fact: coverage vs. portability may turn out to be a serving detail rather than a format war. Nothing prevents an MCP server from serving sections of a DESIGN.md on demand, or a build step from compressing a server's catalog into a DESIGN.md snapshot. The token system is already designed for interchange: it is inspired by the W3C Design Token Format, and the CLI exports DTCG JSON today. If convergence happens, Atlassian's numbers will read less like a verdict against the file and more like the argument that forced the two approaches to meet in the middle. Treat any specific roadmap claim beyond this as speculation.

Next step: this comparison is one slice of a bigger shift: design systems restructured for agents as first-class readers. Read the full guide to agentic design systems for the architecture view, or the DESIGN.md spec guide if you're ready to write and lint your own file.