Mermaid 画不出能放进文章的图，diagram-design 给 Claude 装了个审美闸门

你让 Claude 画个架构图，十有八九拿回来的是这么个东西。深色背景，青色和紫色发光的连线，每个节点都是一模一样的圆角矩形，字体清一色等宽。看着挺「技术」，但你根本不会把它截图放进自己写的文章里。

这不是模型笨。是你没给它规格。

Cathryn Lavery 在写她的博客 littlemight.com 时反复撞上这件事。她要一张架构草图、一个流程图、一个「什么最重要」的金字塔，问 Claude，回来永远是那种通用圆角盒子，跟网站风格毫无关系。要么打开 Figma 抠半小时配色，要么干脆不画。她不是写代码出身的工程师，她是做手账和效率工具的创业者，手头那家公司叫 BestSelf.co。但她决定换个思路。

不是换个更聪明的模型，是给 Claude 塞一套设计规格进去。

结果就是 diagram-design。今天 GitHub trending 日榜第一，单日涨 1612 颗星，总星 5996，277 个文件。它卖的就一句话，editorial diagrams your designer won't hate，设计师不会嫌弃的编辑级图表。我自己把源码拆了一遍，说真的，这套思路比我想的有意思，但它的「保证」也比 README 说的要软不少。下面一条条讲。

这个 Skill 到底在干什么

diagram-design 是一个 Claude Code Skill，也兼容 Codex 插件。你跟 Claude 说「画个我应用的架构图，前端、后端、数据库、Redis 缓存」，它会自己挑一个图表类型，按一套固定的编辑级设计系统，生成一个自包含的 HTML 文件。内联 SVG 加 CSS，零 JS，零外部图片，浏览器直接打开就能截图。

27 种图表类型。架构图、流程图、时序图、状态机、ER 图、时间线、泳道、四象限、雷达图、飞轮循环、嵌套、树、组织架构、层级栈、韦恩图、金字塔，再到柱状图、折线图、甘特、散点，还有一批数据平台专用的（Medallion、DP integration、DP security matrix）。每种都分浅色、深色、全编辑三个变体。

到这里你可能觉得，不就是个图表模板包嘛。其实吧，真不是。它最值钱的地方不在模板数量，在那套被反复强调「non-negotiable」的设计规格上。

把审美本身写成规则

这是整篇我最想讲透的部分。

这套 Skill 的核心赌注是这样的。AI 味图表之所以千篇一律，不是模型不会画，是没人告诉它「什么算好看」。Mermaid 那套东西一眼能认出来，是因为它的默认审美就是技术模板，深色加发光加等宽圆角。要打破它，你得把审美拆成机器能照着执行的规则。

diagram-design 干的就是这件事。我把几条最硬的挑出来。

4px 网格，不可商量。 SKILL.md 第 7 节，所有数值，字号、内边距、节点尺寸、间距、x/y 坐标，必须能被 4 整除。它甚至给了一张白名单，字号只能取 8/12/16/20/24/28/32/40，节点宽度只能取 80/96/112/128/160 这类值。最狠的是这句，如果某个坐标以 1、2、3、5、6、7、9 结尾，修掉它。坐标和间距落在一个稳定节奏上，图就不会有那种「随手凑」的 AI 感。

不过这里我得插一个但。这条 4px 网格在文档里被反复叫做 non-negotiable，不可商量。可整个仓库里真正能跑的校验脚本 scripts/lint-skin.py，翻一遍它的 lint_text 函数，只查三件事，颜色 hex 是不是在 style-guide 调色板里、有没有用纯黑 #000000、字体是不是允许的那几个（Instrument Serif、Geist、Geist Mono）。它完全不查坐标是不是 4 的倍数。也就是说，4px 网格这条「不可商量」的规则，靠的是 LLM 读完 markdown 自觉遵守，没有任何机器兜底。这是后面我要讲的那个关键问题的预演，先放一边。

