diagram-design：29 种编辑级图表技能，让 Claude Code 直接吐出 "杂志风" 架构图

发表于 分类于 ，
当日增 1.6k stars 的 diagram-design 是一套专为 Claude Code 设计的"编辑级"图表技能集合，29 种图表类型全部以自包含 HTML + SVG 输出，硬性约束无阴影、4 像素栅格、统一字体搭配，把 AI 生成的"Mermaid 风"架构图直接拉高到杂志栏目级别。

你有没有过这种体验：让 Claude Code 帮忙画一张” 用户登录流程” 的时序图，出来的图长这样 ——

圆角矩形、蓝灰阴影、Helvetica 同款系统字、节点间距乱七八糟、箭头穿过文本框、配色一股”PPT 模板 2019” 的味儿。然后你跟模型说” 画得高级一点”，它再吐一版，又回到了那个圆角矩形。

问题不在 Claude，也不在 Mermaid。Mermaid 本身是个伟大的工具，但它的语法决定了：LLM 只能产出” 能跑就行” 的工程图，离” 可以直接放进博客头图” 的视觉水准差了十万八千里。

今天 GitHub Trending 榜首的 cathrynlavery/diagram-design 就是来解决这个问题的。它不是另一个图表渲染器，而是一套专门喂给 Claude Code 的” 图表设计技能”——29 种编辑级图表类型，全部以自包含 HTML + SVG 输出，硬性约束设计规范，让 AI 直接吐出能上杂志的架构图。

项目背景：AI 画图的” 审美天花板” 问题

过去两年，AI Coding Agent 已经把” 读代码、写代码、跑测试、改 bug” 这些活儿卷到了极致。但一旦涉及到” 画一张图”，绝大多数 Agent 还是会直接吐出 Mermaid/PlantUML 的渲染结果 —— 能用，但不好看。

更深层的问题有三：

1. 渲染语法限制了审美空间。 Mermaid 的 graph TD、sequenceDiagram、erDiagram 这些语法非常适合 LLM 写出” 对的图”，但要让 LLM 同时控制字距、阴影方向、强调色、留白比例，几乎不可能。语法里就没有这些旋钮。

2. 缺乏统一的设计系统。 即便给 LLM 一段” 用 editorial style” 的 prompt，它每次产出的” 高级感” 都是不同的。颜色随机、字体不一致、间距凭感觉。

3. 输出格式不可二次编辑。 Mermaid 渲染出来就是 PNG/SVG，但这些 SVG 里所有节点都是硬编码的 path，想手动改一行字都得重新生成。

diagram-design 的解题思路是：别让 LLM 写 Mermaid，让它写 HTML。 把每个图表类型拆成一个独立 skill（技能），每个 skill 都内置一套硬性设计规范（design constraints），LLM 只负责” 组合 + 填内容”，风格部分被规范锁死。

核心功能：29 种图表 + 硬性设计规范

29 种图表类型

项目里把” 编辑级图表” 分成三大类：

  • 结构类：Architecture（架构）、Flowchart（流程）、Sequence（时序）、State machine（状态机）、ER（数据模型）、Org chart（组织）、Tree（树形）、Nested（嵌套层级）。
  • 定位 / 分析类：Quadrant（两轴定位）、Consultant 2×2（场景矩阵）、Radar/Spider（多轴雷达）、Venn（韦恩图）、Swimlane（跨职能泳道）。
  • 叙事类：Timeline（时间轴）、Pyramid/Funnel（金字塔 / 漏斗）、Layers（层叠抽象）、Loop（飞轮）、IT current-state（IT 现代化现状图）。

每种图表都对应一个独立的 references/primitive-xxx.md 文件，里面写死了布局算法、节点尺寸、连线样式、标注规则。

硬性设计规范

这是这个项目最值钱的地方。它把” 什么算好看” 翻译成了一组可执行的硬性约束：

  • 一个强调色：每个图只有 1 种 accent color，所有焦点元素都用它。
  • 1–2 个焦点元素：超过就稀释注意力。
  • 三种字体：Instrument Serif（标题 + 斜体批注）、Geist Sans（节点名）、Geist Mono（技术子标签，如端口号、URL、字段类型）。
  • 1px 发丝边框：所有边框都是 1 像素。
  • 无阴影：彻底禁用 drop-shadow、box-shadow。
  • 最大圆角 10px：避免” 儿童画风”。
  • 4 像素栅格：每个坐标、宽度、间距都必须能被 4 整除 —— 这是它原话：”non-negotiable, it’s what keeps the diagrams from feeling AI-generated.”

这最后一条尤其重要。4 像素栅格是出版行业的硬规矩。AI 生成的图之所以一眼假，就是因为坐标都是奇数位、间距都是 3px、7px 这种凭感觉的数。强制 4 像素栅格之后，整个图会立刻显得” 被人设计过”。

自包含 HTML 输出

每张图都是一个单文件 HTML——HTML 里嵌了 CSS、SVG、所有数据。意味着：

  • 直接双击在浏览器里打开就能看
  • 可以塞进博客、文章、Notion、Confluence
  • 可以导出为独立 SVG（提取 <svg> 节点，注入 Google Fonts），用于 Figma、Illustrator
  • 可以用 Playwright 栅格化为 PNG（默认 2× 分辨率）

没有任何外部依赖，没有 CDN 引用，没有 build step。

标注（Annotation）系统

每张图都可以叠加斜体 Instrument Serif 的批注 + 虚线 Bézier 引导线，模拟杂志栏目的” 旁注” 效果。这个能力来自 primitive-annotation.md 技能包。技术文档里加这种批注，可读性会比单纯的方框图高一档。

Sketchy 滤镜

