DESIGN.md：把设计系统写进代码仓库，让代理按规范出活

代理看不懂设计稿，所以需要一个仓库内的规范文件

编码代理能写代码，但经常搞不清楚按钮该用几号字、圆角该是 4px 还是 8px。把设计系统塞进 prompt 里，既占 token 又难维护。DESIGN.md 的做法是把视觉身份写成一个文件，放在仓库根目录，让代理每次生成界面时都能读到。它服务的对象是那些用 AI 生成前端代码的团队，尤其是设计系统还没有完整组件库、但希望输出保持一致性的项目。文件里同时包含机器可读的令牌和人类可读的解释，前者给代理精确数值，后者告诉代理这些数值为什么存在。

YAML 令牌加 Markdown 理由，两层结构各司其职

DESIGN.md 的文件结构分两层。顶部是 YAML front matter，用 `---` 分隔，定义颜色、字体、圆角、间距和组件令牌。下面是 Markdown 正文，用 `##` 章节写设计理由。令牌是规范性的，散文是解释性的。比如颜色令牌 `colors.primary` 定义成 `#1A1C1E`，正文里再解释这是深墨色标题，用于营造高级报纸感。代理读令牌拿数值，读散文拿上下文。这种分层让同一份文件既能被程序解析，又能被人类审阅。令牌类型支持 CSS 颜色、带单位的尺寸、以及用 `{path.to.token}` 形式的引用，组件可以引用颜色令牌，比如 `backgroundColor: "{colors.tertiary}"`。

章节顺序有硬性规定，但未知内容不报错

规范要求 Markdown 章节按固定顺序出现：Overview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do's and Don'ts。可以省略章节，但出现的必须按这个顺序。这个限制保证了代理解析时不会迷路。不过规范对未知内容采取宽容策略：未知的章节标题保留但不报错，未知的颜色令牌只要值合法就接受，未知的组件属性只给警告。唯一硬性错误是重复的章节标题，遇到就直接拒绝文件。这种设计有意区分了致命错误和可容忍的偏差，让代理在遇到新内容时不至于崩溃，同时又防止结构混乱。

lint 和 diff 两条命令，把设计审查变成结构化 JSON

CLI 提供两个主要命令。`lint` 校验 DESIGN.md 是否符合规范，检查令牌引用是否断裂，计算 WCAG 对比度，然后输出结构化 JSON。输出里包含 findings 数组，每条有 severity、path 和 message，比如警告某个按钮的文字颜色和背景色对比度是 15.42:1，通过 AA。`diff` 比较两个版本的设计系统，检测令牌级别的增删改，以及散文层面的回归。diff 输出里 `regression` 字段直接告诉你是否出现倒退。两条命令都接受文件路径或 `-` 表示 stdin，默认输出 JSON。这意味着你可以把 lint 接入 CI，把 diff 接进代码审查流程，让设计变更像代码变更一样被检查。

Windows 上的坑：bin 名带 .md 后缀会撞上文件关联

CLI 的 bin 名是 `design.md`，在 Windows 上这个后缀会触发 Markdown 文件关联，导致 npx 直接运行时可能没有输出，或者意外打开编辑器。README 明确警告了这个问题，并给出两个解决办法：要么在 npm install 时给包名加引号，要么用 `designmd` 别名。`designmd` 是同一个入口的另一个名字，在 package.json 脚本里调用时应该用它。另一个常见问题是 `ENOVERSIONS` 错误，这通常不是包本身的问题，而是 npm 没在查公共 registry，比如自定义 registry 或公司镜像没同步。检查 `npm config get registry`，正常应该是 `https://registry.npmjs.org/`。这些坑说明这个项目在跨平台兼容上还有粗糙之处，但至少文档给出了明确绕法。

组件变体靠命名约定，不是靠状态字段

组件令牌用 YAML 对象定义，比如 `button-primary` 有 backgroundColor、textColor、rounded、padding。有效的组件属性只有八个：backgroundColor、textColor、typography、rounded、padding、size、height、width。变体（hover、active、pressed）不是用状态字段表达，而是拆成独立的组件条目，比如 `button-primary-hover`。这种设计简单直接，但代价是变体之间的关系只能靠命名约定维持，规范没有机制保证 `button-primary-hover` 一定跟 `button-primary` 关联。如果团队命名不规范，diff 输出会变得混乱。另外，令牌引用只在组件属性里出现，颜色和排版令牌本身不支持引用其他令牌，这限制了令牌复用的灵活性。

对比 AGENTS.md 和纯设计令牌文件，它把理由和数值绑在一起

市面上已有 AGENTS.md 这类文件，给代理写项目说明，但通常以自然语言为主，没有结构化令牌。也有纯设计令牌方案，比如 Style Dictionary，用 JSON 定义令牌，但缺少设计理由的散文层。DESIGN.md 的独特之处是把两者合并：YAML 提供精确数值，Markdown 提供上下文。相比 Style Dictionary，它不生成跨平台代码，只提供规范和校验工具。相比 AGENTS.md，它强制要求令牌结构，代理可以直接读取数值而不必解析自然语言。这种折中意味着它不适合需要把令牌编译成 iOS 或 Android 资源的场景，那个需求应该用 Style Dictionary。它更适合代理直接消费的、仓库内的单一事实来源。

维护成本与升级风险：alpha 版本，结构可能变

当前版本是 0.4.0，schema 里 `version` 字段标注为 `alpha`，说明格式还没稳定。最近的发布节奏是每月一个版本，0.2.0 到 0.3.0 间隔三周，0.3.0 到 0.4.0 间隔六周。这意味着令牌结构可能随版本变化，升级时需要跑 `diff` 检查回归。维护成本包括：设计系统每次变更都要更新 DESIGN.md，并在 CI 里跑 lint 保证规范有效。好消息是 lint 会捕获断裂的令牌引用和对比度问题，减少人工审查。许可证是 Apache-2.0，允许商用和修改，没有 copyleft 义务。但格式本身还在演化，如果团队长期使用，需要跟踪每个版本的 spec 变更。

编辑结论

适合采用 DESIGN.md 的团队是那些已经依赖编码代理生成 UI，并且希望把设计决策固化到仓库里的项目。它把令牌和理由放在同一文件，代理不用猜测颜色值或圆角来源。不适合的团队是设计系统尚未稳定、频繁推翻令牌定义的团队，因为 diff 命令会把每次改动都变成噪音。另一个不适合场景是代理工具链不支持读取该格式，单纯加一个文件不会改变代理行为。采用前要验证三件事：你的代理是否真的读取并遵循 DESIGN.md，你的 CI 是否愿意为每次提交运行 lint，以及你的 Windows 开发者是否准备用 designmd 别名绕开文件名冲突。许可证是 Apache-2.0，商用没有额外限制，但格式本身仍处于 alpha 版本，令牌结构可能变化，升级时需检查 diff 输出。

官方来源

1. Official documentation
2. Official README
3. Project repository
4. Release notes