DESIGN.md 文件实测：84 份品牌文件对照 Google 规范，以及 Claude Code 拿到一份后会怎么做
我们把 awesome-design-md 里的 84 份 DESIGN.md 对照 Google 的 DESIGN.md 规范逐一检查，再让 Claude Code 在不给品牌、只报品牌名、放入品牌 DESIGN.md 三种情况下做了 54 个页面。有文件时，每个页面都用上了品牌的色板、主色和字体；只报名字时，只有四分之一的颜色对得上。这些文件大约 7,000 个 token，71 份里有 33 份至少有一组文字配色低于 WCAG AA。
概述
想让 Claude Code 按某个品牌的风格做页面，就把这个品牌的 DESIGN.md 放进文件夹，并让它照着文件做。只报品牌名不够。用之前先查一遍文件里的对比度，也要料到每次会话会更贵。
原因很简单：文件和结果我们都量过了。我们把 awesome-design-md 里的 84 份 DESIGN.md 对照 Google 的 DESIGN.md 规范逐一检查，然后让 Haiku 上的 Claude Code 给 Airbnb、Stripe、Jobright 各做页面，分三种情况：不给品牌、只报品牌名、放入品牌的 DESIGN.md，一共 54 个页面：
- 文件管用。 有文件时，页面颜色的中位数 100% 出自品牌色板，每个页面都用上了主色，也写出了品牌字体。18 次全都先读了文件。
- 只报名字，模型靠猜。 只报名字时，25% 的颜色对得上。Airbnb 那抹红模型认得，6 个页面里 5 个用上了。Stripe 每次都凭记忆用
#635bff，而文件写的是#533afd。Jobright 名气小，模型直接退回了通用的灰色系。 - 文件很长。 品牌文件中位 28,200 个字符，约 7,000 个 token，是 Google 自己示例的三倍。带文件的那组，费用是不给品牌时的 2.8 倍。
- 有些配色对比度不够。 71 份带颜色参数的文件里，33 份至少有一组文字和背景的对比度低于规范自己建议的 4.5:1。还有几组干脆把文字和背景设成了同一个颜色。
推荐
- 品牌不出名、或者颜色必须分毫不差时，用 DESIGN.md。 模型的记忆只粗略记得大品牌，小品牌完全不认识。让颜色准确的是那份文件。
- 交给 agent 之前，把每一组文字和背景都查一遍。 agent 会忠实地照抄文件，错的也照抄。Google 的 design.md 项目自带检查工具，任何 WCAG 对比度检查器也都行。普通文字低于 4.5:1，就当成 bug。
- 留意文件大小。 每次照着文件做的会话都要把它整个读一遍。Google 的三个示例每份约 2,200 个 token，品牌文件中位 7,000 个。要自己写的话，从 Google 的示例起步，别从你能找到的最长那份起步。
- 写参数，不要只写散文。 84 份里有 71 份像规范那样把颜色和字体写成 YAML，73 份按顺序用齐了规范的八节。参数给了 agent 可以直接照抄的精确值，这正是放文件那组颜色全中的原因。
- 想让工具读懂文件，就用规范推荐的颜色名。 规范推荐
primary、surface、on-surface、error这类名字。品牌文件中位只用了这 7 个里的 1 个，其余都是ink、canvas这种自己起的名字。
你的项目里是不是已经有一份 CLAUDE.md 或 AGENTS.md 写了界面该长什么样？DESIGN.md 是同一个思路，只是单独放成一个文件。这些文件怎么被读取，见我们的 CLAUDE.md 和 AGENTS.md 研究。
怎么测的
- 文件。 VoltAgent/awesome-design-md（MIT 许可）里全部 84 份 DESIGN.md，2026 年 11 月 7 日读取。每份描述一个知名品牌的设计系统。
- 规范。 Google 的 DESIGN.md 规范 alpha 版（Apache-2.0 许可）：八节，顺序固定（概览、颜色、字体、布局、层级与阴影、形状、组件、该做与不该做），参数写在 YAML 头部或 YAML 代码块里，并有推荐的参数名。
- 对比度。 凡是同时有
backgroundColor和textColor的组件参数，我们把{colors.primary}这类引用解析成十六进制色值，计算 WCAG 对比度。排除了 WCAG 豁免的禁用状态，以及分隔线、环、图标这类非文字元素，剩下 1,438 组文字配色。 - 实测。 三个配色鲜明的品牌（Airbnb、Stripe、Jobright），三种页面（价格页、注册表单、首页主视觉），三种情况，各跑两遍：Claude Code 2.1.314 上 54 个全新的
claude -p会话，--model haiku，只允许使用读文件工具。每个回答是一个 HTML 文件。 - 判分。 收集每个页面用到的不同十六进制色值，算其中有多少出现在品牌 DESIGN.md 的颜色参数里，再看有没有用上品牌主色、有没有写出品牌的首选字体。
测试结果
84 份文件对照规范
| 品牌文件 | Google 的示例（3 份） | |
|---|---|---|
| 中位长度 | 28,200 字符，约 7,050 token | 8,660 字符，约 2,165 token |
| 颜色和字体写成 YAML 参数 | 84 份里 71 份 | 3 份全是 |
| 规范的八节全有且顺序正确 | 84 份里 73 份 | 每份 8 节里有 7 节 |
| 颜色参数个数中位 | 23 | 47 |
| 规范推荐的颜色名，中位用了 | 7 个里 1 个 | 7 个里 6 个 |
| 常见的额外章节 | 响应式（61 份）、迭代指南（50 份）、已知缺口（43 份） |
文字配色，71 份文件里的 1,438 组
| 组数 | 至少有一组的文件数 | |
|---|---|---|
| 低于 4.5:1 | 77（5%） | 33 |
| 低于 3:1 | 24 | |
| 文字和背景同色 | 3 | 3 |
对比度最低的几组出在”推荐套餐”卡片、营销主视觉这类组件上，文字和背景解析出来是同一个参数。这更像是文件写错了，而不是设计上的选择，照着文件做的 agent 会把它原样复制出来。
三种情况下 Claude Code 的表现，每种 18 个页面
| 不给品牌 | 只报品牌名 | 放 DESIGN.md | |
|---|---|---|---|
| 颜色出自品牌色板，中位 | 9% | 25% | 100% |
| 用上品牌主色 | 18 个里 0 个 | 18 个里 5 个 | 18 个里 18 个 |
| 写出品牌字体 | 18 个里 0 个 | 18 个里 0 个 | 18 个里 18 个 |
| 输出 token 中位 | 2,689 | 4,259 | 7,240 |
| 18 次费用 | 0.052 美元 | 0.067 美元 | 0.147 美元 |
按品牌，颜色出自色板的中位数
| 不给品牌 | 只报品牌名 | 放 DESIGN.md | |
|---|---|---|---|
| Airbnb | 9% | 65% | 100% |
| Stripe | 10% | 25% | 97% |
| Jobright | 9% | 9% | 100% |
不给品牌时命中的只有白色，每个色板里都有。只报 Airbnb 的名字时，模型用的是 Circular，这是 Airbnb 以前的字体，文件里只把它排在 Airbnb Cereal 后面作备用。只报 Stripe 的名字时，它每次都选了大家熟悉的那套紫色和深蓝；文件给出的是另一种紫色。哪个才是 Stripe 现在在用的，我们判断不了，但只有放文件那组用的是文件里的值。
该忽略什么
- 合集里有多少份文件。 收了 84 份还是 759 份，说明不了其中任何一份是对的。用哪份就查哪份。
- 描述风格的形容词。 文件开头都是大段描述氛围的文字。agent 照抄的是 YAML 里的值，那些散文有没有起作用，我们没测。
- 写出字体名就等于显示出来了。 CSS 里写上品牌字体并不会加载它。品牌字体大多要授权，除非你自己托管，页面会退回字体列表里的下一个。
局限
- 三个品牌、三种页面、只测 Haiku。 更大的模型可能记得更多品牌，只报名字那组的差距会缩小。
- 色板命中率只算十六进制完全一致的。 页面用了几乎一样的色调，也会算作没命中。
- 品牌文件是第三方的分析。 描述的是作者眼中这个品牌的样子，不是品牌方发布的官方规范。
- 对比度只查了组件参数。 只在散文里描述的文字颜色没有检查。
自己复现
脚本是 design-md-files-2026-11-catalog.py，用来对照规范检查一整个文件夹的 DESIGN.md；以及 design-md-files-2026-11-test.py，用 Claude Code 跑那 54 个页面并判分。数据 design-md-files-2026-11.json 里有每份文件的测量结果和对比度配对、Google 的三个示例，以及每一次实测。
来源
- google-labs-code/design.md：DESIGN.md 规范 · official
- VoltAgent/awesome-design-md · official
- W3C：WCAG 2.2 最低对比度 · official
- AgentCraft：5,864 个仓库里的 CLAUDE.md 和 AGENTS.md · blog