本周 GitHub 第一！diagram-design：让 AI 画出设计师都挑不出毛病的图表

一、它是什么？

diagram-design 是一个给 Claude Code / Codex / Pi 等 AI 编码助手用的图表设计技能包（Agent Skill）。

一句话：你让 AI 画架构图、流程图，它不再吐给你"千篇一律的圆角方框 + Mermaid 丑图"，而是输出编辑级排版质量的 HTML + SVG——自带三种风格（浅色、深色、全编辑风），浏览器直接打开，没有构建步骤、没有 JS 依赖、没有外部图片。

README 里作者 Cathryn Lavery（BestSelf.co 创始人，技术博主 littlemight.com）的原话很直白：

"No Figma. No generic rounded boxes. No 30-minute color-picking sessions." （不用 Figma，不要通用圆角框，不用再花 30 分钟调色。）

她在 README 里讲了真实的痛点：每次写技术文章需要架构图、流程图或金字塔图，让 Claude 画出来的都是"和网站风格完全不搭的通用圆角框"，要么自己和 Figma 搏斗半小时，要么干脆不画。于是她做了这个 skill。

二、27 种图表类型全览

覆盖了技术文档里几乎所有常用图，每种都有 3 个静态变体（minimal light / minimal dark / full-editorial）：

最新版本亮点：

• 2.0 新增 Loop：带共享记忆中心的飞轮图，虚线表示回写

• 2.3 新增语义系统模式 + 可选无障碍动效（默认仍是静态输出）

三、核心设计理念

作者在 README 里写了一套清晰的设计哲学，这也是它比 Mermaid 好看的根本原因：

The highest-quality move is usually deletion. Every node earns its place. The accent color is reserved for the 1–2 things the reader should look at first. Target density: 4/10.

翻译过来：

1. 克制：每个节点都要争取存在的资格，最高质量的操作通常是"删掉"

2. 强调色只给 1-2 个焦点：读者第一眼该看的地方才用珊瑚色

3. 目标密度 4/10：不堆砌

4. 设计系统统一：1px 发丝边框、无阴影、最大圆角 10px、所有坐标/宽度/间距必须能被 4 整除（这是它不像 AI 生成的关键）

5. 三套字体：Instrument Serif（标题+斜体标注）、Geist sans（节点名）、Geist Mono（技术子标签）

6. 等宽字体只用在技术内容（端口、URL、字段类型），不滥用成"开发者美学"

四、怎么安装和使用？

4.1 在 Claude Code 里安装

/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

装完后开启一次自动更新：运行 /plugin → Marketplaces → 选 diagram-design → Enable auto-update（Claude Code 对第三方市场默认关闭自动更新）。按提示运行 /reload-plugins。

4.2 在 Codex 里安装

codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-design

Codex 启动时刷新 Git 市场；想立即更新运行 codex plugin marketplace upgrade diagram-design。

4.3 在 Pi 里安装

pi install https://github.com/cathrynlavery/diagram-design

在打开的 Pi 会话里运行 /reload。用 /skill:diagram-design 显式调用。

4.4 实际用法

装好后，直接用自然语言让 AI 画图：

• "画一个微服务网关的架构图：frontend、backend、database、Redis cache"

• "用四象限展示 Q2 项目按影响力 vs 工作量分布"

• "画一个带 401 token 刷新的 bearer 调用时序图"

• "把这个 drawio 文件重绘成适合演讲的深色风格"

AI 会自动选图类型、构建 HTML、保存文件。

4.5 从模板直接开始

cp skills/diagram-design/assets/template.html my-diagram.html        # 极简浅色
cp skills/diagram-design/assets/template-full.html my-diagram.html   # 编辑风（带摘要卡）
cp skills/diagram-design/assets/template-motion.html my-diagram.html # 可选无障碍动效

五、杀手级功能：品牌匹配（60 秒让图变成你的风格）

这是最实用的功能——让 skill 读取你的网站，自动提取品牌色和字体：

你：     "onboard diagram-design to https://yoursite.com"
Agent：  → 抓取首页
         → 提取主色调 + 字体栈
         → 映射到语义角色：paper(背景)、ink(文字)、muted(次要)、accent(强调)、link(链接)
         → 展示拟修改的 diff
         → 写入 references/style-guide.md
你：     "yes, apply it"

之后每张新图都用你的品牌色。具体的映射规则：

还会自动做 WCAG AA 对比度检查：如果你网站的颜色在图表字号（9-12px）下对比度不达标，它会提议一个调整值并解释原因。

多客户管理：品牌可以存成命名 profile，每个客户项目加一个 .diagram-design 标记文件写 profile: <slug>，不同项目用不同品牌，互不覆盖。

六、杀手级功能：从 draw.io / Mermaid 重绘

已经有 draw.io 或 Mermaid 图？它能重绘成这套设计系统：

/diagram-design:import-drawio platform.drawio
/diagram-design:import-drawio platform.drawio --size=slide-16x9 --detail=simplified --audience=executive
/diagram-design:import-mermaid architecture.mmd --size=slide-16x9

四个调节旋钮（The four dials）

同一个源文件，可以输出完全不同的图：

每次导入结束会输出保真台账（fidelity ledger），明确告诉你合并了什么、折叠了什么、丢弃了什么：

Detail: balanced · 12 source nodes → 8 drawn
Collapsed: "Token valid?" decision → edge label on Gateway → Auth
Dropped:   1 sticky note ("legacy path, to be retired") — unconnected in source
Kept in full: the request path (Web/Mobile → Gateway → Orders → Postgres)

