The Brief and the Inventory: What I Learned Researching DESIGN.md and Design-System MCP Servers

Here is the whole argument up front. A DESIGN.md is a brief: one Markdown file with design tokens in YAML on top and plain-language rationale below, so an agent learns what a color is for and not only its hex value S1S2. It answers "why", and it is static. It cannot answer what an agent needs halfway through a screen: which Button exists in this codebase today, which props it really takes, and whether the thing it just built passes the tests. Those are live facts, and in 2026 they arrive over MCP, from Figma, Storybook or a component registry S3S4S5. Figma's own docs say its MCP server does not understand your design system by default S6. So the setup that works is both: a brief the agent reads and an inventory it can query. For freelancers, that pair is also the deliverable that outlives the contract, and whether your agent can use half of it depends on the seat the client gives you.

I started this thinking DESIGN.md was the whole story, a better handoff file that would retire the Figma link and the PDF style guide. Three things changed my mind. A vendor-run eval found that with the design system out of an agent's reach, 73% of style decisions bypassed tokens and none of 60 runs flagged a problem S7. Mature systems already ship both halves: Cognite's Aura pairs a DESIGN.md with an MCP server for its docs S8, and Atlassian publishes its MCP server while keeping its design-md skill internal S9. And when I ran Google's own linter over 74 community DESIGN.md files, 13 had no tokens it could read.

FIG. 01 · The brief and the inventory · the file carries intent, the servers carry what exists right now S2S6S4

What is actually inside a DESIGN.md?

Google's Stitch team open-sourced the draft spec on April 21, 2026, so any tool could read the same design rules S1. YAML front matter holds the tokens in five groups, colors, typography, rounded, spacing and components, and a component can reference another token, such as {colors.primary} S2. The Markdown body holds up to eight ## sections in a fixed order, from Overview to Do's and Don'ts. Tokens give exact values; prose says why they exist and when to use them S2.

The tooling surprised me. The @google/design.md package ships a linter with nine rules: one error, broken-ref, for a reference that resolves to nothing; six warnings, including a WCAG AA contrast-ratio check at 4.5:1; and two info rules S2. It also diffs versions for token regressions and exports to Tailwind or W3C DTCG JSON S2, and DTCG reached its first stable version, 2025.10, last October S10. The format itself is still alpha, at release 0.3.0 from June 15, 2026 S2.

FIG. 02 · Two layers, eight sections, nine lint rules · only a broken token reference is an error S2

How well do the community files hold up?

Adoption ran ahead of the spec. On October 10 the official repo had 26.3k stars, and VoltAgent's collection of brand files had 101k, up from the 71k Mejba Ahmed counted in early May S2S11S12. Most people meet the format through that collection, so I cloned it at its October 5 commit, 74 files, and ran @google/design.md 0.3.0 against every one.

None produced an error, which is narrower than it sounds. In 13 files the linter found no machine-readable tokens: 10 had no YAML and 3 had YAML it could not parse, so to an agent they are prose. 36 files had at least one component text and background pair under 4.5:1, 89 findings in all, including the primary button in six. I excluded another 89 findings on fully transparent backgrounds, which the linter scores against black. 61 files defined tokens no component used.

Two caveats. These files are extracted from public websites, and the repo disclaims ownership of any site's visual identity S11. And WCAG accepts 3:1 for large or bold text, so some of those buttons pass on the live site. The finding is about the file: an agent that copies one inherits its contrast misses unless something checks.

The number I got wrong first was section order. The collection uses nine sections of its own, such as an Agent Prompt Guide S11, so I expected section-order warnings. There were none, because the spec preserves headings it does not know rather than rejecting them S2.

FIG. 03 · Google's linter against 74 community files · zero errors, 13 with no readable tokens, 36 with color pairs under 4.5:1 · my run, October 10, 2026 S2S11

Why isn't the file enough on its own?