项目还内置了一个 SVG turbulence + displacement map 的手绘滤镜（primitive-sketchy.md）。让原本严谨的工程图瞬间变成” 手绘风”。项目原话：”Good for essays, not for technical docs.” —— 适合博客随笔，不适合技术文档。

实战示例：让 Claude Code 画一张用户登录架构图

第一步：安装

1
2
3
4
5
6
7
8
9
# 方式 1：作为 Claude Code 插件
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

# 方式 2：作为 Claude Cowork 插件
# Customize → Directory → Plugins → + → 粘贴 cathrynlavery/diagram-design → Sync

# 方式 3：作为 Codex skill
npx skills add <your-fork-or-mirror> --skill diagram-design

第二步：浏览图库

1
2
git clone https://github.com/cathrynlavery/diagram-design
open skills/diagram-design/assets/index.html

浏览器里会打开一个交互图库，包含全部 29 张图，分别有 light /dark/full-editorial 三种主题。挑一个最接近你想要的风格。

第三步：让 Claude Code 生成图

在 Claude Code 里直接说：

“用 diagram-design 的 Architecture 类型，给我画一张用户登录流程的架构图，包含前端、API 网关、认证服务、用户库、Redis 缓存这五个节点。强调色用 coral（珊瑚色），焦点放在认证服务上。”

Claude 会自动调用 /diagram-design 这个 skill，输出一段自包含 HTML，保存到当前目录。

第四步：导出

1
2
3
# 在 Claude Code 里用 slash command
/diagram-design export output/login.html --format svg
/diagram-design export output/login.html --format png

PNG 导出需要一次性安装 Playwright：

1
pip install playwright && playwright install chromium

实际输出长什么样？

我拿项目自带的一个示例改造了一下：一张 “Web 应用登录流程” 的时序图，焦点元素是后端认证服务，其它节点用低饱和度灰色，标注栏写着 “Single source of truth for sessions”。

打开 HTML 文件的效果是 ——

页面背景是 #FAFAF7 这种米白色，而不是纯白 #FFFFFF。节点圆角 6px（小于 10px 上限），边框 1px #E5E5E0。标题用 Instrument Serif 斜体：”User authentication flow”。节点名用 Geist Sans：”Browser”、”API gateway”、”Auth service”、”Postgres”、”Redis”。技术子标签用 Geist Mono：”POST /login”、”SET session:xxx”、”SELECT * FROM users”。认证服务那个节点用珊瑚色 #FF6B5C 描边，里面写着 “Single source of truth”。连线是 1px 实线，转角处直角不圆滑。整张图所有间距都是 8、16、24、32、48—— 清一色 4 的倍数。

一眼看过去就是” 杂志专栏图” 的味道，而不是”AI 出图” 的味道。

适用场景和限制

最适合的场景

  • 技术博客头图：直接放进博客文章，质量比 Mermaid 高两档。
  • 产品文档架构图：给客户看的设计文档。
  • 公司内部 Wiki：Confluence、Notion 都支持嵌入 HTML。
  • 演讲幻灯片：导出 SVG 拖进 Keynote/Figma，二次编辑没问题。
  • AI Coding Agent 的” 画图” 任务：替代 Mermaid 作为默认输出。

不适合的场景

  • 需要” 实时数据驱动” 的图：它是静态 HTML，不支持数据绑定。如果你要” 点击节点看详情”、”hover 显示 tooltip” 这种交互，得用 Excalidraw、tldraw、miro AI。
  • 极复杂的企业架构：29 种类型里没有专门给” 几百个微服务关系” 用的图。超大架构还是 Structurizr（C4 模型）更合适。
  • 需要 Git diff 友好：因为输出是 HTML，不是文本语法，PR review 里只能看到 HTML 改动，看不到” 图本身的变化”。Mermaid/D2 在这点上更强。
  • 非 Claude Code 用户：虽然技术上是 HTML + SVG，但整套技能是为 Claude Code 设计的。Codex 用户能用，Cursor/Cline 用户体验会打折扣。

跟同类项目的差异

  • vs Mermaid：Mermaid 是” 语法 + 渲染器”，diagram-design 是” 技能 + 设计规范”。Mermaid 输出工程图，diagram-design 输出杂志图。
  • vs Excalidraw：Excalidraw 是” 可视化画板 + AI”，diagram-design 是”AI 直接吐图”。如果你想自己画，Excalidraw 更好；如果你想 AI 帮你画，diagram-design 更快。
  • vs Napkin / Whimsical / Lucidchart：这些是 SaaS 平台，diagram-design 是开源 + 自包含。SaaS 平台有协作、模板市场、品牌管理；diagram-design 给你完全控制权和可二次编辑的 HTML。
  • vs D2 / PlantUML：D2/PlantUML 是” 代码生成图”，diagram-design 是” 技能约束设计”。D2 给你的是” 能用就行”，diagram-design 给你的是” 高级感”。

总结

cathrynlavery/diagram-design 不是一个” 工具”，它是一种 **” 让 AI 画图也能出片” 的工作流 **。它通过 29 个细分的图表技能 + 一组硬性设计规范（特别是 4 像素栅格这个反直觉但有效的约束），把 LLM 的图表输出从”Mermaid 风” 拉到了” 杂志风”。

如果你已经重度使用 Claude Code，并且经常需要给博客、文档、PPT 配架构图，这个项目值得直接装上。如果你只是偶尔画个流程图，Mermaid 还是够用的 —— 但你会越来越嫌弃它。

下一个阶段我比较期待的方向是：把这种” 硬性设计约束” 思路推广到 UI 设计（design tokens + 技能）、数据可视化（chart-design skill）、PPT 排版（slide-design skill）。一旦 AI 学会遵守” 行业硬规矩”，它产出内容的可信度会再上一个台阶。

仓库地址：https://github.com/cathrynlavery/diagram-design