DESIGN.md：让 AI 一次写对你想要的 UI 风格

速览

项目	说明
GitHub	google-labs-code/design.md
是什么	给 AI 编码助手读的「设计系统说明书」——一个纯文本文件，YAML token 给精确值（机器读），Markdown 说明讲设计意图（人读）
解决什么	AI 写 UI 风格不稳定：颜色偏、字体不对、间距乱，口头描述每次都不一样。DESIGN.md 让 Claude Code / Cursor 读一次就记住你要的风格
状态	Alpha / 15.7k Star / Apache 2.0，npm 包 @google/design.md

文件长什么样

两层结构：YAML front matter 放 token，Markdown body 放设计说明。

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

## Colors

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Tertiary (#B8422E):** Boston Clay — the sole driver for interaction.

仓库哲学说得很直白：prose 比 token 更重要。token 是上下文参考，真正约束 AI 行为的是描述性文字——一个具体参照（「像排版考究的论文预印本」）自带负面约束，比十个「现代、简洁、高级」的形容词有用得多。

三步上手

1. 建文件：规范定义了 8 个标准 section（Overview / Colors / Typography / Layout / Elevation & Depth / Shapes / Components / Do's and Don'ts），按顺序写，不必写全，不认识的自定义 section AI 会保留不报错。
2. 写 token：最简只要 name + colors。颜色支持 hex、rgb()、oklch()；token 间用 {colors.primary} 花括号语法互相引用。
3. 写 prose：给具体参照，别堆形容词。

10 行就能用的最小版本：

---
name: 我的项目
colors:
  primary: "#2563EB"
  neutral: "#F8FAFC"
typography:
  body-md:
    fontFamily: Inter
    fontSize: 16px
---

## Overview

一个 B2B SaaS 后台。信息密度优先，不追求视觉花哨。
参考 Linear 和 Vercel Dashboard 的克制感。

CLI 三件套：lint / diff / export

不需要全局安装，直接 npx：

# 校验文件（9 条规则：token 引用、WCAG AA 对比度、缺 primary 等，能查出设计系统本身的逻辑问题）
npx @google/design.md lint DESIGN.md

# 对比两个版本，输出 token 级变更报告；新版多了 error/warning 时 exit code 非零
npx @google/design.md diff DESIGN.md DESIGN-v2.md

# 导出到其他格式（Tailwind v3 / v4 / W3C DTCG），DESIGN.md 当单一信源
npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

接入 AI 工作流

• 项目上下文：内容放进 CLAUDE.md / .cursorrules 或项目根目录，AI 每次会话自动读到。
• CI 集成：lint + diff 挂进流水线，设计系统变更自动检查，回归直接挂构建。

坑点

• 组件规范还在演进：目前只支持 backgroundColor、textColor、typography、rounded、padding、size 等基础属性，hover/focus 等交互状态得靠命名约定。
• token 命名无强制规范：自定义名字 AI 看不懂，prose 里必须解释。
• Windows 注意：包名 .md 后缀在 PowerShell 有冲突，用别名 designmd（npx -p @google/design.md designmd lint DESIGN.md）。
• Alpha 阶段：格式不保证向后兼容，生产环境锁定版本号。

一句话总结

DESIGN.md 不替代 Figma / Tailwind / DTCG，而是卡在中间位置：用最低成本（一个纯文本文件）让 AI 理解你的设计意图，再通过 export 同步到你实际的工具链。对「让 AI 写对风格」这个具体问题，它目前是最轻量的解法。