> ## Content Index > Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt > Use this file to discover other available public pages before exploring further. # DESIGN.md: AI 缺失的设计系统 - URL: https://www.hubwiz.com/blog/design-md-the-missing-design-system-for-coding-agents/ - Published: 2026-05-01T15:04:16.000Z - Updated: 2026-10-13T16:10:45.000Z - Description: AI 编码 Agent 在视觉一致性方面出人意料地糟糕。 - Author: admin - Tags: AGENT, DESIGN.MD, #Import 2026-10-14 14:41 让一个 Agent 构建设置页面、仪表盘和定价页面，每一个都会开始与上一个产生偏差。间距变了。蓝色调偏移了。按钮看起来像是表亲而不是兄弟。你最终要么每次生成都要盯着看，要么之后花几个小时手工修复视觉漂移。 Google 的新 DESIGN.md 规范试图用一种几乎简单到愚蠢的东西来解决这个问题：一个 Agent 实际上能读取的纯文本文件。 Google Labs 于 2026 年 4 月 21 日开源了该规范草案。八天后，[官方仓库](https://github.com/VoltAgent/awesome-design-md?ref=hubwiz.com) 的 GitHub 星标已突破 10,000，而另一个社区合集 [github.com/VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md?ref=hubwiz.com) 已飙升至超过 68,000。这是大多数付费产品都梦寐以求的早期开发者关注度。 这比看起来更重要。而大多数做产品的人还没有注意到。 ## 1、没人愿意承认的问题 AI 编码 Agent 会幻觉十六进制颜色代码。而且频繁发生。 让 Cursor、Claude Code 或 Antigravity"构建一个与我们应用匹配的设置页面"，你会得到 80% 正确、20% 微妙错误的东西。内边距差了 4 个像素。按钮悬停状态使用了略有不同的蓝色。H2 的字体粗细与应用中其他任何地方都不匹配。每次生成都会离你的设计系统更远一点，因为模型每次都在无状态地猜测。 业界对此有一个名字。他们称之为"AI slop"（AI 粗制滥造）。 设计团队试图用 Figma 设计令牌、导出的 JSON 文件、Storybook 集成和没人读的 Notion 文档来解决这个问题。但 Agent 看不到其中任何一个。 DESIGN.md 用一种古老到几乎有些冒犯的策略来解决这个问题：把它写下来，放在 Agent 能读到的地方。 ## 2、这个模式在代码领域已经存在 现在它也来到了设计领域。 如果你认真使用过 Claude Code 或 Cursor，你已经了解这个想法了。 CLAUDE.md、AGENTS.md 和 .cursorrules 是放在项目根目录的纯文本文件，告诉 AI Agent 你的代码库是如何工作的。命名约定。测试规则。架构决策。Agent 在每次会话开始时读取它们，你的生成就不再漂移了。 DESIGN.md 是同样的模式，终于来到了视觉系统。同样的根目录。同样的纯文本。同样的目的：给随机系统一个它可以返回的确定性锚点。新颖之处不在于文件格式，而在于有人专门为设计意图构建了一个严格的、可验证的模式，并随附了工具。 一旦你把它看作 CLAUDE.md 的视觉表亲，一切就都说得通了。 ## 3、文件里实际有什么 DESIGN.md 之所以有效，是因为它有两层：机器指令和人类解释。 文件的顶部是包裹在 `---` 围栏中的 YAML 前置数据。这是机器层。颜色以十六进制代码表示，排版作为包含字体族、粗细、行高的嵌套对象，整个令牌系统都在其中。令牌之间使用花括号语法相互引用，如 `{colors.primary}`，因此按钮的悬停状态会动态地从你的基础颜色中获取。只需更改一次主色，每个引用它的组件都会更新。 在 YAML 下方，你会看到标准 `##` 标题下的 Markdown 文本。这是人类层。它解释的是*为什么*。为什么主色是"Boston Clay"而不仅仅是 `#B8422E`。间距哲学到底是什么。什么时候该用阴影而不是边框。 这种双重结构就是整个诀窍。 LLM 两者都需要。只给 AI 一个十六进制代码 `#B8422E`，它会在你的 UI 中随机使用。给它同样的十六进制代码，附加上文本上下文说明这个颜色是应用程序中*唯一的交互驱动色*，Agent 就会停止在随机表面上涂橙色。文本不是装饰。它是对随机模型的行为编程。 ## 4、运行一切的部分 该规范强制执行严格的规范顺序。你可以跳过某些部分，但不能重新排序。重要的不是 DESIGN.md 有这些部分，而是它给 Agent 一个可预测的位置来找到决策：颜色、排版、布局、组件，以及它不应违反的规则。 完整顺序如下： 1. **概述** 设定基调和密度哲学 2. **颜色** 将语义名称映射到十六进制代码 3. **排版** 定义完整层次结构 4. **布局** 规定间距比例和网格约定 5. **阴影与层次** 处理阴影和 z-index 规则 6. **形状** 控制边框圆角和边缘哲学 7. **组件** 定义特定 UI 集群及其状态 8. **应该做和不应该做的事** 建立防止 Agent 幻觉的护栏 最后一个部分是秘密武器。大多数设计系统都是作为正面指令编写的（"在主要操作中使用主要按钮"）。DESIGN.md 积极鼓励负面指令（"永远不要在宽度超过 200px 的背景上使用强调色，永远不要将 `card-elevated` 与 `border-strong` 组合使用"）。负空间，写下来。AI Agent 对"不要"的响应出奇地好，因为它消除了概率分布中的模糊性。 ## 5、之前和之后：这实际改变了什么 没有 DESIGN.md 时，你的提示词是这样的： > *"给我构建一个包含侧边栏、统计卡片和数据表的客户仪表盘。让它看起来像我们的应用。"* Agent 会猜测颜色、发明间距，产出的东西需要 30 分钟来清理。 当项目根目录中有了 DESIGN.md，同样的提示词变成了： > *"给我构建一个包含侧边栏、统计卡片和数据表的客户仪表盘。严格遵循 DESIGN.md 中的交互、间距、排版和组件规则。不要引入新的颜色或按钮样式。"* Agent 读取文件，按名称引用你的令牌，并在第一次尝试时就非常接近你现有的 UI。这就是用两个提示词概括的整个推介。 ## 6、Linter 是真正严肃的部分 Google 将 `@google/design.md` 作为 npm 包与规范一起发布，lint 命令在真正发挥作用。在任何令牌编译为生产代码之前，会运行八条诊断规则。 最值得每个无障碍倡导者欢呼的是 `contrast-ratio`。它为每个定义的背景-文本颜色配对计算相对亮度，如果任何配对低于 WCAG AA 4.5:1 标准则发出警告。AI 生成模型有记录表明倾向于产生美观但不可访问的低对比度设计。将 WCAG 验证直接嵌入设计协议中，迫使问题在基础层面得到解决，而不是在屏幕阅读器用户提出投诉之后。 `broken-ref` 捕获组件引用了不存在的令牌的情况。`orphaned-tokens` 对你的设计系统进行死代码分析，标记没人使用的令牌，以保持你的上下文窗口干净。`duplicate-section` 是一个硬性错误，因为规范层次结构依赖于可预测的解析。 你可以在 CI 中运行它。你的设计系统获得了与代码相同的回归测试。视觉一致性不再是一门凭感觉的学科。 值得注意：该规范还是 alpha 版本。模式和 CLI 正在积极开发中。模式是可靠的；具体规则会继续调整。 ## 7、如何在明天真正尝试这个 你不需要承诺任何事情。以下是测试这是否会改变你工作流程的最简单方法。 **第一步：** 选择一个副项目。3 到 5 个页面的那种。不是你日常工作中的生产应用。你需要一个奇怪的输出无关紧要的沙盒。 **第二步：** 访问 [github.com/VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md?ref=hubwiz.com)。社区贡献者创建了受 Stripe、Vercel、OpenAI、Apple、Figma、Linear、Notion 等数十家公司启发的 DESIGN.md 风格文件。这些是从公开网站中提取并按原样共享的，不是那些公司的官方制品。选一个你真正想借鉴其美学的。 **第三步：** 将文件放入项目的根目录，命名为 `DESIGN.md`。就这样。不需要构建步骤。 **第四步：** 打开 Cursor 或 Claude Code 或你使用的任何 Agent。使用上面"之后"那个提示词。看看会发生什么。 Agent 将文件作为其上下文窗口的一部分读取，并开始按名称使用你的令牌，而不是发明十六进制代码。你过去 18 个月一直在默默忍受的漂移问题基本消失了。 如果你想更进一步，安装 `@google/design.md` 包并对文件运行 `design-md lint`。你会看到诊断输出。如果你想把文件转换为 Tailwind 配置或 W3C 标准的 JSON 令牌，导出命令一行就能搞定。 ## 8、大多数人忽略的部分 人们正在把 DESIGN.md 当作 Figma 的替代品来评估。它不是。 Figma 是人类协作进行视觉决策的画布。DESIGN.md 是机器执行这些决策的上下文文件。它们解决不同的问题。有趣的问题不是"这是否会杀死 Figma"。有趣的问题是 Figma 是否会开始原生导出 DESIGN.md，就像它最终开始导出设计令牌一样。 我认为它会的，而且会很快。否则它就会成为坐在开发工作流旁边的断连画布，而每个人的实际构建都是通过无法读取 .fig 文件的 Agent 完成的。 更深层次的变化是：我们正在见证设计从图形学科转向写作学科。现在重要的技能是清晰地将意图表达出来，让随机系统能够一致地据此行动。不是像素推敲。不是矢量操作。是写作。 设计师的工作并没有消失。它正在变得更加显式化。 这是设计师需要擅长的真正变化。而且不管设计社区是否愿意，它都在发生。 ## 9、我会真正关注什么 未来六个月值得追踪的几件事。 [awesome-design-md issue 追踪器](https://github.com/VoltAgent/awesome-design-md/issues?ref=hubwiz.com)目前是该规范最好的压力测试。超过 270 个开放的 issue，贡献者正在积极发现边缘情况，这些情况将影响下一个官方修订。如果你想知道该格式真正薄弱的地方在哪里，去读那些 issue。当前的争论围绕 DESIGN.md 应如何处理复杂动画、暗色模式令牌和响应式断点。这些都没有完全解决。 Anthropic、Cursor 或其他主要 Agent 平台是否会正式认可该格式。目前采用是自下而上的。如果主要 IDE 之一将原生 DESIGN.md 感知作为一等公民功能发布，该规范一夜之间就会从"有趣的标准"变成"默认基础设施"。 MCP 集成的故事。Google 的 Stitch MCP 服务器让 Agent 可以直接从云端项目中将设计数据拉取到本地 DESIGN.md 文件中。如果这变成双向的，即代码库中的编辑回流到设计工具，你就把设计到代码的交接压缩成了一个单一的同步状态。那才是真正的终局。 ## 10、一个诚实的提醒 这是 alpha 版。该规范才刚一周大。工具之间存在解析不一致，YAML 模式将会改变，一些规范部分的顺序感觉是任意的，这表明它会被修订。 但底层模式——给 AI Agent 一个结合了机器可读令牌和人类可读解释的结构化纯文本文件——将比这个特定实现更持久。即使 Google 明天放弃 DESIGN.md，也会有人在三个月内用不同的文件名发布同样的想法。这个品类已经存在了。 最坏的情况是浪费一个下午在一个奇怪的小 Markdown 实验上。 最好的情况是你的 AI Agent 不再把你的界面当作情绪板来对待。 DESIGN.md 可能会改变。模式可能会调整。工具可能会更名。但这个趋势不会消失：设计系统正在成为机器可读的指令。而那些学会清晰地编写这些指令的人将拥有不公平的优势。 --- 原文链接: [Google's DESIGN.md Is the Design System AI Coding Agents Were Missing](https://medium.com/@creativeaininja/googles-design-md-is-the-design-system-ai-coding-agents-were-missing-1e08de0c7725?ref=hubwiz.com) 汇智网翻译整理，转载请标明出处 > **这是「Agent / MCP」专题的一部分。**完整地图见：[Agent / MCP / 自动化完全指南](https://www.hubwiz.com/blog/agent-stack/)