一、一周涨 7,208 星的到底是什么项目
cathrynlavery/diagram-design 这个仓库，在 2026 年 9 月 14 日那期 GitHub 周榜里排到第 2 名，统计区间 2026.09.08 到 09.13 内净增 7,208 颗星。截至核数当天，它累计 39,807 颗星、2,528 次 fork，主语言是 HTML，许可证为 MIT，创建于 2026-04-16，最近一次推送在 2026-09-10，未关闭 issue 还有 44 个。
作者是 Cathryn Lavery，BestSelf.co 的创始人，平时在 littlemight.com 写 AI、创业与设计相关的内容。这件事本身就值得玩味：一个设计师背景的人，做出来的"图表技能包"在工程师聚集的 GitHub 上冲到周榜第二，靠的不是又一个画图引擎，而是一套相当克制的出图规范。
需要点出一个核真细节：官方 README 自己写的是 39 种编辑级图表类型，但周榜抓取到的项目描述写的是 38 种，两者不一致。以 README 的 39 为准——2.5.10 版本一次新增了十种布局语法。这种口径上的小差异，恰恰是"实核"和"转述"的分界线，下面也会在文中带过。
它不是一个独立应用，而是一个面向 Agent Skills 兼容宿主的图表技能包：Claude Code、Codex、Factory Droid、Pi、GitHub Copilot、Kiro、OpenCode 这些都能接。换句话说，它不是给你一个 GUI 让你拖拽，而是装进你的编码 agent，让 agent 在写文档、写方案时顺手出图。
二、它产出的东西长什么样
它的输出是自包含的 HTML 加 SVG：没有构建步骤、没有 JavaScript、没有外部图片依赖。双击就能在浏览器里打开，离线也能看，唯一的外部请求是 Google Fonts 那一个。这条"无 JS、无构建、自包含"，是整件事的题眼。
为什么这是题眼？因为几乎所有图表引擎都要回答一个问题：渲染依赖怎么解决。Mermaid 要一个运行时去把文本解析成图；draw.io 是一个完整的编辑器；Excalidraw 依赖浏览器和手绘库。diagram-design 绕开了整条路——它直接产出一份静态文件，任何能打开 HTML 的环境都能看，不需要任何工具链。你得到的不是"一段需要被渲染的代码"，而是一张"已经画好的图"。
这也是它和 Mermaid 划清界限的地方。官方宣传语原文是：No shadows. No Mermaid slop.（无阴影、不要 Mermaid 那种糊弄货）。把 Mermaid 摆到对手位，是它立人设的方式。
每一种图表类型都提供三种静态变体：minimal light、minimal dark、full-editorial。light 和 dark 是干净的底色版本，editorial 是带编辑级卡片和页眉的版本。注意，导出时这两种格式"只含图本身"，editorial 卡片和页眉不在默认导出里，只有 -full 变体才带。这个边界后面会专门讲。
三、设计系统拆解：约束为什么反 AI 味
真正让这个项目成立的是它的设计系统，而不是那 39 种类型。它有一组看起来吹毛求疵、实则指向明确的约束：
- 只用一个强调色，每张图只保留 1 到 2 个视觉焦点元素。
- 三套字体：Instrument Serif（标题与斜体注释）、Geist sans（节点名）、Geist Mono（技术副标签）。
- 1px 发丝边框、没有阴影、圆角最大 10px。
- 所有坐标、宽度、间距都必须是 4 的整数倍。
- 默认配色是 jet-black 加 atomic-tangerine。
- 目标信息密度定为 4/10，官方一句设计箴言是"最高质量的操作通常是删除"。
这些约束单独看都小，合在一起指向一件事：让图"不显得像 AI 生成的"。现在 AI 出的图有两个通病——要么滥用渐变和阴影显得廉价，要么元素堆得满、对齐乱、密度失控。diagram-design 用"无阴影、单强调色、4 的倍数网格"直接堵死这两条路。4 的倍数这条尤其关键：人类手工布局时往往落在整数网格上，而模型随手给的坐标常常带小数、对不齐，于是整体透出一股"AI 味"。把它强制到 4 的整数倍，等于在生成层面就抹掉了那种不对齐。
这套系统不是堆类型数量来覆盖场景，而是反过来：它先定义行为模式，再选视觉类型。项目里内置 8 条"语义模式"，比如 fan-in 队列与瓶颈、重复阶段槽、非结构化输入转换、成对策略轨迹、安全铺装路、治理目录、补偿式安全层、可溯源块分解。逻辑是"先定你要表达的行为，再挑一种图去承载"，而不是"我手里有 39 种图，挑一个顺眼的"。这点和AI 编码技能框架横评里提到的"技能应当围绕意图组织而非围绕工具堆叠"是同一个判断。
四、品牌 onboarding 与多客户 profile
光有默认皮肤还不够，它最实用的功能是品牌 onboarding。你对它说一句"onboard diagram-design to https://你的站点"，它就会去抓你的首页，抽取主色调与字体栈，映射到一组语义 token：paper、ink、muted、accent、link、paper-2。在真正写文件之前，它会先给你看一份 diff，确认无误才落盘到 references/style-guide.md。
这个过程不是无脑套色。它会自动做 WCAG AA 对比度校验；如果你的品牌色在 9 到 12px 这种图内小字号下不达标，它会给出调整值，并解释为什么。落地后还会输出一份 fidelity receipt（保真回执），列明采样了哪个 URL、每个颜色角色是什么、用了什么字体族与字重、字体来源 URL，以及任何降级处理。
还有一个 first-run gate（首次运行门禁）：在一个从没定制过 style-guide 的项目里第一次用它出图，它不会闷头就出，而是停下来问你——要 onboarding、手填 token，还是直接用默认皮肤。这个"先问再动"的设计，避免了agent 在没上下文时乱套品牌。
多客户场景它也想清楚了。品牌可以存成命名 profile，放在 ~/.diagram-design/profiles/<slug>.md；项目里放一个 .diagram-design 标记文件，内容写 profile: <slug>，这个项目的图就直接读对应 profile。多个工作区并行跑，互不覆盖。而且 profile 库在 Claude Code、Codex、Factory Droid、Pi 之间是共享的——你在 A 工具里定好的品牌，B 工具能直接复用。
五、导入与导出：重绘而不是转换
它支持把 draw.io、Mermaid、Excalidraw 的源文件重绘成这套设计系统的图。关键词是"重绘"而不是"转换"：保留内容和结构，换掉样式。这点和把书蒸馏成技能包的思路一致——拿别人的素材，按自己的规范重新产出。
导入的格式覆盖很全：draw.io 支持 .drawio、.drawio.xml、.drawio.png（内嵌图）、.drawio.svg，包括压缩过的 payload；Mermaid 支持 .mmd、.mermaid 以及 Markdown 里的 mermaid 代码块；Excalidraw 支持 .excalidraw 与 .excalidraw.json 场景文件，但不支持它的 png/svg 导出。Excalidraw 这条路径只解析文本：不渲染、不执行 JavaScript、不开浏览器、不联网、不跟随点击目标。这一点对安全很重要——重绘一个别人发来的 Excalidraw 文件，不会触发任何副作用。
整个导入由四个旋钮控制：
| 旋钮 | 取值 | 说明 |
|---|---|---|
| Format | html、svg、png、html+png | 输出形态 |
| Size | doc-inline、doc-wide、slide-16x9、slide-4x3、social-og、social-square、print-a4-landscape、print-letter-landscape、fit（共 9 档） | 同时改 viewBox 与字号阶梯，投影用图用 16px 节点名而非 12px |
| Detail | faithful（最多 24 节点）、balanced（最多 12）、simplified（最多 7） | 按固定降级阶梯删减：先装饰、再重复、再叶簇、最后基础设施 |
| Audience | engineer、mixed、executive | 改的是措辞不是数量，例如 Auth Service / JWT · RS256 · :8443 到 Auth Service / token check 再到 Sign-in |
每次导入结束都会输出一份 fidelity ledger（保真账单），说明哪些被合并、折叠或丢弃。这里还有一组明确的边界：它不继承源文件或渲染器的坐标、源配色、源字体、draw.io 的斜线连接器乱麻、Mermaid 的自动布局、Excalidraw 的手绘几何；它一定继承的是组件、关系、分组、方向。
导出侧同样有边界。导出 SVG 时，它抽出 <svg> 节点并注入 Google Fonts，方便在浏览器、Figma、Illustrator 里独立使用。导出 PNG 用 Playwright 栅格化，默认 2 倍；一次性准备是 pip install playwright && playwright install chromium。前面说过，两种导出格式都只含图本身，-full 变体里的编辑级卡片与页眉不含在内。
六、工程质感与边界，以及谁该用
这个项目最让我高看一眼的，是它对"图会撒谎"这件事的较真。它在工程上做了几件不讨巧但扎实的事。
裁切检测用的是像素差分而不是几何。官方明确说 getBoundingClientRect() 会漏掉描边宽度、标记与滤镜溢出，也不懂 clip-path，所以他们把每个 SVG 按原样截一次、再释放 overflow 截一次，两张图做差分，出现在外面的墨迹就是被裁掉的。而且它不存 golden image（基准图），所以仓库里没有一堆需要重录的基准 PNG——这点对长期维护很友好。
它有一批专门的门禁脚本，专治各类"图会撒谎"：Sankey 的守恒检验、waterfall 的运行总额校验、treemap 的面积误差校验（用相对误差而不是绝对误差，因为绝对值会恰好放过那些最容易出错的小格子）、标签遮挡的几何校验、块注册表的环路与悬空父节点校验。这些不是锦上添花，而是"出一张数据图但数字对不上"这种尴尬的直接防线。
渐进披露也做得克制。常规出图时，agent 只加载 SKILL.md 加那一个类型的参考文件，语义、类型、动画参考按需加载。这对 token 成本很友好，也意味着它没把整本说明书一次性塞给模型。
动效是可选的，而且不新增类型。支持 none、reveal、step、loop 四种模式，默认 none，默认输出是静态且无脚本的。静态首帧必须是完整的；在 prefers-reduced-motion 下显示完整静态帧并隐藏播放控件。动效 HTML 只能用仓库里那个经过审查的固定控制器，任意或改过的内联脚本、远程资源、CSS @import、可执行属性一律拒绝。这又是一道安全边界。
无障碍同样没有糊弄。每张图的 SVG 都带 role="img"、能解析的 aria-labelledby，以及作为首个子元素的 <title> 与 <desc>；SVG 内部 ID 按图表与变体加前缀，保证多个 SVG 内联到同一页面时不会出现重复的可访问名 ID。项目还内置 87 个单色 IT/云图标（笔记本、手机、用户、服务器、数据库、Docker、Kubernetes、AWS、Azure、GitHub、Postgres 等），描边图标来自 Tabler Icons（MIT），品牌轮廓来自 Simple Icons（CC0），统一用 currentColor 继承皮肤。
但它也清楚地说了"不要用"的场景，这点反而加分：
- 推特或终端里用的快速 unicode 示意图；
- 任何"清单"性质的东西，用表格或列表更好；
- 前后对比，用表格；
- 只有一个框加一个标签的"图"，直接写句子。
官方让使用者先自问：读者从这张图里学到的，会比从一段写好的文字里更多吗？如果不会，就别画。
那么判断来了：什么团队该上？如果你的产出要进文档、进方案、进给客户看的报告，且你受不了 Mermaid 那种"能看但廉价"的观感，又想要离线、可归档、可无障碍访问的静态文件，diagram-design 值得一试。它把"AI 出图"从"生成一张看起来像样的图"推进到"产出一个可交付、可归档、可无障碍访问的静态文件"，这一步是有真实价值的。
代价也很清楚：它是一套绘画规范很重的系统，上手成本高于写一行 Mermaid，你要先理解它的 token、profile 和四旋钮。如果你只是想在 README 里快速画个流程图，Mermaid 就够了，别为了"高级感"硬上这套。另外它把 Mermaid 当对手，却又提供 Mermaid 导入通道——这个张力值得记住：它真正想取代的不是 Mermaid 的语法，而是 Mermaid 那种"糊弄货"的审美。接入实操可参考 Codex harness 接入实操，本质都是把技能包装进你的 agent 工作流。
常见问题
Q1：diagram-design 支持哪些 Agent 宿主？
A1：官方定位是 Agent Skills 兼容宿主，已点名支持 Claude Code、Codex、Factory Droid、Pi、GitHub Copilot、Kiro、OpenCode。它装进 agent 后由 agent 在写文档或方案时调用，不是独立 GUI 应用。
Q2：39 种和周榜写的 38 种，到底听谁的？
A2：以 README 的 39 种为准。周榜抓取到的项目描述写的是 38 种，两者不一致；2.5.10 版本一次新增了十种布局语法，README 是更新后的口径。
Q3：导出 PNG 要装什么？
A3：用 Playwright 栅格化，默认 2 倍。一次性准备命令是 pip install playwright && playwright install chromium。SVG 导出则不需要这套，只需抽出 <svg> 并注入 Google Fonts。
Q4：它能把我的 draw.io 文件直接变成这套风格的图吗？
A4：可以，且是"重绘"不是"转换"——保留组件、关系、分组、方向，换掉样式。支持 .drawio、.drawio.xml、.drawio.png、.drawio.svg（含压缩 payload）。但它不继承源坐标、源配色、源字体、draw.io 的斜线连接器乱麻。
Q5：图里那些 IT 图标有版权风险吗？
A5：内置 87 个单色 IT/云图标，描边图标来自 Tabler Icons（MIT），品牌轮廓来自 Simple Icons（CC0），统一用 currentColor 继承皮肤，合规可用。仓库整体许可证为 MIT。