怎么写 DESIGN.md
DESIGN.md 有效的前提只有一个:读它的机器永远不用猜。写好它的全部功夫就在这里——先定位后细节,写数值不写形容词,把 agent 真会去搭的组件讲到。下面是行之有效的结构,和那些悄悄毁掉它的错误。
先写定位,别先堆细节
文件的开头应该告诉机器它在看什么:风格的名字、一句话的精髓——你会用哪句话向没见过这个风格的人描述它——以及会改变后面一切的标志位,比如这套风格是浅色还是深色。
多数规范把这些放在文件顶部的一小段结构化块里(YAML frontmatter 是通行约定,Google 的开放 DESIGN.md 规范用的也是它)。agent 先读这一块,再用它去解读后面的每个章节。一个开头就砸下五十个色值、却没有定位的文件,会逼模型自己重建意图——这恰恰是你想消灭的那种猜测。
写数值,不写形容词
「温暖、极简、杂志感」对每个模型、每次运行的含义都不一样。「背景 <hex>,墨色 <hex>,一个强调色 <hex>,正文 <px>、行高 1.5,间距走 <px> 的节奏」每次含义都相同。token 是合同;形容词是装饰。
token 按角色命名,不按外观命名:background、ink、accent、line——而不是「浅灰」或「蓝色」。角色名扛得住换主题,而且告诉 agent 这个值属于哪儿,而不只是它是什么。
文件里可以有文字,但要给文字派活:解释这些值为什么是这样、怎么组合。「强调色每屏只留给一个动作」是 agent 能执行的文字;「这套色板感觉很平静」不是。
把 agent 真会搭的组件讲到
只有 token 是撑不起一套 UI 的。两种风格可以共享一套色板,长得却完全不同,差别就在组件逻辑里:按钮是实心还是描边、直角还是圆角?卡片浮在阴影上,还是坐在发丝线边框里?强调靠字重、字号,还是颜色?
把这些写成简短的陈述式规则,覆盖那几个到处出现的组件——按钮、卡片、输入框、导航。再加上适用边界:这套风格适合哪儿、不适合哪儿。知道某风格是为杂志式页面而生的 agent,就不会把它硬塞进一个高密度仪表板。
悄悄毁掉规范的几个错误
有形容词没数值。最常见的失败:一段写得漂亮的氛围描述,一个数字都没有。agent 频频点头,然后自己编一套色板。
把整本品牌手册倒进去。DESIGN.md 是干活用的规范,不是档案馆。如果读文件比搭页面还慢,agent 就会跳读——跳读就是带着自信在猜。只留下会改变产出的内容。
没有适用边界。从不说明这套风格不该去哪儿的规范,会被套到所有地方,而且套得很糟。
任它腐烂。这个文件是仓库里的纯文本,要像对待代码一样对待它。设计变了,DESIGN.md 就该在同一个 commit 里跟着变——否则 agent 会忠实地应用上个季度的设计。
内部自相矛盾。字体章节说一套字阶、组件示例暗示另一套,agent 只能二选一——而且它不会告诉你它选了哪个。
或者跳过手写:挑一份现成的
为一套你自己拥有的设计系统写 DESIGN.md,值得。但如果你想要的是一种成熟风格——包豪斯、瑞士国际主义、某种品牌级的当代长相——手写这份文件意味着你要亲自逆向工程整个流派的规则,而「微妙地写错」是默认结局。
这就是库存在的理由。Curio 以完整 DESIGN.md 交付数百种真实设计风格——已经调研、已经结构化,你的 AI 通过 MCP、分享链接或下载即可套用。挑风格就行;文件已经写好了。
常见问题
DESIGN.md 该写多长?
在能回答 agent 会遇到的每个视觉问题的前提下,越短越好。实践中通常是一两页:一段定位、核心 token 章节、高频组件的规则、适用边界。如果某个章节不会改变 AI 的产出,删掉它。
文件该放在项目的哪里?
项目根目录,挨着 README.md——编码 agent 最先看那里,也符合这个名字本身暗示的约定。有些工具也支持显式指定路径或通过 MCP 拉取,但放根目录在哪儿都好使。
写成一个文件还是拆成几个?
一个。这个格式的意义就在于 agent 一次读完整套设计系统。规范一旦散落多个文件,你就在指望 agent 自己找齐并调和它们——这又把格式本来要消灭的猜测请了回来。
必须写 YAML frontmatter 吗?
它是 Google 开放规范采用的约定,也是机器最好解析的一块,所以是个好默认。但更本质的规则是「先定位后细节」:无论语法如何,文件都应该先说这套风格是什么,再列数值。