DESIGN.md 示例,逐段拆解
理解 DESIGN.md 最快的方式就是走读一份。下面按 AI 阅读的顺序,拆解一份完整文件的解剖结构——每个章节装什么、在文件里长什么样、为什么放在那个位置。可以直接当模板用:这里的结构,就是你为自己的风格动笔时要写的结构。
文件的整体形状
每份合格的 DESIGN.md 都有相同的三层,顺序也相同。最前是 frontmatter 块——几行结构化元数据,机器最先读它。然后是 token 章节——配色、字体、间距、形状、阴影、动效——每项都是精确值。最后是应用层:组件逻辑与用法说明,把 token 变成页面的那些文字规则。
顺序本身就是要点。agent 从上往下读,文件因此从定位(这是什么?)走到词汇(值是多少?),再走到语法(它们怎么组合?)。这个形状的文件一遍就能解析完——不用回头,不用推断。
frontmatter:名字、精髓、标志位
文件以一段围栏 YAML 块开头,只有几个字段:风格的名字;一句话精髓——比如包豪斯式规范可能写「几何的清晰,三原色点缀,形式追随功能」;以及会改变后续渲染的布尔标志位,其中最重要的是这套风格是否深色。
这一块虽小,却是全文件里每行干活最多的部分。精髓句给后面所有解读定了调;单是深色标志位,就会翻转 agent 处理对比度、层级和配图的方式。哪怕 agent 只读到这里,它已经能避开最糟的错误。
token 章节:精确值,按角色命名
配色章节列一套命名色板,每一项都是「角色 + 精确值」:背景 <hex>、墨色 <hex>、一小组强调色 <hex>、发丝线 <hex>。按角色而不是按外观命名——agent 因此知道每个颜色属于哪儿,而不只是它长什么样。
字体章节点名字体家族与字重,然后给出具体尺寸的字阶——展示、标题、正文、注文,各自的 <px> 与行高。间距章节写明版式吸附的节奏:一个 <px> 的基础单位,和在它之上搭出的步长。
形状、阴影、动效补全词汇表:以 <px> 计的圆角、带阴影值的层级、带时长的缓动曲线。这里每一条都是机器能照抄执行的数字——每一行都得过这个测试。
诚实说明一点:本文走读里的值都是 <hex>、<px> 这样的占位符。DESIGN.md 的结构是开放的;Curio 每种风格的精确数值是付费产品。对模板而言,重要的是形状——换上你自己的值,文件就能用。
应用层:组件逻辑与边界
token 之后,是高频组件的简短陈述式规则。按钮规则可能写:主按钮以墨色填充、文字用背景色、圆角取形状章节的值、不带阴影。卡片规则:卡片坐在发丝线边框里,永远不浮在投影上。强调规则:层级靠字号与字重,绝不靠加颜色。
文件以用法说明收尾——几句话讲清这套风格擅长哪儿(杂志式页面、营销站),不该去哪儿(高密度数据表、仪表板)。正是这些边界,拦住 agent 把一套漂亮的风格用错地方。
拿它当模板——或者直接拿一份真的
如果你在编码自己的品牌,这篇走读就是模板:frontmatter 开头,token 按角色写明,组件逻辑与边界收尾。填上你的值,一份能干活的规范就有了。
如果你要的是一种成熟风格,那这个文件已经存在了。Curio 库中的每种风格——从包豪斯到品牌级的当代长相——都以这个形状的完整 DESIGN.md 交付,真实数值已经填好,你的 AI 通过 MCP、分享链接或下载即可套用。
常见问题
能把这个结构直接抄去当模板吗?
可以——结构是开放的,这篇文章就是给你抄的:frontmatter、按角色写的 token 章节、组件逻辑、适用边界。Google 的开放 DESIGN.md 规范也是这个整体形状,照此写的文件任何认这个格式的工具都能读。
为什么值是占位符而不是真实数字?
因为数值本身就是产品。DESIGN.md 的结构是公开知识,本页全部展示了;而 Curio 每种风格经过调研的精确 token 值,是付费方案解锁的内容。至于你自己品牌的文件,值当然由你自己填。
最小可用的 DESIGN.md 长什么样?
frontmatter 里有名字、精髓句和深色标志位;精确值的色板与字阶;一个间距单位;外加三条组件规则(按钮、卡片、强调)。半页纸就装下了,而且已经胜过任何用形容词写的 prompt。