How to write a DESIGN.md怎么写 DESIGN.md
A DESIGN.md only works if the machine reading it never has to guess. That is the whole craft of writing one: put orientation before detail, state values instead of adjectives, and cover the components the agent will actually build. Here is the structure that works, and the mistakes that quietly break it.DESIGN.md 有效的前提只有一个:读它的机器永远不用猜。写好它的全部功夫就在这里——先定位后细节,写数值不写形容词,把 agent 真会去搭的组件讲到。下面是行之有效的结构,和那些悄悄毁掉它的错误。
Start with orientation, not detail先写定位,别先堆细节
The first thing in the file should tell the machine what it is looking at: the style's name, a one-line essence — the sentence you would use to describe the look to someone who has never seen it — and the flags that change everything downstream, like whether the style is light or dark.文件的开头应该告诉机器它在看什么:风格的名字、一句话的精髓——你会用哪句话向没见过这个风格的人描述它——以及会改变后面一切的标志位,比如这套风格是浅色还是深色。
Most specs put this in a small structured block at the top (YAML frontmatter is the common convention, and the one Google's open DESIGN.md spec uses). An agent reads that block first and interprets every later section through it. A file that opens with fifty color values and no orientation makes the model reconstruct the intent — which is exactly the guessing you are trying to eliminate.多数规范把这些放在文件顶部的一小段结构化块里(YAML frontmatter 是通行约定,Google 的开放 DESIGN.md 规范用的也是它)。agent 先读这一块,再用它去解读后面的每个章节。一个开头就砸下五十个色值、却没有定位的文件,会逼模型自己重建意图——这恰恰是你想消灭的那种猜测。
State values, not adjectives写数值,不写形容词
"Warm, minimal, editorial" means something different to every model on every run. "Background <hex>, ink <hex>, one accent <hex>, body type at <px> with a 1.5 line height, spacing on an <px> rhythm" means the same thing every time. Tokens are the contract; adjectives are decoration.「温暖、极简、杂志感」对每个模型、每次运行的含义都不一样。「背景 <hex>,墨色 <hex>,一个强调色 <hex>,正文 <px>、行高 1.5,间距走 <px> 的节奏」每次含义都相同。token 是合同;形容词是装饰。
Name your tokens by role, not by appearance: background, ink, accent, line — not 'light gray' or 'blue'. Role names survive theme changes and tell the agent where a value belongs, not just what it is.token 按角色命名,不按外观命名:background、ink、accent、line——而不是「浅灰」或「蓝色」。角色名扛得住换主题,而且告诉 agent 这个值属于哪儿,而不只是它是什么。
Keep prose in the file, but give it a job: explain why the values are what they are and how they combine. 'The accent is reserved for one action per screen' is prose an agent can obey. 'The palette feels calm' is not.文件里可以有文字,但要给文字派活:解释这些值为什么是这样、怎么组合。「强调色每屏只留给一个动作」是 agent 能执行的文字;「这套色板感觉很平静」不是。
Cover the components the agent will build把 agent 真会搭的组件讲到
Tokens alone underdetermine a UI. Two styles can share a palette and still look nothing alike, because the difference lives in component logic: are buttons filled or outlined, sharp or rounded? Do cards float on shadows or sit inside hairline borders? Is emphasis done with weight, size, or color?只有 token 是撑不起一套 UI 的。两种风格可以共享一套色板,长得却完全不同,差别就在组件逻辑里:按钮是实心还是描边、直角还是圆角?卡片浮在阴影上,还是坐在发丝线边框里?强调靠字重、字号,还是颜色?
Write these as short declarative rules for the handful of components that appear everywhere — buttons, cards, inputs, navigation. Then add usage bounds: where the style fits and where it does not. An agent that knows a style is built for editorial pages will not force it onto a dense dashboard.把这些写成简短的陈述式规则,覆盖那几个到处出现的组件——按钮、卡片、输入框、导航。再加上适用边界:这套风格适合哪儿、不适合哪儿。知道某风格是为杂志式页面而生的 agent,就不会把它硬塞进一个高密度仪表板。
The mistakes that quietly break a spec悄悄毁掉规范的几个错误
Adjectives without values. The most common failure: a beautifully written mood description with no numbers. The agent nods along and then invents its own palette.有形容词没数值。最常见的失败:一段写得漂亮的氛围描述,一个数字都没有。agent 频频点头,然后自己编一套色板。
Dumping the whole brand book. A DESIGN.md is a working spec, not an archive. If the file takes longer to read than the screen takes to build, the agent will skim — and skimming is guessing with confidence. Keep it to what changes the output.把整本品牌手册倒进去。DESIGN.md 是干活用的规范,不是档案馆。如果读文件比搭页面还慢,agent 就会跳读——跳读就是带着自信在猜。只留下会改变产出的内容。
No usage bounds. A spec that never says where the style should not go gets applied everywhere, badly.没有适用边界。从不说明这套风格不该去哪儿的规范,会被套到所有地方,而且套得很糟。
Letting it rot. The file is plain text in your repo; treat it like code. When the design changes, the DESIGN.md changes in the same commit — otherwise the agent faithfully applies last quarter's design.任它腐烂。这个文件是仓库里的纯文本,要像对待代码一样对待它。设计变了,DESIGN.md 就该在同一个 commit 里跟着变——否则 agent 会忠实地应用上个季度的设计。
Inconsistent internal references. If the type section says one scale and a component example implies another, the agent has to pick one — and it will not tell you which it picked.内部自相矛盾。字体章节说一套字阶、组件示例暗示另一套,agent 只能二选一——而且它不会告诉你它选了哪个。
Or skip the writing: pick a ready-made one或者跳过手写:挑一份现成的
Writing a DESIGN.md is worth it for a design system you own. But if what you want is an established style — Bauhaus, Swiss International, a contemporary brand-grade look — writing the file means reverse-engineering a whole movement's rules yourself, and getting them subtly wrong is the default outcome.为一套你自己拥有的设计系统写 DESIGN.md,值得。但如果你想要的是一种成熟风格——包豪斯、瑞士国际主义、某种品牌级的当代长相——手写这份文件意味着你要亲自逆向工程整个流派的规则,而「微妙地写错」是默认结局。
That is the case for a library. Curio ships hundreds of real design styles, each already encoded as a complete DESIGN.md — researched, structured, and ready for your AI to apply over MCP, a share link, or a download. Pick the style; the file is already written.这就是库存在的理由。Curio 以完整 DESIGN.md 交付数百种真实设计风格——已经调研、已经结构化,你的 AI 通过 MCP、分享链接或下载即可套用。挑风格就行;文件已经写好了。
FAQ常见问题
How long should a DESIGN.md be?DESIGN.md 该写多长?
As short as it can be while still deciding every visual question the agent will face. In practice that is usually a page or two: one orientation block, the core token sections, component rules for the recurring elements, and usage bounds. If a section would not change what the AI builds, cut it.在能回答 agent 会遇到的每个视觉问题的前提下,越短越好。实践中通常是一两页:一段定位、核心 token 章节、高频组件的规则、适用边界。如果某个章节不会改变 AI 的产出,删掉它。
Where should the file live in my project?文件该放在项目的哪里?
The project root, next to README.md — that is where coding agents look first, and it follows the convention the name implies. Some tools also let you point at the file explicitly or fetch it over MCP, but root placement works everywhere.项目根目录,挨着 README.md——编码 agent 最先看那里,也符合这个名字本身暗示的约定。有些工具也支持显式指定路径或通过 MCP 拉取,但放根目录在哪儿都好使。
Should it be one file or several?写成一个文件还是拆成几个?
One. The point of the format is that an agent reads the whole design system in a single pass. The moment the spec is spread across files, you are relying on the agent to find and reconcile them — reintroducing the guessing the format exists to remove.一个。这个格式的意义就在于 agent 一次读完整套设计系统。规范一旦散落多个文件,你就在指望 agent 自己找齐并调和它们——这又把格式本来要消灭的猜测请了回来。
Do I need YAML frontmatter?必须写 YAML frontmatter 吗?
It is the convention Google's open spec uses and the easiest block for a machine to parse, so it is a good default. But the deeper rule is orientation-before-detail: whatever the syntax, the file should open with what the style is before it lists values.它是 Google 开放规范采用的约定,也是机器最好解析的一块,所以是个好默认。但更本质的规则是「先定位后细节」:无论语法如何,文件都应该先说这套风格是什么,再列数值。