design.md - 面向编码智能体的视觉身份格式规范

这是什么

google-labs-code/design.md 是由 Google Labs 推出的一个开源项目，旨在为 AI 编码代理（Coding Agents）提供一种标准化的视觉身份描述格式。它不仅仅是一个设计系统文档，更是一个机器可读与人类可读相结合的规范文件。

该项目的核心是一个名为 DESIGN.md 的文件格式，它通过 YAML front matter 定义机器可读的设计令牌（Design Tokens），并通过 Markdown 正文提供人类可读的设计 rationale（设计理由）。这种结构使得 AI 代理能够精确获取颜色、字体、间距等具体数值，同时理解这些数值背后的设计意图和应用场景。

目前该项目处于 Alpha 阶段，其 CLI 工具包发布在 npm 上，包名为 @google/design.md。

解决的问题

在现代前端开发中，尤其是引入 AI 辅助编码（如 Cursor、GitHub Copilot 等）后，存在以下痛点：

1. 上下文缺失：传统的 UI 组件库或 CSS 变量文件只提供了“怎么做”（How），但缺乏“为什么”（Why）。AI 代理虽然能读取变量值，但往往不理解设计系统的整体风格（如“建筑极简主义”或“新闻严肃感”），导致生成的 UI 虽然功能正确但风格不统一。
2. 格式碎片化：设计令牌分散在 Figma、Storybook、CSS 文件、Tailwind 配置等多个地方，AI 难以一次性获取完整的设计上下文。
3. 验证困难：当设计系统发生变更时，难以自动化检测这些变更是否破坏了现有的视觉一致性或无障碍标准（WCAG）。

design.md 通过单一文件解决了上述问题，将设计系统的“数据层”和“语义层”统一，为 AI 代理提供了一个持久化、结构化的设计系统理解基础。

核心功能

1. 双模态文件结构

DESIGN.md 文件包含两个关键部分：

• YAML Front Matter：包含严格的结构化数据，如颜色（colors）、排版（typography）、圆角（rounded）、间距（spacing）和组件（components）。这些是代理执行代码时的“真理来源”。
• Markdown Body：包含自然语言描述，解释设计原则、颜色选择的原因以及组件的使用场景。这帮助代理在生成代码时保持设计意图的一致性。

2. 智能 Linter (Lint)

内置的 linter 可以验证 DESIGN.md 文件的结构正确性，并检查设计令牌的合理性。

• WCAG 对比度检查：自动计算文本颜色与背景色的对比度，确保符合无障碍标准。
• 令牌引用检查：检测是否存在未定义的令牌引用或错误的嵌套。
• 结构化输出：所有检查结果均以 JSON 格式输出，便于 CI/CD 流程集成或供其他代理解析。

3. 版本 Diff 与回归检测

通过 diff 命令，可以比较两个不同版本的 DESIGN.md 文件，识别令牌级别的变更（新增、删除、修改）以及正文中的回归问题。这对于维护设计系统的演进至关重要。

4. 多格式导出 (Export)

支持将 DESIGN.md 中的令牌导出为多种主流前端框架所需的格式：

• Tailwind CSS：支持导出为 Tailwind v3 的 JSON 配置或 Tailwind v4 的 CSS @theme 块。
• DTCG：导出为 W3C Design Token Format 标准的 tokens.json 文件。
• CSS Variables：生成标准的 CSS 自定义属性。

5. 组件映射

支持在 YAML 中定义组件级别的令牌映射，例如：

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"

代理可以直接读取这些映射来生成具体的 UI 组件代码。

亮点 / 与同类相比

• 专为 AI 代理优化：与 Storybook 或 Figma 插件不同，design.md 的语法设计考虑了 LLM（大语言模型）的上下文窗口和解析能力。它强调“机器可读”与“人类可读”的结合，不仅给数据，还给意图。
• 单一事实来源 (Single Source of Truth)：传统工作流中，设计师维护 Figma，前端维护 CSS/Tailwind，文档维护 Markdown。design.md 试图将这三者收敛到一个文件中，减少同步成本。
• 内置设计语义：大多数设计令牌系统只存储值（如 #1A1C1E），而 design.md 允许通过 Markdown 正文存储设计哲学（如 "Architectural Minimalism meets Journalistic Gravitas"）。这使得 AI 在生成非标准组件或调整布局时，能更好地把握整体调性。
• 轻量级且独立：作为一个 npm 包，它不依赖庞大的设计工具链，可以独立集成到任何前端项目中，甚至在没有设计工具的情况下也能通过代码定义设计系统。

适合谁用 / 上手

适合人群

• 使用 AI 编码代理的团队：如果你正在使用 Cursor、Windsurf 或 GitHub Copilot 进行开发，并希望 AI 生成的 UI 严格遵循公司的设计系统，这个项目是理想的配置。
• 设计系统维护者：需要一种比 Figma 更易于版本控制和代码集成的方式来管理设计令牌。
• 独立开发者：希望快速建立一套可复用、可描述的设计规范，并让 AI 辅助生成一致的 UI。

上手指南

1. 安装 CLI：

   npm install @google/design.md
   # 在 Windows PowerShell 中，建议加引号
   npm install "@google/design.md"
   

2. 创建 DESIGN.md： 在项目根目录创建 DESIGN.md，按照规范填写 YAML front matter 和 Markdown 正文。

3. 验证与调试： 使用 lint 命令检查文件是否符合规范：

   npx @google/design.md lint DESIGN.md
   

   输出 JSON 格式的 findings，包括错误、警告和建议。

4. 集成到前端项目： 使用 export 命令将令牌导出为 Tailwind 或 CSS 变量，并导入到你的项目中：

   npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
   

5. 配置 AI 代理： 将 DESIGN.md 的内容添加到 AI 代理的系统提示词（System Prompt）或上下文文件中，使其在生成代码时能够参考该设计系统。

注意：该项目目前处于 Alpha 阶段，规范可能会发生变化。此外，在 Windows 环境下使用 CLI 时，建议使用 designmd 别名以避免文件关联冲突。