Monorepo中管理多个DESIGN.md：多设计系统并行的完整指南

Monorepo中管理多个DESIGN.md：多设计系统并行的完整指南

【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md

为什么需要在 Monorepo 中管理多套设计系统 🎯

DESIGN.md是一种面向编码代理（Coding Agent）的视觉身份描述格式：它把机器可读的设计 Token（YAML frontmatter）与人类可读的设计说明（Markdown 正文）写在同一个文件里，让 AI 代理对设计系统形成持久、结构化的理解。当一个组织同时维护品牌官网、电商 App、内部后台等多条产品线时，"一套仓库、多套 DESIGN.md" 就成为必然选择——而 Monorepo 正是承载多设计系统并行的理想工程结构。

1. 项目结构速览：设计系统即工作区

本项目本身就是一个 Monorepo 范例：根目录通过 npm workspaces 管理子包，官方示例目录 examples/ 下就并排放置了三套风格迥异的设计系统：

每一套都包含三个产物：DESIGN.md（源文件）、tailwind.config.js（Tailwind v3 主题导出）、design_tokens.json（DTCG 标准 JSON 导出）。这正是多设计系统并行时推荐的文件三件套。

2. 推荐目录布局：一个产品线一个文件夹

Monorepo 中并行多套 DESIGN.md 的黄金法则是按产品线隔离、按 Token 共享：

monorepo/ ├── package.json # workspaces 声明 ├── turbo.json # 任务编排 └── products/ ├── shop/ │ └── DESIGN.md # 电商设计系统 ├── admin/ │ └── DESIGN.md # 内部后台设计系统 └── shared-tokens/ # 跨系统共享的基座 Token（可选）

这样做的好处：

• 边界清晰：每套设计系统自带 Token 与说明文字，代理生成 UI 时不会串味
• 独立演进：产品线 A 改版不影响产品线 B，diff回归检测可按目录单独运行
• 复用有度：共享品牌色、字体族可抽成共享 Token 包，被各产品 DESIGN.md 引用

3. 统一校验：一条命令守住全部设计系统 ✅

多套设计系统最怕"静默腐化"。官方 CLI 提供lint命令，可对每个 DESIGN.md 执行 11 条规则检查（结构完整性、Token 引用是否断裂、WCAG 对比度、孤悬 Token 等），规则清单见 README.md 的 Linting Rules 一节，规格全文见 docs/spec.md。

推荐在 Monorepo 根目录用脚本遍历所有产品目录：

for f in products/*/DESIGN.md; do npx @google/design.md lint "$f" done

CLI 支持文件路径或-（stdin），输出结构化 JSON，发现 error 时退出码为 1——天然适合接入 CI 流水线作为质量门禁。

4. diff 回归检测：设计系统的"单元测试"

每次改动 DESIGN.md 后，用diff命令对比新旧两个版本，可以精确得到 Token 级别的增删改清单，以及 lint 发现的回归（regression 字段为true时退出码为 1）。在多设计系统并行场景下，建议为每套系统保留上一版快照，PR 中自动 diff，一眼看出"改动了哪些 Token、新增了几条警告"。

diff 的实现位于 packages/cli/src/commands/diff.ts，可直接参考其输出结构。

5. 导出与消费：一份 DESIGN.md，多端落地

export命令把 Token 一键转成三种下游格式：

多设计系统并行时，每个产品目录各自export，产物直接喂给各自的 Tailwind 配置——这正是 examples/totality-festival/ 目录中tailwind.config.js与design_tokens.json的生成方式（详见其 README）。

6. 用 Turbo 编排并行任务（可选进阶）

本仓库根 package.json 使用 npm workspaces +bun作为包管理器，turbo.json 中声明了build、test、lint三类任务并配置了dependsOn依赖关系。你可以照抄这套模式：在根目录写一个design:lint脚本，用 Turbo 并发跑所有产品目录的检查，改动哪个产品就只重跑哪个。

7. 避坑清单 📌

• 命名规范：每个 DESIGN.md 的 frontmatter 里name字段必须全局唯一，避免代理混淆上下文
• 不要合并多产品 Token：强行把两套系统的颜色塞进一个文件，会让orphaned-tokens警告泛滥
• 共享 Token 用引用：跨文件复用建议通过{path.to.token}引用语法而非复制粘贴
• CI 必跑 lint：missing-primary、broken-ref这类问题在生成 UI 前发现，成本最低
• 版本对齐：CLI 当前格式版本为alpha（见 docs/spec.md），升级 CLI 后建议全量 diff 一遍所有产品目录

小结

在 Monorepo 中并行管理多个 DESIGN.md 的核心思路是：目录按产品隔离、校验用 lint 门禁、变更用 diff 回归、落地用 export 多格式分发。配合官方 CLI 的 JSON 输出与退出码语义，整套流程可以完全自动化——多设计系统不再是维护负担，而是结构清晰的工程资产。

【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md