A single markdown file used 92% more tokens than an MCP server to produce the same screen. That's not a consultant's hunch: Atlassian measured it, on its own design system. And what the measurement really tells you is more interesting than the number itself.
DESIGN.md, the promise of a single file
The format is called DESIGN.md. It's a markdown file created by Google that sums up your brand and your components in a single document you paste into your prompt. On paper, it's appealing: one file, portable, and the AI stops generating generic mush.
What Atlassian measured
Atlassian compared this single file with its MCP server and its skills, on a simple task in a production codebase. The single file used 92% more tokens, it was slower, and it showed 2.7 times more variance in consumption from one run to the next. It also tended to recreate components instead of reusing the ones that already exist, which means piling up debt.
The number I find most telling is somewhere else, though: the MCP gives the agent access to about 80% of the design system, the single file to 30%. To fit everything into one document, Atlassian had to cut a large part of the guidelines for its 50 components.
The real variable: on-demand loading
The reason is simple. A markdown file loads everything, all the time, even what the AI doesn't need. An MCP server fetches the right component at the right moment, on demand.
One clarification matters here, because the shortcut is tempting: Atlassian's skills are markdown files too, and they come very close to the MCP on the same tests. What makes the difference is on-demand loading, whatever tech carries it.
What it changes in practice
This is what I set up for my clients: the design system split up and queryable, the AI picking the relevant component when it needs it, instead of one big frozen block you hope is complete enough.
DESIGN.md is still handy for quick prototyping, client theming, or an environment without MCP. Atlassian even publishes its own. For a product in production, it's not enough.
In all honesty: Atlassian points out that these results aren't conclusive in the scientific sense, and that other models or other design systems will give other numbers. The order of magnitude, though, matches what I see on client engagements.
So the useful question isn't about the file you give the AI. It's about how you make your design system queryable. A file alone doesn't do that.
If you want to boost the productivity of your product and design teams with common, shared tools, get in touch. That's what I build.