复杂度预算，每种图有上限。 一张图最多 9 个节点，最多 12 条连线，最多 2 个珊瑚色焦点。时序图最多 5 条生命线，四象限最多 12 个条目，ER 图最多 8 个实体，泳道最多 5 条泳道，树最深 4 层。超过就拆成两张图。你想想看，这条规则潜台词是，超过 9 个节点你画的就不是图了，是信息淹没。它逼你做减法。

一条强调色，最多两个焦点。 这是我最喜欢的一条。accent 色（默认 atomic-tangerine #eb6c36）只能用在一到两个最该被先看到的元素上。文档原文说，coral is editorial, not a flag，珊瑚色是编辑性强调，不是信号旗。一旦你想给 5 个节点都涂强调色，说明你还没想清楚到底什么最重要。这种「克制即设计」的态度，跟那种恨不得把所有功能都涂彩色的产品思维，是两个物种。

5 条强制连接线规则。 这部分最像一份正经的制图规范。连接线必须用圆角直角弯头（r=8），禁止斜线；标签和线之间必须留 6 到 10 像素的缝，标签底下垫一个不透明遮罩，不能压在线上；两条线不能重叠或共线，交叉时要用桥接（bridge/hop）画法；多条线进同一个边时，挂载点要沿边散开，彼此间距至少 12 像素；连接线不能从非端点的盒子背后穿过，除非几何上实在避不开，那种例外下线必须画成虚线，表示「过境，不交互」。

光这 5 条就够大多数画图工具学一阵了。我一直觉得，很多团队花了大价钱做的图表组件，连接线处理还没这一份 markdown 文件讲得明白。

语义 token 系统。 所有颜色不写死 hex，写语义角色。paper 是背景，ink 是主文字和描边，muted 是次级文字和默认箭头，accent 是焦点。深色模式靠一条反转规则，任何 rgba(28,25,23, X) 在深色下变成 rgba(250,247,242, X)，同样的透明度，RGB 翻转。你换成自己品牌色，改一个 references/style-guide.md 文件，所有图全部继承。这套东西做前端的人应该很眼熟，跟设计 token 的思路一模一样，只是搬到了「给 LLM 看的 prompt 规格」里。

60 秒把你的品牌灌进去

其实吧，onboarding 是这个 Skill 另一个聪明的点，也是它在 README 里最用力的卖点。

整个流程是这样的。你跟 Claude 说「onboard diagram-design 到 https://yoursite.com 」，它去抓你的首页，提取主色和字体栈，映射到那套语义角色上（你的 body 背景变 paper，CTA 色变 accent，正文字体变 node-name），给你看一个 diff，你点头它就写进 style-guide.md。从此每张新图都用你的色。它甚至会在写 token 前自动做 WCAG AA 对比度检查，如果你的某个色在 9 到 12 像素这种小字号下不达标，它会主动建议一个调整值并解释原因。

这个设计真正的洞察是，它把「品牌一致性」这个本来要设计师手动维护的事，变成了一次性的 URL 输入。

但就在这个最卖力的功能上，我挖到了一个让人哭笑不得的 bug。

SKILL.md 第 0 节有个「首次运行 gate」，专门防止 Skill 把默认皮肤偷偷塞进一个有品牌的项目。它的检测逻辑写得很直接，如果 style-guide.md 里的 accent 值跟 #b5523a（一种暖 rust 色）不一样，就认为已经自定义过了，跳过 gate。问题是，style-guide.md 里真正的默认 accent 是 #eb6c36（atomic-tangerine），根本不是 #b5523a。也就是说，在一个全新安装上，accent 永远是 #eb6c36，永远不等于 #b5523a，gate 会立刻判定「已自定义」然后跳过自己。这个被当作招牌的首次运行拦截，在自己全新的安装上是失效的。

坦白讲，这不是我推测的。两份文件摆在那儿，SKILL.md §0 写的默认是 #faf7f2 纸、#1c1917 墨、#b5523a rust，style-guide.md 的默认 token 表写的是 #f5f5f5 纸、#2d3142 墨、#eb6c36 tangerine。一个暖色系，一个冷色系，两套默认皮肤，明显是某次大改皮肤后 SKILL.md 那段忘了同步更新。style-guide.md 自己也在角落留了句备注，assets 里那些预生成的示例 HTML 是「更早一版皮肤」下做的，重新对齐是 v5.1 的待办。版本号也有点乱，frontmatter 标着 2.0，注释里又冒出个 v5.1。