Because a file is read once and drifts quietly. TJ Pitre, who maintains the open source Figma Console MCP, puts it simply: an agent does not know your design system exists unless someone puts it in its context, and left alone it generates a component rather than finding the governed one S13. A DESIGN.md puts the rules in context, not the inventory. It cannot tell the agent that Card gained a variant on Tuesday.

Knapsack's eval is the sharpest evidence I found, with caveats up front: Knapsack sells design system tooling, and the test covers 60 runs against one system, Meta's open source Astryx S7. Out of reach, 73% of style decisions bypassed tokens, one in three component choices built something new, and 0 of 60 runs reported a problem S7. In reach, 60 of 60 runs used the system and decisions the compiler could check rose from 49% to 78% S7. The post does not say whether "in reach" meant a file, an MCP server or both, so I read it as evidence for live context in general.

FIG. 04 · Out of reach, agents improvise; in reach, they use the system · vendor-run, 60 runs, one design system S7

Practitioners report the same split. Mejba Ahmed shipped four products on DESIGN.md; a 412-line file took him about three hours and then produced a landing page in 40 minutes, and his warning is about forks, where a file copied from a sibling project builds the other brand's UI S12. He also writes that Claude Design launched with deep DESIGN.md support. I could not confirm it: Anthropic's announcement says Claude Design builds a design system by reading your codebase and design files, and never mentions DESIGN.md S14. I treat that claim as secondhand.

What does MCP add that the file can't?

Live answers to narrow questions. Figma's server lists 18 read tools and 12 write tools, not counting its Weave tools S3. search_design_system finds components and variables across libraries, get_variable_defs returns the tokens a selection uses, and with Code Connect the response carries your real component's import and usage snippet instead of generic React and Tailwind S3S15. Since March 24, 2026, use_figma also writes native frames, components and variables back to the canvas S16S17.

Storybook's addon serves MCP from the dev server at /mcp: docs-list and docs-show for documented components and props, and test-run for interaction and accessibility tests on what the agent built S4. Its suggested AGENTS.md rule is the best one-line case for MCP I read: never hallucinate component properties, check them through the tools first S4. The shadcn server does the same for component registries, including private ones S5.

The protocol grew up this year too. The July 28, 2026 revision made MCP stateless, so any request can land on any server instance, and the maintainers report close to half a billion SDK downloads a month S18. Figma's VP of Engineering, Josh Clemm, is quoted in that release saying more builders use Figma's MCP server and the stateless core lets it scale with them S18.

FIG. 05 · Read-only to read-write to stateless in just over a year · the pieces this post depends on S16S10S18S14S1S2

Figma is honest about the limit. Its docs say the server does not generate final code, does not understand your design system by default, and does not fix problems for you S6. That is the gap the brief fills. The file supplies intent, the server supplies inventory, and neither does the other's job.

What does the client actually see?

Mostly the output. On Upwork's August earnings call, CEO Hayden Brown said clients increasingly assume AI will be used without saying so: nearly half of freelancers in a company survey said their latest project involved AI, while 16% of job posts mentioned it S19. Upwork also sees clients hiring people to finish or fix projects started with AI, including turning AI-generated code into production websites S19.

What changes is what the client keeps. The old handoff was a Figma link and a style guide a person had to read. The 2026 handoff is a linted DESIGN.md in their repo, plus endpoints their own agents can call after you leave: a Figma library with Code Connect mappings, a published Storybook MCP, a component registry S2S15S4S5. The file is portable and free. The endpoints are only as good as the seats and upkeep behind them.

FIG. 06 · What the client keeps after you leave · a file any agent can read, and endpoints that need seats and upkeep S2S15S4S5

Designers already work this way. In UX Tools' independent survey of 1,478 designers this spring, Claude was the second most-used weekly tool at 50.8%, behind Figma at 82.6%, and design systems and tokens ranked third among next-year investments at 40.2% S20. Among the 17.9% who work independently, 36.2% said AI is now central to their workflow, against 28.6% at agencies S20.

