适合谁

设计系统：适合把设计规范沉淀成 Agent 可读规则和 DESIGN.md。

Codex 用法

优先按具体技能或原项目安装方式使用，不建议把归档目录整包复制。

可复制设计规范思路到项目根目录，但不要盲目覆盖现有设计系统。

许可证 / 风险

设计规则可参考，品牌与字体资产需单独核对授权。

DESIGN.md

让 AI 理解设计系统的"语言"

Google 出品的 AI 编码代理设计系统格式规范。结合机器可读的设计 Token（YAML）和人类可读的设计理念（Markdown），让 AI 生成代码时遵循统一的设计规范。

$ npx @google/design.md lint DESIGN.md

📐 分层架构

📝 Markdown 正文 - 人类可读的设计理念

设计决策的"为什么"：为什么选择这个颜色？为什么用这种字体？帮助 AI 理解设计意图，在新场景中做出合理推断。

## Overview - 设计理念概述
## Colors - 颜色含义解释
## Typography - 字体选择理由

↓

🏷️ Component Tokens - 组件级设计 Token

具体组件的样式定义：按钮、卡片、输入框等组件的属性。

button-primary: backgroundColor, textColor, rounded
card: padding, shadow, borderRadius
input: height, borderColor, focusRing

↓

🎨 Foundation Tokens - 基础设计 Token

最底层的原子化设计变量，其他 Token 的引用来源。

colors: primary, secondary, tertiary, neutral...
typography: h1, body-md, label-caps...
rounded: sm, md, lg
spacing: sm, md, lg

↓

📄 YAML Front Matter - 机器可读的结构化数据

文件的头部区域，包含所有设计 Token 的精确值。AI 可以直接解析使用。

name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem

⚡ 核心功能

🔗 Token 引用机制

组件可以使用 {colors.primary} 引用其他 Token，修改一处即可全局更新，确保设计一致性。

✅ WCAG 对比度检查

自动检测文本与背景的对比度是否满足 AA 标准（4.5:1），防止无障碍问题。

🔍 Token 引用验证

检测断开的引用，如 {colors.primary} 不存在时报错。

📊 设计回归检测

diff 命令可以比较两个版本的设计系统，检测添加/删除/修改的 Token，防止意外设计回归。

📤 多格式导出

支持导出为 Tailwind 主题配置、DTCG tokens.json 等格式，与现有工具链集成。

🧩 程序化 API

提供 TypeScript API，可集成到构建流程、CI/CD 管道中自动检查设计规范。

🛠️ CLI 工具箱

lint

免费

npx @google/design.md lint DESIGN.md

验证设计文件的结构正确性、Token 引用、WCAG 对比度，输出结构化 JSON 报告。

diff

免费

npx @google/design.md diff v1.md v2.md

比较两个设计系统的 Token 级变化，检测设计回归。

export

免费

npx @google/design.md export --format tailwind

将 DESIGN.md 导出为 Tailwind 主题配置或 DTCG tokens.json。

spec

免费

npx @google/design.md spec --rules

输出 DESIGN.md 格式规范，可选包含 linting 规则表，便于注入到 Agent Prompt。

💬 聊天比喻场景

🤖

用户想要一个蓝色的按钮。请帮我生成代码。

👤

好的，我需要先查看项目的 DESIGN.md 文件来了解设计规范...

📄

找到了！设计系统中定义：
• primary 颜色是 #4285f4
• button-primary 组件使用 {colors.primary} 作为背景色
• 圆角使用 {rounded.md} = 8px
• 文字颜色使用 {colors.on-primary} = 白色

🤖

明白了！我会使用蓝色背景、白色文字、8px 圆角的按钮，并且遵循设计系统中的间距规范。

📖 大白话解释

什么是 Design Token？

想象你有一套乐高玩具，Design Token 就是乐高的基础砖块规格：红色砖块、多大尺寸、什么形状。定义一次，所有地方都能用，修改一个地方，全部跟着变。

为什么要分两层？

YAML 部分像"配方"，机器可以直接读取；Markdown 部分像"说明书"，告诉 AI 为什么这么设计。这样 AI 既知道"怎么做"，也理解"为什么"。

Token 引用是什么意思？

就像 Excel 公式 =A1 引用另一个单元格一样，{colors.primary} 引用的是"主色"这个变量。哪天主色从蓝色改成红色，所有用到这个引用的按钮、卡片都会自动变。

WCAG 对比度是什么？

就是检查文字够不够明显、能不能看得清。WCAG 规定文字和背景的对比度至少要 4.5:1，这样视力不好的人或者在阳光下看手机的人也能看清内容。DESIGN.md 会自动帮你检查。