顺便说几个小出入

往细了看，这种「文档没跟上代码」的小毛刺还有几处。

GitHub 仓库描述写的是「29 editorial diagram types」，但 README 正文、SKILL.md、实际的 type-*.md 文件，数下来全是 27 个。这个 29 大概是某次加类型时改了描述、后来又回收，没改回来。不影响用，但作为「编辑级严谨」的人设，这种数字对不上挺扎眼。

再看发布节奏。metadata 里标着 version 2.0，README 还专门有段「New in 2.0」，但 GitHub Releases 一条都没有，零。也就是说 2.0 只是个写在 frontmatter 里的字符串，没有对应的 tag，没有 changelog。贡献者去掉 web-flow 那个 GitHub 网页机器人，实际参与提交的大概 4 个人，核心就是 Cathryn 一个。项目 2026 年 4 月才建，四个月冲到近 6 千星，势头很猛，但 bus factor 偏低这件事得诚实讲。一旦她顾不上，这套高度依赖维护者审美把关的系统，延续性是要打问号的。

坦白讲，这些都不是致命问题。一个四个月大、一个人主导的 Skill，文档有点漂太正常了。我特意拎出来，是因为它正好戳中这套思路最核心的那个软肋。

真正值得带走的东西

把前面这些串起来，你会发现 diagram-design 走的是一条很特别的路。

它解决的不是「模型能不能画图」，Claude 本来就能画。它解决的是「模型画的图为什么丑」，答案是缺规格。于是它把审美，字号节奏、强调色配额、连接线弯头角度、节点上限，全部写成 LLM 能读能执行的规则。这是一套可以复用的方法论，我给它起个名字，Spec-as-Taste，把审美编码成规格。你想让一个 LLM 稳定产出某种风格的东西，别指望它在 prompt 里「领悟」你的品味，把品味拆成可执行的约束喂给它。

但 diagram-design 也把这条路的天花板暴露得很清楚。说真的，规格分两种，一种能被机器验证，一种只能靠 LLM 自觉。

颜色和字体是能机器验证的，lint-skin.py 就干这个，你提交一个用了 #000000 纯黑的图，它真能拦下来报错。这是硬保证。可 4px 网格、连接线圆角弯头、9 节点上限、标签留缝，这些更关键的「编辑级」规则，全是 markdown 里的检查清单，也就是它说的 taste gate，靠模型读完自觉照做。没有任何脚本会因为你画了个斜线连接就拒绝输出。它最引以为傲的那套反 AI 味的结构规则，全是 aspirational，是愿望，不是强制。

这就给所有做 Skill 和 Agent 的人一个很实在的判断标准。你给 LLM 定的任何规矩，问自己一句，这条有没有一个脚本能在我违反时让我构建失败。有，它就是真约束。没有，它就是建议，模型心情好照办，context 一长或者换个模型就可能忘。diagram-design 的聪明在于，它至少把最容易机器化的那一层（调色板）做成了硬约束。它的遗憾在于，那一层恰好不是它最该骄傲的部分。

所以回到选型。如果你写技术博客、做产品文档，需要一个截图就能用、跟你网站配色一致的图，而且你愿意花 60 秒跑个 onboarding，diagram-design 是目前 Claude 生态里最讲究的一个，没有之一，那个编辑级皮肤确实比 Mermaid 和各种 AI 画图工具好看一大截。但你要清楚，它给你的「保证」止于颜色和字体。结构上的好看，得靠 Claude 当天状态好不好，和你自己最后那双眼睛。

一个非工程师创业者，把「审美」这件事从玄学变成了可写的规格，这件事本身就值得 6 千颗星。至于那些规格能被多大程度机械执行，是下一阶段该补的功课。

怎么装，怎么用

分析归分析，真想拿它给自己的文章配图，装和用都简单，照着下面走就行。

