🎨 design.md：让 AI 编码助手读懂你的设计灵魂——Google Labs 新规范深度解析

试想这样一个场景：你兴奋地启动 AI 编码代理，让它生成一个现代化的仪表板界面。几秒后，代码新鲜出炉，功能完善、结构清晰，但当你打开预览时——按钮用了上世纪 90 年代的渐变蓝，标题字体居然混搭了三次不同字族，间距忽大忽小像喝醉的尺子。你叹了口气，开始手动调整颜色、字体、圆角、阴影……这还算“AI 辅助”吗？

这正是 Google Labs 最近开源的 design.md 想要根治的顽疾。这个规范不是另一个 UI 框架，也不是新的设计工具，而是一份给编码代理看的视觉说明书。就像 README.md 告诉人类项目的意图，DESIGN.md 用机器可读的格式告诉 AI：“这就是我们的设计语言，请按这个来”。

🎯 为什么“设计令牌”还不够？

前端工程师早就在用设计令牌（design tokens）了——将颜色、字体、间距等抽象为 JSON 或 YAML，再通过 Style Dictionary 之类的工具生成 CSS 变量或 Tailwind 配置。听起来很美好，但当 AI 编码代理介入时，这些令牌孤岛就暴露出致命缺陷：它们缺乏语义上下文和媒介适应性。

例如，一个典型的 tokens.json 可能这样定义主色：

{
  "color": {
    "primary": {
      "value": "#2563EB"
    }
  }
}

它告诉工具“蓝色是这个值”，但却无法解释：这个主色在浅色模式下用于按钮背景，在暗色模式下用于文字高亮，在表单焦点态要加 2px 的外光圈，并且绝不能用在错误提示上。人类设计师默会这些知识，而 AI 代理却一脸茫然。

design.md 正是为此而生：它不是原始令牌的简单替换，而是一层语义封装，把设计决策的意图、约束和上下文规则一并用结构化方式记录下来。

🧬 解剖一份 DESIGN.md：从颜色到组件契约

打开项目的规范草案，你会发现它采用了一种声明式、分层描述的格式。最令人兴奋的并非它的语法（语法只是载体），而是其中蕴藏的“设计系统可计算化”的思想。

来看一个简化的例子：

design:
  name: "NeoBrand"
  tokens:
    colors:
      primary:
        value: "#2563EB"
        description: "核心品牌色，用于主要操作按钮和链接"
        restrictions:
          - "禁止用于文字正文（对比度不足）"
          - "暗色模式下自动替换为 lightPrimary"
    typography:
      heading:
        fontFamily: "Inter"
        weight: 700
        size: 
          base: 2rem
          responsive:
            mobile: 1.5rem
        lineHeight: 1.2
  components:
    Button:
      base:
        borderRadius: "8px"
        padding: "12px 24px"
        transition: "all 0.2s ease"
      variants:
        primary:
          background: "colors.primary"
          textColor: "white"
        ghost:
          background: "transparent"
          border: "1px solid colors.primary"
          textColor: "colors.primary"
      states:
        hover:
          primary:
            background: "darken(colors.primary, 10%)"
        focus:
          outline: "2px solid colors.primary"
          outlineOffset: "2px"

这已经远远超越了传统令牌的键值对。它明确定义了：

语义角色：颜色不仅是 primary，还带有人类可读的解释和禁止规则。
组件契约：Button 组件的结构就像一份小型 API，包含基础样式、变体（variants）和状态（states），并且值直接引用了顶层令牌（如 colors.primary），杜绝了魔法数字。
响应式与自适应：字体大小内嵌了断点逻辑，暗色模式替换规则也被预先声明。

这种结构让 AI 代理可以推理设计系统的规则，而非机械地复制粘贴变量。当代理需要生成一个暗色模式下的幽灵按钮时，它会根据 dark mode 配置自动引用 lightPrimary；当它想给某个组件上色时，会先检查 restrictions 避免违反对比度规范。