Why does the client's seat decide what your agent can do?

This is the part I would put in a statement of work. View and Collab seats get up to 20 Figma MCP tool calls a month on every plan. Dev and Full seats get 200 a day on Professional and Organization and 600 a day on Enterprise S21. Writing is narrower: the developer docs say agents need a Full seat to write to Figma files, and the help center adds that Dev seats can write only in drafts S22S23. Only clients listed in Figma's MCP catalog can connect at all S21.

FIG. 07 · The client's seat decides what your agent can do · 20 calls a month on a View seat, and writing needs a Full seat S21S22S23

A freelancer on a client's View seat has 20 calls for the month, which one agent session can spend. Figma also says writing will become a usage-based paid feature after the free beta S23S17. And a catalog listing is not proof of working support: in April, a Windsurf user on a Professional Full seat reported that read tools loaded but use_figma never appeared S24. Ask for a Dev or Full seat before the first sprint, and test the exact editor you will use.

How would I wire one project?

Three pieces: the brief, a routing rule, and a lint gate. I ran the DESIGN.md below through the 0.3.0 linter and got zero errors and zero warnings. Change one letter in the {colors.accent} reference and it becomes a broken-ref error with exit code 1, which is what makes it usable as a CI gate S2.

---
version: alpha
name: Client Brand
colors:
  primary: "#1A1C1E"
  on-primary: "#FFFFFF"
  accent: "#B8422E"
  surface: "#F7F5F2"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 1rem
  label-caps:
    fontFamily: Inter
    fontSize: 0.75rem
rounded:
  sm: 4px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.accent}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.sm}"
    padding: 12px
  page:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.primary}"
---
 
## Overview
 
Quiet and editorial. Dense tables, generous margins. The accent is reserved
for the single most important action on a screen.
 
## Colors
 