第一步，装。 Claude Code 用户最省事的是插件方式：

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

装完建议把自动更新打开。Claude Code 对第三方市场默认关着 auto-update，运行 /plugin，进 Marketplaces，选中 diagram-design，点 Enable auto-update，之后启动时它会自己在后台刷新。

打算自己改配色的，别走插件，走 clone 加 symlink。插件更新会把你手改的 style-guide.md 覆盖掉，symlink 过去的改动才不会丢：

git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design

重启 Claude Code 生效。Codex 用户走市场命令：

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

之前按老办法用 npx skills add 装过的，那是独立副本，不会跟着市场更新，删掉按上面重来。Pi 用户一句 pi install https://github.com/cathrynlavery/diagram-design 搞定，开着会话的话 /reload 一下，更新要手动跑 pi update --extensions。组织里想用 Claude Cowork 统一分发的，README 另有一段镜像仓库的说明，这里不展开。

第二步，灌品牌。 跟 Claude 说一句话，它会抓你的首页，把背景映射成 paper、CTA 映射成 accent、正文字体映射成节点字体，给你看个 diff，点头就写进 style-guide.md：

onboard diagram-design to https://yoursite.com

这步前面讲过细节，60 秒的事。想纯手动改也行，直接编辑 skills/diagram-design/references/style-guide.md 里的 token 表。

第三步，让它画。 装完重启之后正常对话就行，Skill 会自动激活：

Make me an architecture diagram of my app: frontend, backend, database, Redis cache.
Give me a sequence diagram of the OAuth handshake.
I need a quadrant showing Q2 projects by impact vs effort.

它会自己挑图表类型，生成一个自包含的 HTML 文件，浏览器打开就能截图，零 JS 零外部图片。想跳过对话直接起步，也可以从模板复制，cp skills/diagram-design/assets/template.html my-diagram.html，minimal light、全编辑、动效三个版本都有。

存量旧图不用重画，让它重绘。 手头有 draw.io 或 Mermaid 图的，指着源文件让它重绘就行，斜杠命令或者自然语言都可以，内容不变，皮肤换成这套设计系统：

/diagram-design:import platform.drawio
/diagram-design:import platform.drawio --size=slide-16x9 --detail=simplified --audience=executive
/diagram-design:import-mermaid README.md --diagram=all

draw.io 的几种容器格式（.drawio、.drawio.xml、内嵌图的 .drawio.png 和 .drawio.svg）都能读，Mermaid 吃 .mmd 和 Markdown 里的 fenced 代码块，全程只解析文本，不渲染、不联网。重绘有四个旋钮。format 定产物，html、svg、png 随你挑；size 连画布带字号一起换，投到幻灯上节点名自动从 12px 升到 16px；detail 定留多少，faithful 最多 24 个节点、balanced 12 个、simplified 7 个，砍的顺序是先装饰、再重复、再叶子簇、最后基础设施；audience 换措辞不换数量，engineer 看到 Auth Service / JWT · RS256 · :8443，executive 看到的就是 Sign-in。README 里那张对比图很有说服力，源文件六种粉彩填色收敛成一个 accent，手拖的坐标全部归位到 4px 网格。每次重绘结束还会附一份 fidelity ledger，合并了什么、折叠了什么、丢了什么，一条条列出来，你可以对着源文件核账。

导出成 PNG 或 SVG。 生成的 HTML 想转图片，用斜杠命令：

/diagram-design:export path/to/diagram.html --svg-only
/diagram-design:export path/to/diagram.html --png-only --scale=3

PNG 走 Playwright 截图，第一次用要装一下环境，pip install playwright && playwright install chromium。SVG 会内联 Google Fonts，丢进 Figma 或 Illustrator 直接能编辑。Pi 那边对应的是 /export-diagram。

想先看看各种图长什么样，不用装，在线画廊直接扫：cathrynlavery.github.io/diagram-design。clone 到本地的话，open skills/diagram-design/assets/index.html 打开内置版，还能按浅色、深色、全编辑三个变体切换。