🤖 当 Coding Agent 吃下 DESIGN.md 后发生了什么？

理论说够了，我们看看实际集成流程。目前主流 AI 编码工具（如 GitHub Copilot、Cody、自定义的代码生成代理）都可以在项目根目录读取上下文文件。将 DESIGN.md 放置在那里后，代理可以将其作为长期指令缓存。

一个典型的 LLM 提示工程模式是：

You are an expert UI engineer. You must adhere to the design system 
defined in DESIGN.md. Before generating any component, analyze the 
relevant component contracts and token references. Do not invent new 
colors or spacing values unless explicitly allowed.

当用户要求“在此页面添加一个次要操作按钮”时，代理不再凭空捏造样式，而是解析 components.Button.variants.secondary，生成类似如下的代码：

import { Button } from '@/components/ui/button';

// 代理根据 DESIGN.md 知道 secondary 变体使用的是 ghost 样式
<Button variant="ghost">取消</Button>

甚至更激进的场景：代理可以直接根据组件契约生成整个组件库的样板代码。因为规范中已经定义了基础样式、变体和状态，代理只需将其映射到目标框架（React/Vue/Svelte）的语法糖上。这样一来，设计系统从“纸上文档”进化为“可执行规范”。

⚙️ 设计令牌 → 代理指令：一条自动化管道

设计团队维护原始令牌源（比如 Figma Tokens 插件导出的 JSON），然后通过转换工具生成 DESIGN.md。这可以无缝集成到 CI/CD 中：

🔄 Figma 令牌更新 → 脚本转换成带语义的 DESIGN.md → 自动提交 → Agent 下次运行自动读取最新设计。
🎨 品牌换肤只需修改几个颜色值，代理生成的所有界面即时同步。
📦 微前端架构中，不同子应用甚至可以引用各自的 DESIGN.md，但共享基础令牌。

这种管道彻底打破了设计-开发-AI 之间的“翻译损耗”。Google Labs 提供了一些参考解析器（可能是 TypeScript/Go 库），能够将 DESIGN.md 反序列化为类型安全的对象，方便在代码或代理工具链中使用。虽然目前规范还在早期阶段，但其理念已足够清晰。

💡 设计师视角：从“标注地狱”到“规则引擎”

对于设计师而言，维护一份详尽的组件规范常常是一场噩梦——标注稿充满了冗余的文本说明，开发人员还会频繁遗漏边缘情况。design.md 提供了一种单一事实来源，它既是设计移交文件，又是机器的输入。

过去，设计师需要在 Figma 里标注“按钮悬停时颜色加深 10%”，开发者在实现时可能用 opacity 代替，导致在不同背景下效果异常。现在，这个规则被写成 darken(colors.primary, 10%)，机器和人都可以明确理解为 HSL/LCH 色彩空间下的数学变换。这种精确性消除了歧义。

更重要的是，design.md 的可版本化管理能力让设计变更像代码一样可追溯。当产品经历一次品牌升级，你可以在 Git 历史中看到每一次颜色替换是如何影响所有组件的。

🌐 给 AI 戴上品牌的眼镜

Google Labs 推出的 design.md 规范，表面上是一份格式文档，实则是将设计系统提升为 AI 原生基础设施的重要一步。它让我们看到这样一个未来：编码代理不再仅仅是完成功能需求的码农，而是真正理解品牌灵魂的设计工程协作者。

或许不久之后，初始化的项目里除了 README.md、CONTRIBUTING.md，还会有一份醒目的 DESIGN.md。当 AI 阅读它时，就像戴上了一副精确匹配你品牌风格的眼镜——从此，再也没有跑偏的按钮，再也没有混乱的排版。

现在就前往 GitHub 仓库一探究竟，看看这份尚在进化中的规范如何重新定义你团队的设计-开发-AI 协作流程。让机器读懂设计，是通往真正智能开发体验的关键一步。