每天有无数开发者对着 AI 生成的图表叹气：圆角方块堆叠、配色刺眼、和自家网站风格完全不搭。cathrynlavery/diagram-design 就是冲着这个痛点来的。这个 GitHub 上日增 2855 star 的开源项目，把 27 种编辑级图表类型打包成一个 Claude Code 技能，让 AI 画出的架构图、流程图、序列图能直接用于正式场合。
它解决了什么问题
AI 画图的核心矛盾在于：模型能理解组件之间的关系，但输出结果缺少设计语言。常见的场景是，开发者让 Claude 画一个系统架构图，得到的是一堆灰色圆角矩形加几根连线，和精心设计的文档页面格格不入。
diagram-design 的作者 Cathryn Lavery（BestSelf.co 创始人）在 README 里描述了同样的痛点：每次需要图表时，要么花 30 分钟在 Figma 里手动调整，要么干脆跳过。这个项目的设计哲学可以归纳为一句话：一套强调色、每张图最多 1-2 个焦点元素、1px 细线边框、无阴影、所有坐标和间距必须能被 4 整除。这些约束让图表看起来像手工设计的编辑级排版，而不是 AI 自动生成的草稿。
27 种图表类型
项目内置 27 种可视化类型，每种都提供三种静态变体：极简浅色、极简深色、完整编辑版。所有输出都是自包含的 HTML+SVG 文件，双击即可在浏览器中打开，不依赖任何构建步骤、JavaScript 或外部图片。
核心类型包括：
| 类别 | 图表类型 |
|---|---|
| 结构图 | Architecture, Nested, Tree, Org Chart, Layers, Venn |
| 流程图 | Flowchart, Sequence, State Machine, Swimlane, Process |
| 数据图 | ER / Data Model, Data Flow, Medallion, Bar Chart, Line Chart, Scatter Plot |
| 分析图 | Quadrant, Consultant 2×2, Radar / Spider, Pyramid / Funnel |
| 时间图 | Timeline, Gantt |
| 系统图 | IT Current-State, High-Level, DP Integration, DP Security Matrix |
v2.0 新增了 Loop（循环飞轮）类型：围绕中心节点的多个站点，用虚线表示回写路径，适合表达反馈循环和飞轮效应。v2.3 引入了语义系统模式，把行为描述和布局分离——队列、策略追踪、信任边界等行为模式可以先匹配到最近的视觉类型，而不需要增加新的图表种类。
品牌自适应系统
diagram-design 不只是图表模板库。它的核心差异化能力是品牌自适应（onboarding）。用户只需说一句"onboard diagram-design to https://yoursite.com"，技能会自动执行以下流程：
- 抓取目标网站首页
- 提取主色调和字体栈
- 将检测到的值映射到语义角色（paper、ink、muted、accent、link）
- 展示变更差异供用户确认
- 写入
references/style-guide.md
之后所有新图表都会使用提取到的品牌色和字体。网站背景色变成图表底色，CTA 按钮色变成焦点强调色，正文字体族变成节点标签字体。
品牌匹配过程中还会自动执行 WCAG AA 对比度检查。如果检测到的颜色在图表字号（9-12px）下对比度不达标，技能会提出调整建议并说明原因。
| 网站检测项 | 语义角色 |
|---|---|
| `` 背景色 | paper |
| 主文本色 | ink |
| 次级/说明文本色 | muted |
| 卡片/容器色 | paper-2 |
| 最高频品牌色（CTA、链接、标题） | accent |
| `` 字体族 | title |
| `` 字体族 | node-name |
/ 字体族 | sublabel |
多平台支持
diagram-design 目前支持三个主流 AI 编码工具：
Claude Code 安装：
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design安装后需要在 /plugin 设置中手动启用自动更新。Claude Code 默认对第三方市场关闭自动更新，开启后会以后台方式刷新。
Codex 安装：
codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-designCodex 在启动时自动刷新已配置的 Git 市场。需要立即拉取可以运行 codex plugin marketplace upgrade diagram-design。
Pi 安装：
pi install https://github.com/cathrynlavery/diagram-designPi 没有自动包刷新机制，更新时需要手动运行 pi update --extensions。
对于需要深度定制的用户，项目支持 editable install：克隆仓库后在本地路径安装，修改 references/style-guide.md 不会被包更新覆盖。
draw.io 和 Mermaid 导入
已有 draw.io / diagrams.net 或 Mermaid 图表的项目可以直接迁移。diagram-design 会读取原始文件并重绘——保留组件、关系、分组和方向，丢弃原始坐标、配色和字体。
导入支持四个调节旋钮：
| 旋钮 | 选项 | 控制内容 |
|---|---|---|
| Format | html / svg / png / html+png | 输出格式。SVG 用于 Figma，PNG 用于幻灯片 |
| Size | doc-inline / doc-wide / slide-16x9 / slide-4x3 / social-og 等 | viewBox 尺寸和字号比例 |
| Detail | faithful (≤24 节点) / balanced (≤12) / simplified (≤7) | 节点保留程度 |
| Audience | engineer / mixed / executive | 标签措辞风格 |
Detail 旋钮通过固定的降级阶梯工作：先去掉装饰元素，再合并重复节点，然后折叠叶节点簇，最后移除基础设施节点。每次导入结束时会输出一份保真度报告（fidelity ledger），列出哪些节点被合并、折叠或删除。
例如从 12 节点的 draw.io 文件导入时，balanced 模式输出 8 个节点，报告会注明"Token valid? 决策框已合并为 Gateway 到 Auth 的边标签"和"1 个便签（旧路径，待退役）因未连接而被删除"。
设计系统细节
整个项目遵循一套严格的设计规范：
色彩：默认使用 jet-black（墨黑）+ atomic-tangerine（原子橘）配色方案。white-smoke 作纸面，jet-black 作墨水，atomic-tangerine 作强调色，blue-slate 作弱化色，silver 作发丝线。
字体：三套字体族。Instrument Serif 用于标题和斜体标注，Geist sans 用于节点名称，Geist Mono 用于技术子标签（端口号、URL、字段类型）。Mono 字体仅用于技术内容，不是泛泛的"开发者审美"。
几何约束：所有坐标、宽度和间距必须能被 4 整除。最大圆角 10px。1px 发丝线边框，无阴影。珊瑚色调的焦点节点用于吸引视线到最重要的 1-2 个元素。
设计密度目标：4/10。每个节点都必须为它的存在负责。作者的设计理念是"最高质量的操作通常是删除"。
架构与渐进式加载
项目采用渐进式架构（progressive disclosure）。技能在启动时只加载名称和描述。当请求匹配时加载 SKILL.md，语义、类型和动画引用只在需要时才拉取。
| 请求类型 | 加载的资源 |
|---|---|
| "画一个流程图" | SKILL.md + type-flowchart.md |
| "构建架构图" | SKILL.md + type-architecture.md |
| "比较两个策略请求的差异" | SKILL.md + semantic-patterns.md + type-flowchart.md |
| "给这个策略追踪加动画" | 上述 + animation.md |
| "把这个技能适配到我的网站" | SKILL.md + onboarding.md + style-guide.md |
这种设计保证了无论有多少种图表类型，Agent 只需要读取用户当前需要的那一个类型引用文件。添加新类型不会影响其他部分。
语义模式系统
v2.3 引入的语义模式系统是项目架构上的重要设计决策。它把行为描述和视觉布局完全分离，定义了七种路由模式：
- Fan-in 队列和瓶颈：多输入汇聚到单处理单元
- 重复阶段插槽：流水线式连续处理
- 非结构化输入转换：杂乱数据清洗管线
- 配对策略追踪：两个请求路径对比
- 安全铺装路径：治理和合规流程
- 治理目录：资产盘点和权限矩阵
- 补偿性安全层：纵深防御架构
每种模式定义了触发条件、基础原语、预算约束、反模式、静态回退和最近的视觉类型。当用户描述的是行为而非布局时（如"画一个队列"、"做一个信任边界图"），技能会先匹配语义模式，再选择最合适的视觉类型。语义模式不会增加视觉类型的数量——七种模式映射到已有的 27 种类型。
动画与无障碍
动画是可选功能，不会创建新的视觉类型。项目定义了四种动画模式：
- none（默认）：静态输出，无脚本
- reveal：逐步显示
- step：按帧步进
- loop：循环播放
所有动画都基于一个经过审查的控制器模板（template-motion.html）。系统会拒绝任意的内联脚本、远程资源、CSS 导入和可执行 HTML 属性。prefers-reduced-motion 设置下显示完整的静态首帧，隐藏播放控件。
无障碍方面，每个图表模板的 SVG 都包含 role="img"、aria-labelledby 和首子级 / 槽位。ID 按图表和变体前缀化，确保多个 SVG 可以安全内联在同一页面中而不会产生重复的无障碍名称 ID。装饰性图标对辅助技术隐藏。
导出与集成
图表以自包含 HTML 输出，但可以导出为 PNG 或 SVG：
- SVG：提取 `` 节点并注入 Google Fonts，确保在 Figma、Illustrator 和浏览器中独立渲染
- PNG：通过 Playwright 以 2× 分辨率光栅化（需一次性安装
playwright install chromium）
两种格式都只导出图表本身，不含编辑卡和页眉。全页截图需要用浏览器的打印 PDF 或整页截图功能。
项目质量保障
项目维护了一套严格的 CI 验证体系。所有 Pull Request 和推送通过 GitHub Actions 在 Linux、Windows 和 macOS 三个平台上验证：
- 皮肤 lint（
lint-skin.py）确保所有示例和模板风格一致 - 语义路由验证（
verify-semantic-motion.py） - 动画模板结构验证（
verify-motion.py） - draw.io 导入路径验证（
verify-drawio-import.py） - Mermaid 导入路径验证（
verify-mermaid-import.py） - 几何标签放置验证（
verify-geometry.py）防止标签遮盖后被遮挡 - 文档同步验证（
verify-docs-sync.py）确保 SKILL.md、gallery 和 README 文件树一致
安装后的 Agent 可以运行 skills/diagram-design/scripts/self_check.py 对生成的图表进行自检。设计决策以 ADR（架构决策记录）形式记录在 docs/adr/ 目录中。
总结
diagram-design 代表了 AI 编码工具生态中一个有意思的方向：让 AI 在特定垂直领域做到专业级输出，而非泛泛覆盖更多功能。27 种图表类型覆盖了开发文档、架构评审、产品演示中绝大多数可视化需求。品牌自适应系统解决了 AI 输出和团队设计语言不一致的问题。draw.io / Mermaid 导入管线降低了已有项目的迁移成本。渐进式架构确保技能不会随类型增加而膨胀。
项目在 GitHub 上日增近 3000 star 的爆发增长，反映出开发者对"让 AI 画出能用图表"这个需求确实存在。对于使用 Claude Code、Codex 或 Pi 的团队，这个技能值得加入工作流。