支持读取 .drawio、.drawio.xml、.drawio.png（内嵌图）、.drawio.svg，包括编辑器里看着像 base64 乱码的压缩内容。Mermaid 支持 .mmd、.mermaid 和 Markdown 里的 fenced 代码块。

七、导出 PNG / SVG

# Pi
/export-diagram path/to/diagram.html
/export-diagram path/to/diagram.html --svg-only
/export-diagram path/to/diagram.html --png-only --scale=3
​
# Claude Code
/diagram-design:export-diagram path/to/diagram.html

• SVG：提取 <svg> 节点，注入 Google Fonts，可独立在浏览器/Figma/Illustrator 打开

• PNG：通过 Playwright 光栅化，默认 2×；一次性安装：pip install playwright && playwright install chromium

八、架构：按需加载，不撑爆上下文

skill 的目录结构经过精心设计，采用渐进式披露：

skills/diagram-design/
├── SKILL.md                  # 哲学、选型指南、清单（启动时只加载这个）
├── references/               # 只有选了某类型才加载
│   ├── style-guide.md        # 颜色+字体的唯一真相源
│   ├── semantic-patterns.md  # 行为模式（与布局分离）
│   ├── animation.md          # 可选动效契约
│   ├── type-architecture.md  # 27 种类型各一个文件
│   ├── type-flowchart.md
│   ├── ...（每个类型一个 md）
│   ├── import-drawio.md
│   └── output-spec.md
├── scripts/
│   ├── drawio_extract.py     # drawio → 结构化 IR
│   ├── mermaid_extract.py    # Mermaid → 结构化 IR
│   └── self_check.py         # 输出自检
└── assets/
    ├── index.html            # 在线画廊（可切换浅/深/编辑风）
    ├── example-<type>.html   # 27 类型 × 3 变体
    └── template*.html        # 脚手架

加载时机表：

无论有多少种类型，Agent 只读你需要的那一个。这种设计让 27 种图的 skill 不会撑爆上下文窗口。

九、质量保障：CI 比代码库还严格

这个项目让我意外的是它的质量门禁体系，完全是生产级：

• lint-skin.py --all --baseline：所有示例和模板的皮肤检查必须全绿

• verify-semantic-motion.py --markdown-only：语义路由验证

• verify-motion.py --shipped：每个动效模板结构检查

• verify-geometry.py --all：几何标签放置检查——标签遮挡后续节点会导致 CI 失败（因为节点填充会在渲染时裁切文字）

• verify-docs-sync.py：文档与路由同步检查（SKILL.md 不能丢类型词、画廊必须能到达每个示例、链接不能断）

• self_check.py：安装到用户机器上后，Agent 可以对自己生成的图跑自检

• CI 在 Linux、Windows、macOS 上跨平台运行

• 安全门禁：动效 HTML 只允许经过审查的控制器，拒绝远程资源、CSS @import、非 fragment CSS url()、onclick/srcdoc 等可执行属性

设计决策记录在 docs/adr/（Architecture Decision Records），包括"为什么固定一个控制器""为什么模式不增加类型数量""自动播放策略"等。

十、优点总结

1. 质量是真的高：编辑级排版，不是 Mermaid 那种工程师审美

2. 零依赖：纯 HTML + SVG，无 JS、无构建、无外部图片，双击即开

3. 三风格内置：浅色/深色/全编辑风一键切换

4. 品牌匹配 60 秒：读网站自动提取配色字体，还做对比度检查

5. 语义与布局分离：队列、策略追踪、信任边界等行为模式可复用最近的图类型

6. draw.io/Mermaid 重绘：四个旋钮精确控制输出，带保真台账

7. 多 Agent 支持：Claude Code、Codex、Pi 都能装

8. 无障碍：每个 SVG 有 role="img"、aria-labelledby、<title>/<desc>；支持 prefers-reduced-motion

9. 55 个单色 IT/云图标：笔记本、手机、服务器、数据库、Docker、K8s、AWS、Azure、GitHub、Postgres 等

10. 按需加载架构不撑爆上下文

十一、什么时候不该用？

README 很诚实地列了"不适用场景"：

• 快速 unicode 图表（发推/终端输出）→ 用 wiretext 风格的 skill

• 任何东西的列表 → 用表格或列表

• 前后对比 → 用表格

• 单形状"图表"（一个框加个标签）→ 直接写句子

画图前先问：读者从这张图学到的，比从一段写得好的话多吗？ 如果不多，就别画。

十二、为什么这么火？

• 踩中真实痛点：每个用 AI 写技术文档的人都受过"Mermaid 丑图/圆角方框烂大街"的苦

• 即装即用零学习成本：一行命令装上，立刻提升 AI 输出质量

• 作者会讲故事：README 真诚讲了自己和 Figma 搏斗 30 分钟的经历，容易共鸣

• 作品即广告：生成的图本身就是最好的传播素材

• 站在 Agent Skills 风口：Anthropic 官方 skills 仓库 17 万星，整个生态在爆发

• 工程完成度惊人：CI、自检、ADR、跨平台测试，不像个人玩具

附：官方资源

• GitHub：GitHub - cathrynlavery/diagram-design: 27 editorial diagram types for Claude Code. Self-contained HTML + SVG. No shadows, no Mermaid-slop. · GitHub

• 在线画廊：Diagram Design · Gallery

• 作者博客：https://littlemight.com

• 作者公司：https://bestself.co