- **Primary (#1A1C1E):** body text and headings.
- **Accent (#B8422E):** primary buttons only. Never links or decoration.
 
## Do's and Don'ts
 
- Never hardcode a hex value in a component; use a token.
- Never invent a component prop. Look it up first.

The inventory goes in .mcp.json for Claude Code: Figma's remote server and a local Storybook. I have not run this exact pairing end to end, so treat it as a starting point S3S4.

{
  "mcpServers": {
    "figma": { "type": "http", "url": "https://mcp.figma.com/mcp" },
    "storybook": { "type": "http", "url": "http://localhost:6006/mcp" }
  }
}

The routing rule in AGENTS.md tells the agent which source answers which question. The second line is adapted from Storybook's own suggestion S4.

## UI work
 
- Read DESIGN.md before generating any UI. It is the source of truth for tokens and intent.
- Before using a component or a prop, look it up with docs-list and docs-show. Never guess a prop.
- For a Figma link, call get_design_context and reuse components that come back through Code Connect.
- After building, run test-run on the new stories and fix what fails before reporting done.

The lint gate is one script. The designmd alias is the README's own suggestion for package.json, because the .md in the main binary name confuses Windows S2.

{
  "scripts": {
    "design:lint": "designmd lint DESIGN.md"
  }
}

What does the side-by-side look like?

Which one should you reach for?

DESIGN.md alone is enough if:

• The project is small and has no component library yet S12
• The client has no Figma seat to give you and you need something portable and free S2S21
• You can gate it in CI so a broken token reference fails the build S2

Add the Figma MCP server if:

• The source of truth is a Figma library with variables and components S3
• The client can give you a Dev or Full seat, since a View seat gets 20 calls a month S21
• Someone will keep Code Connect mappings current as component APIs change S15

Add Storybook or a registry server if:

• The components already exist in code and agents keep inventing props S4
• You want the agent to run interaction and accessibility tests before it says done S4S7
• The team ships a private component registry S5

If you are the freelancer, put these in the contract:

• Which plan and seat you will work on, and who pays once agent writes stop being free S21S23
• A linted DESIGN.md written for the client's brand, not forked from a public file S11S12
• Who keeps the MCP endpoints running after handoff S4S15

What would I do differently next time?

1. Run the tool before writing about it. My guess about section-order warnings was wrong, and the 13 community files with no readable tokens did not come up in anything I read.
2. Read the vendor's "what it does not do" page first. Figma's three-line list framed this post better than its launch blog did.
3. Keep format support apart from product claims. Several write-ups say Claude Design reads DESIGN.md; Anthropic's announcement does not. A support claim needs the tool's own docs.

Sources

1. S1Google, Cassia Xu, "Stitch's DESIGN.md format is now open-source so you can use it across platforms," April 21, 2026, blog.google
2. S2Google Labs, "google-labs-code/design.md" README and release 0.3.0 (June 15, 2026), accessed October 10, 2026, github.com
3. S3Figma, "Tools and prompts," Figma MCP server developer docs, accessed October 10, 2026, developers.figma.com
4. S4Storybook, "MCP server," Storybook 10.6 docs, accessed October 10, 2026, storybook.js.org
5. S5shadcn/ui, "MCP Server," accessed October 10, 2026, ui.shadcn.com
6. S6Figma, "What the MCP sends vs. what the agent does," Figma MCP server developer docs, accessed October 10, 2026, developers.figma.com
7. S7Knapsack, "Your AI Builder Has Changed, And Your Design System Needs to Know," August 19, 2026, knapsack.cloud
8. S8Cognite, "About Aura," Aura design system docs, accessed October 10, 2026, docs.cognite.com
9. S9Atlassian Design, "Develop: With AI," accessed October 10, 2026, atlassian.design
10. S10Design Tokens Community Group, "First stable version 2025.10 now available," designtokens.org home page, accessed October 10, 2026, designtokens.org
11. S11VoltAgent, "awesome-design-md," commit 13be5c0 of October 5, 2026, accessed October 10, 2026, github.com
12. S12Mejba Ahmed, "DESIGN.md: The AI Design Framework Hiding In Plain Sight," May 5, 2026, mejba.me
13. S13TJ Pitre, Southleft, "The Design System Was Fine Until the Agents Moved In," August 17, 2026, southleft.substack.com
14. S14Anthropic, "Introducing Claude Design by Anthropic Labs," April 17, 2026, anthropic.com
15. S15Figma, "Code Connect integration," Figma MCP server developer docs, accessed October 10, 2026, developers.figma.com
16. S16Vannarot Roeung, Creative AI News, "Figma Opens Canvas to AI Design Agents," March 24, 2026, creativeainews.com
17. S17Figma, Matt Colyer, "Agents, meet the Figma canvas," March 2026, figma.com
18. S18Model Context Protocol Blog, David Soria Parra and Den Delimarsky, "The 2026-07-28 Specification," July 28, 2026, blog.modelcontextprotocol.io
19. S19PYMNTS, "Upwork Navigates Cross-Currents as AI Reshapes Freelance Demand," August 10, 2026, pymnts.com
20. S20UX Tools, Tommy Geoco, "State of Prototyping: Spring 2026," survey run March 14 to April 6, 2026, uxtools.co
21. S21Figma, "Rate limits & access," Figma MCP server developer docs, accessed October 10, 2026, developers.figma.com
22. S22Figma, "Write to canvas," Figma MCP server developer docs, accessed October 10, 2026, developers.figma.com
23. S23Figma Help Center, Figma MCP server help article 39216419318551, accessed October 10, 2026, help.figma.com
24. S24Figma Forum, "Figma MCP for Windsurf Says Read and Write Access. However, Write to Canvas is not working," April 2, 2026, forum.figma.com

Written by

Syed Moinuddin

Full Stack Engineer.

Notes on AI tooling, agentic systems, and building things that survive contact with production.