DESIGN.md：让 AI 编码助手理解你的设计系统

原文来源：GitHub - google-labs-code/design.md — Google Labs 推出的 DESIGN.md 格式规范，让 AI 编码代理持久理解视觉设计系统，19.2k Stars，1.7k Forks。

如果你用过 AI 编码工具（Claude Code、Cursor、Copilot）来写前端代码，大概率遇到过这种场景：AI 生成的按钮颜色完全不对，字体用了系统默认的 Arial，圆角和间距随心所欲——不是说它做不对，而是它每次都要重新"理解"你的设计。

DESIGN.md 就是 Google Labs 对这个痛点的解决方案。

什么是 DESIGN.md

DESIGN.md 是一种格式规范，用结构化的方式描述视觉设计系统。它借鉴了 README.md 在整个开源世界中的"项目入口"角色，但专门为 AI 编码代理设计。

A format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.

简单说：你在项目根目录放一个 DESIGN.md 文件，你的 AI 编码助手就能读懂你的设计系统——颜色、字体、间距、圆角、组件样式——然后生成风格一致的前端代码。

格式设计：两层结构

DESIGN.md 由两部分组成：

1. YAML 前置元数据（机器可读的设计 Token）

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

2. Markdown 正文（人类可读的设计理念）

## Overview

Architectural Minimalism meets Journalistic Gravitas. The UI evokes a
premium matte finish — a high-end broadsheet or contemporary gallery.

## Colors

Prose explains the rationale behind color choices.

Token 是规范性的（normative）——AI 应当遵循。正文提供上下文——帮助 AI 理解何时、为何使用这些 Token。

支持的设计 Token

目前支持五类 Token：

组件层可以定义具体的 UI 组件样式：

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"

变体（hover、active 等）通过关联命名的子键表达。

CLI 工具

Google Labs 同时提供了 npm 包 @google/design.md，包含两个核心命令：

lint：验证 DESIGN.md

npx @google/design.md lint DESIGN.md

输出示例：

{
  "findings": [
    {
      "severity": "warning",
      "path": "components.button-primary",
      "message": "textColor (#ffffff) on backgroundColor (#1A1C1E) has contrast ratio 15.42:1 — passes WCAG AA."
    }
  ],
  "summary": { "errors": 0, "warnings": 1, "info": 1 }
}

diff：比较两个版本的差异

npx @google/design.md diff DESIGN.md DESIGN-v2.md

输出结构化的 Token 变更报告，包括新增、删除、修改的 Token，以及是否构成回归。

为什么这是重要趋势

DESIGN.md 是 AI 编码时代"基础设施层"的典型代表。它解决了一个根本问题：AI 代理没有设计记忆。

每次你让 AI 写前端代码，它都是从零开始理解你的设计需求。即便你在提示词里贴了颜色值，换了上下文它就忘了。DESIGN.md 给 AI 提供了一个持久的、每次加载项目时自然会读取的"设计上下文"。

这个思路其实和 .env 文件类似——把配置从代码中分离出来。只不过 DESIGN.md 分离的是设计配置。

项目状态

• Stars: 19.2k（趋势上升中）
• License: Apache-2.0
• 状态: Alpha
• 语言: TypeScript (95.7%)
• 包管理器: Bun（pinned v1.3.9）

值得注意的是，项目托管在 google-labs-code 组织下，这是 Google Labs 的新 GitHub 组织。目前处于早期阶段，社区正在围绕它形成生态——已有 awesome-design-md 等社区项目收集优秀的 DESIGN.md 示例。

生态系统的响应

截止目前，GitHub 上已有多个项目开始采用 DESIGN.md 格式。一些 AI 编码工具也开始原生支持读取 DESIGN.md——当你在项目中初始化 coding agent 时，它自动加载 DESIGN.md 作为前端代码生成的上下文。

这让人想起 README.md 的生态化过程：先是一个格式规范，然后是工具支持，最后成为社区最佳实践。DESIGN.md 正在走同样的路。

结语

对于使用 AI 编码工具的独立开发者和前端团队来说，DESIGN.md 是一个值得立即采用的实践。写一份 50 行的 DESIGN.md，能让 AI 生成的前端代码风格一致性提升几个档次。在 AI 编码越来越普及的今天，"设计即配置"的思路可能很快会成为前端开发的标准实践。