--- title: DESIGN.md vs. Design System MCP: Which Does What? description: Comparing DESIGN.md and design system MCP servers for feeding AI agents design context: DESIGN.md is a portable, model-agnostic Markdown file with token front... canonical: https://daily.dev/posts/design-md-vs-design-system-mcp-which-does-what--kgeeofyhy twitter:card: summary_large_image twitter:site: @dailydotdev og:type: website og:site_name: daily.dev og:title: DESIGN.md vs. Design System MCP: Which Does What? | daily.dev og:description: Comparing DESIGN.md and design system MCP servers for feeding AI agents design context: DESIGN.md is a portable, model-agnostic Markdown file with token front... og:url: https://daily.dev/posts/design-md-vs-design-system-mcp-which-does-what--kgeeofyhy og:image: https://api.daily.dev/og/posts/KGEEoFyhY.png og:image:alt: DESIGN.md vs. Design System MCP: Which Does What? og:image:width: 1200 og:image:height: 630 og:locale: en --- > ## Documentation Index > Fetch the complete documentation index at: https://daily.dev/llms.txt > Use this file to discover all available pages before exploring further. # DESIGN.md vs. Design System MCP: Which Does What? **[Headway](https://daily.dev/sources/headway)** · 8 min read · 53 upvotes · 4 comments ## Summary Comparing DESIGN.md and design system MCP servers for feeding AI agents design context: DESIGN.md is a portable, model-agnostic Markdown file with token front matter and prose, useful for anyone outside the coded component stack, while an MCP server gives agents precise access to a component library's actual props, variants, and changelog for agents working inside that stack. The recommended setup is to make DESIGN.md the source of truth and have the MCP read from it, reducing duplicate Figma-extraction tooling and keeping both outputs grounded in the same tokens. Practical guidance covers linting DESIGN.md in CI, starting with tokens before adding usage guidance, and routing agents between DESIGN.md, MCP, skill files, and AGENTS.md depending on the task. ## Full article daily.dev links to this article rather than hosting it. Read it at the original source: ## Questions this post answers ### What's the difference between a DESIGN.md file and a design system MCP server for AI agents? DESIGN.md is a portable Markdown file with YAML front matter holding design tokens and prose explaining visual rules, usable by any agent or model regardless of stack. A design system MCP server instead gives coding agents working in the same codebase precise, on-demand access to actual component APIs, like a React Button's variant, size, and isLoading props, plus changelog info. DESIGN.md reaches builders outside the component stack; the MCP serves developers inside it. _Teams weighing how to expose design context to agents can track emerging patterns like this one on daily.dev._ ### Should DESIGN.md or an MCP be the source of truth for design tokens when both are used? DESIGN.md should be the source of truth, with the MCP server reading its tokens and rules rather than maintaining a separate copy. This setup reduces custom Figma-extraction tooling, keeps tokens from drifting between what designers see and what the MCP serves, and ensures both technical and non-technical builders work from the same underlying decisions. _Engineers architecting agent-ready design systems can follow this kind of integration guidance on daily.dev._ ### Can DESIGN.md describe a coded component's props and API for an AI agent? No, DESIGN.md carries design tokens and visual rules well but cannot describe a component's actual API, such as its props or what changed in a recent release. Its components section only describes how a component should look, closer to rebuild instructions than a map of an existing UI kit, so agents working in the same stack still need an MCP for accurate component reuse. _Developers deciding how much component detail to expose to coding agents can follow this comparison on daily.dev._ ## Community discussion Top comments from developers on daily.dev. **@ristotoldsep** · 3 upvotes > A file for the rules, MCP for component details. That split actually makes sense. **@kartiknvj** · 2 upvotes > Making [DESIGN.md](http://DESIGN.md) the source of truth and having the MCP read from it is the detail most takes on this miss, since two independent sources drift the moment a component changes. In my own setup the CI lint on [DESIGN.md ](http://DESIGN.md)is what keeps that safe. When they do drift anyway, which one do you have the agent trust at request time? **@aidive** · 1 upvotes > On drift: a dead CLAUDE.md line pointing at a tsconfig alias that did not exist was read every session and followed by zero runs. Versioned facts belong in the MCP. **@ahmetozel** · 0 upvotes > Making [DESIGN.md](http://DESIGN.md) the shared source reduces duplication, but tokens and component availability evolve at different speeds. A token may be valid while the installed component package still lacks the variant described by the MCP response. > > I would have the component lookup return the package version it describes and compare that with the version in the project lockfile. Linting the Markdown catches malformed context; checking this compatibility catches perfectly valid context for the wrong release. A portable design rule can remain stable, while executable examples should be... ## Similar posts on daily.dev - [Atlassian’s DESIGN.md is here: what we learned testing portable design context in practice](https://daily.dev/posts/atlassian-s-design-md-is-here-what-we-learned-testing-portable-design-context-in-practice-nnf3qta24) · Atlassian · 2 upvotes · 1 comments - [The TL;DR on MCP: Why context matters and how to put it to work](https://daily.dev/posts/the-tl-dr-on-mcp-why-context-matters-and-how-to-put-it-to-work-e64pcueca) · Figma · 3 upvotes · 0 comments - [The case for running AI agents on Markdown files instead of MCP servers](https://daily.dev/posts/the-case-for-running-ai-agents-on-markdown-files-instead-of-mcp-servers-ljqa1dmns) · The New Stack · 2 upvotes · 0 comments - [How to structure Figma files for MCP and AI-powered code generation](https://daily.dev/posts/how-to-structure-figma-files-for-mcp-and-ai-powered-code-generation-qildzfuvv) · LogRocket · 1 upvotes · 0 comments --- Tags: [#webdev](https://daily.dev/tags/webdev), [#react](https://daily.dev/tags/react), [#ai-agents](https://daily.dev/tags/ai-agents), [#mcp](https://daily.dev/tags/mcp) [View this post on daily.dev](https://daily.dev/posts/design-md-vs-design-system-mcp-which-does-what--kgeeofyhy) ```json {"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]} {"@context":"https://schema.org","@type":"TechArticle","headline":"DESIGN.md vs. Design System MCP: Which Does What?","url":"https://daily.dev/posts/design-md-vs-design-system-mcp-which-does-what--kgeeofyhy","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/design-md-vs-design-system-mcp-which-does-what--kgeeofyhy"},"datePublished":"2026-10-01T15:59:45.559Z","dateModified":"2026-10-01T16:00:09.857Z","description":"Comparing DESIGN.md and design system MCP servers for feeding AI agents design context: DESIGN.md is a portable, model-agnostic Markdown file with token front...","image":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/e117fa33f97036cf4727e8ae51d63176?_a=AQAEuop","thumbnailUrl":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/e117fa33f97036cf4727e8ae51d63176?_a=AQAEuop","isAccessibleForFree":true,"articleSection":"Headway","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"Headway","logo":"https://media.daily.dev/image/upload/t_logo,f_auto/v1/logos/6db6367290f142ec95e820d83985679d","url":"https://daily.dev/sources/headway"},"commentCount":4,"discussionUrl":"https://daily.dev/posts/design-md-vs-design-system-mcp-which-does-what--kgeeofyhy","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":52},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":4}],"keywords":"webdev,react,ai-agents,mcp","timeRequired":"PT8M"} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"Headway","item":"https://daily.dev/sources/headway"},{"@type":"ListItem","position":3,"name":"DESIGN.md vs. Design System MCP: Which Does What?"}]} {"@context":"https://schema.org","@type":"WebPage","@id":"https://daily.dev/posts/design-md-vs-design-system-mcp-which-does-what--kgeeofyhy","comment":[{"@type":"Comment","text":"A file for the rules, MCP for component details. That split actually makes sense.","datePublished":"2026-10-02T11:41:23.167Z","url":"https://daily.dev/posts/KGEEoFyhY#c-wJXSOKHxY","author":{"@type":"Person","name":"Risto Tõldsep","url":"https://daily.dev/ristotoldsep","image":"https://lh3.googleusercontent.com/a/ACg8ocLDWc6mZn0JwNmXXw6WY0L_HJ6pegzRttooC5VgtXESHSj3MNYx=s96-c"},"interactionStatistic":{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":3}},{"@type":"Comment","text":"Making DESIGN.md the source of truth and having the MCP read from it is the detail most takes on this miss, since two independent sources drift the moment a component changes. In my own setup the CI lint on DESIGN.md is what keeps that safe. When they do drift anyway, which one do you have the agent trust at request time?","datePublished":"2026-10-01T18:56:35.451Z","url":"https://daily.dev/posts/KGEEoFyhY#c-EY6Fo34fk","author":{"@type":"Person","name":"kartik-nvjk","url":"https://daily.dev/kartiknvj","image":"https://media.daily.dev/image/upload/s--3gGgsVCw--/f_auto/v1781456774/avatars/avatar_TvTVeiMdkRCqWUDullFmy?_a=BAMAMiWQ0"},"interactionStatistic":{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":2}},{"@type":"Comment","text":"On drift: a dead CLAUDE.md line pointing at a tsconfig alias that did not exist was read every session and followed by zero runs. Versioned facts belong in the MCP.","datePublished":"2026-10-02T18:35:46.013Z","url":"https://daily.dev/posts/KGEEoFyhY#c-5i0KyLWi2","author":{"@type":"Person","name":"AI Dive","url":"https://daily.dev/aidive","image":"https://media.daily.dev/image/upload/s--CXOxN2Lp--/f_auto/v1787506402/avatars/avatar_ICUHYClOqsxUOW9ildHmf?_a=BAMAMicg0"},"interactionStatistic":{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":1}},{"@type":"Comment","text":"Making DESIGN.md the shared source reduces duplication, but tokens and component availability evolve at different speeds. A token may be valid while the installed component package still lacks the variant described by the MCP response.\nI would have the component lookup return the package version it describes and compare that with the version in the project lockfile. Linting the Markdown catches malformed context; checking this compatibility catches perfectly valid context for the wrong release. A portable design rule can remain stable, while executable examples should be tied to the actual component contract the agent is editing against.","datePublished":"2026-10-04T17:01:45.581Z","url":"https://daily.dev/posts/KGEEoFyhY#c-73Mw1Nuun","author":{"@type":"Person","name":"Ahmet Özel","url":"https://daily.dev/ahmetozel","image":"https://avatars.githubusercontent.com/u/70992231?v=4"}}]} {"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/design-md-vs-design-system-mcp-which-does-what--kgeeofyhy#faq","mainEntity":[{"@type":"Question","name":"What's the difference between a DESIGN.md file and a design system MCP server for AI agents?","acceptedAnswer":{"@type":"Answer","text":"DESIGN.md is a portable Markdown file with YAML front matter holding design tokens and prose explaining visual rules, usable by any agent or model regardless of stack. A design system MCP server instead gives coding agents working in the same codebase precise, on-demand access to actual component APIs, like a React Button's variant, size, and isLoading props, plus changelog info. DESIGN.md reaches builders outside the component stack; the MCP serves developers inside it. Teams weighing how to expose design context to agents can track emerging patterns like this one on daily.dev."}},{"@type":"Question","name":"Should DESIGN.md or an MCP be the source of truth for design tokens when both are used?","acceptedAnswer":{"@type":"Answer","text":"DESIGN.md should be the source of truth, with the MCP server reading its tokens and rules rather than maintaining a separate copy. This setup reduces custom Figma-extraction tooling, keeps tokens from drifting between what designers see and what the MCP serves, and ensures both technical and non-technical builders work from the same underlying decisions. Engineers architecting agent-ready design systems can follow this kind of integration guidance on daily.dev."}},{"@type":"Question","name":"Can DESIGN.md describe a coded component's props and API for an AI agent?","acceptedAnswer":{"@type":"Answer","text":"No, DESIGN.md carries design tokens and visual rules well but cannot describe a component's actual API, such as its props or what changed in a recent release. Its components section only describes how a component should look, closer to rebuild instructions than a map of an existing UI kit, so agents working in the same stack still need an MCP for accurate component reuse. Developers deciding how much component detail to expose to coding agents can follow this comparison on daily.dev."}}]} ```