What is a DESIGN.md?什么是 DESIGN.md?

What a DESIGN.md isDESIGN.md 是什么

A DESIGN.md is a single Markdown file that encodes a complete design system in a structured, machine-readable form. It pairs machine-readable design tokens (typically a YAML block the machine reads first) with prose sections that lay out the look — colors, typography, spacing, shapes, components, motion — explicitly enough that an AI can apply them without guessing.DESIGN.md 是一个 Markdown 文件,以结构化、机器可读的形式编码一整套设计系统。它把机器可读的设计 token(通常是机器最先读的一段 YAML)与文字章节配在一起,把长相讲清楚——配色、字体、间距、形状、组件、动效——明确到 AI 无需猜测即可套用。

The name follows the convention of README.md: a plain-text file, versionable and portable, that any tool can open. The difference is the audience. A README explains a project to a human; a DESIGN.md explains a design to a machine — the AI that will dress your slides, your site, or your product in that style.名字沿用了 README.md 的约定:一个纯文本文件,可版本化、可移植,任何工具都能打开。区别在于受众。README 把项目讲给人听;DESIGN.md 把设计讲给机器听——就是那个将把你的幻灯片、网站或产品装进这套风格里的 AI。

Instead of prompting an agent with vague adjectives — "make it look modern and clean" — you drop a DESIGN.md into your project, and the agent applies your exact styles to everything it builds.你不再用模糊的形容词去 prompt——「做得现代一点、干净一点」——而是把一份 DESIGN.md 放进项目里,agent 把你的精确样式应用到它做的每一样东西上。

Where the format came from: Google Stitch格式从哪来:Google Stitch

DESIGN.md entered the mainstream through Google Stitch, Google Labs' AI design tool. Stitch uses a design.md file as the persistent memory of your design system: it stores the palette, fonts, and styling rules so that every screen the AI generates stays consistent instead of drifting with each prompt.DESIGN.md 走进主流,是通过 Google Stitch——Google Labs 的 AI 设计工具。Stitch 用一个 design.md 文件充当设计系统的持久记忆:它存下色板、字体和样式规则,让 AI 生成的每一屏都保持一致,而不是随每次 prompt 漂移。

In 2026 Google Labs released DESIGN.md as an open spec, so the same file works across tools and platforms rather than being locked to Stitch. Since then an ecosystem has grown around the format — coding agents like Claude Code, Cursor, and Codex read it from a project root, and libraries of ready-made DESIGN.md files have appeared, from community GitHub collections such as awesome-design-md to curated catalogs like Curio.2026 年,Google Labs 把 DESIGN.md 作为开放规范发布,同一个文件从此可以跨工具、跨平台使用,不再被 Stitch 锁定。此后一个围绕这个格式的生态长了起来——Claude Code、Cursor、Codex 这类编码 agent 会从项目根目录读它,现成 DESIGN.md 文件的库也出现了:从 awesome-design-md 这样的社区 GitHub 收藏,到 Curio 这样的精选目录。

That is why the format matters: it is becoming the common language between design systems and AI agents. One file, written once, understood by whatever AI tool you use next.这就是这个格式重要的原因:它正在变成设计系统与 AI agent 之间的通用语言。一个文件,写一次,你下一个用的 AI 工具都能懂。

What's inside a DESIGN.mdDESIGN.md 里面有什么

Metadata comes first: the style's name, a one-line essence, and flags like whether it is light or dark. This is the orientation a machine reads before anything else.元数据在最前:风格的名字、一句话的精髓,以及诸如「浅色还是深色」这样的标志位。这是机器在读其它一切之前先获取的定位。

Then the token sections, each stated as concrete values rather than adjectives: a color section (a named palette — background, ink, accents — as exact values like <hex>), a typography section (font families, weights, and a type scale in <px>/rem), a spacing section (a rhythm in <px>), and shape, shadow, and motion sections (radii, elevation, easing).接着是 token 章节,每一项都以具体的值给出,而非形容词:配色章节(一套命名色板——背景、墨色、强调色——以 <hex> 这样的精确值表示)、字体章节(字体家族、字重,以及以 <px>/rem 表示的字阶)、间距章节(以 <px> 表示的节奏),以及形状、阴影、动效章节(圆角、层级、缓动)。

Finally, applied guidance: component logic (how buttons, cards, and inputs should look in this style) and usage notes (where the style fits and where it does not). The combination is what lets an AI go from 'I know the rules' to 'I built the screen' — without inventing values.最后是应用指引:组件逻辑(在这套风格里按钮、卡片、输入框该长什么样)与用法说明(这套风格适合哪儿、不适合哪儿)。正是这套组合,让 AI 从「我知道规则」走到「我把这屏做出来了」——而无需自己编造数值。

Curio ships every style in its library as a complete file of this shape. The structure is open so anyone can see how a DESIGN.md is put together; the precise token values for each style are the paid product. The skeleton is public; the exact <hex> and <px> are what you unlock.Curio 库里的每种风格,都以这个形状的完整文件交付。结构是开放的,任何人都能看清一份 DESIGN.md 是怎么组装的;每种风格的精确 token 值,是付费产品。骨架公开;具体的 <hex> 与 <px>,才是你解锁的东西。

Why machine-readable beats a screenshot机器可读为什么胜过截图

A screenshot or a 'vibe' is lossy: the AI has to infer what mattered, and it infers differently every time — copying a color but missing the spacing logic, borrowing the type but not the grid. A DESIGN.md removes the guessing. The values are stated, so the AI applies them exactly, the same way on every screen.截图或「感觉」是有损的:AI 必须推断什么才重要,而且每次推断都不同——抄了颜色却漏了间距逻辑,借了字体却没要网格。DESIGN.md 去掉了猜测。数值是明写的,于是 AI 精确套用,每个屏幕都一样。

Because it is one deterministic file, it is also consistent and reusable. The same DESIGN.md governs slide one and slide forty, this week's landing page and next month's dashboard. That is the difference between a look you stumbled into once and a system you can rely on.因为它是一个确定性的文件,它也是一致且可复用的。同一份 DESIGN.md 既管第一张幻灯片,也管第四十张;既管这周的落地页,也管下月的仪表板。这就是「偶然撞到一次的长相」与「可以依赖的系统」之间的区别。

And because it is plain text, it fits the way software teams already work: it lives in the repo, travels through Git, and changes to the design system show up as reviewable diffs instead of mystery drift.又因为它是纯文本,它天然适配软件团队既有的工作方式:待在仓库里,随 Git 流转,设计系统的每次变更都是一条可 review 的 diff,而不是查无对证的漂移。

How an AI uses a DESIGN.mdAI 怎么使用 DESIGN.md

You hand the file to your AI in whichever way fits your tool: drop it in your project root for a coding agent to find, paste it into a chat, send a share link, or connect over MCP so the AI can pull it on demand. From there the model reads the tokens and applies them — generating components, slides, or pages that already match the style instead of drifting toward the average.你以适合自己工具的方式把文件交给 AI:放进项目根目录让编码 agent 自己找到、贴进聊天窗口、发一个分享链接,或通过 MCP 连接让 AI 按需拉取。从那以后,模型读取这些 token 并套用——生成的组件、幻灯片或页面一开始就匹配这套风格,而不是漂向平均值。

Because the format is plain Markdown, it is not locked to any one assistant. The same DESIGN.md works whether your AI lives in a chat window, a coding tool, or an agent pipeline — the spec travels with the work.因为格式就是普通 Markdown,它不被任何单一助手锁定。无论你的 AI 活在聊天窗口、编程工具还是 agent 流水线里,同一份 DESIGN.md 都能用——规范随工作一起走。

Should you write one or pick one?该自己写一份,还是直接挑一份?

Write your own DESIGN.md when the design system already exists and belongs to you — your brand, your product's look. Encoding it once means every AI tool you use applies it faithfully from then on.当设计系统已经存在且属于你——你的品牌、你产品的长相——就自己写一份 DESIGN.md。编码一次,此后你用的每个 AI 工具都会忠实套用它。

Pick a ready-made one when what you want is an established style — Bauhaus, Swiss International, a brand-grade contemporary look — and you would rather not reverse-engineer it yourself. That is what a DESIGN.md library is for: Curio ships hundreds of real design styles, each as a complete DESIGN.md your AI can apply in seconds over MCP, a share link, or a download.当你想要的是一种成熟风格——包豪斯、瑞士国际主义、某种品牌级的当代长相——又不想自己逆向工程,那就直接挑一份现成的。这正是 DESIGN.md 库存在的意义:Curio 以完整 DESIGN.md 交付数百种真实设计风格,你的 AI 通过 MCP、分享链接或下载,几秒钟就能套上。

FAQ常见问题

Further reading延伸阅读

• How to write a DESIGN.md: structure, best practices & pitfalls怎么写 DESIGN.md:结构、最佳实践与常见坑
• DESIGN.md example: what a complete file looks likeDESIGN.md 示例:一份完整文件长什么样
• Google Stitch's DESIGN.md, explainedGoogle Stitch 的 DESIGN.md,讲明白
• Curio vs DESIGN.md, awesome-design-md & Open DesignCurio vs DESIGN.md、awesome-design-md、Open Design