拒绝 Mermaid 垃圾：2.8 万星 AI 技能把图表画出了杂志质感

AI 画的架构图，十张有九张长一个样：圆角方框、青紫渐变发光、JetBrains Mono 满屏飞，像极了学校课题的封面。而另一个极端你也经历过：在 draw.io 里拖一小时方框，就为配一张能见人的图。

有个开源项目把这两个痛点一起解决了。它叫diagram-design，一个装进 AI Agent 里的图表设计技能：你说一句"给我画一张前端、后端、数据库加 Redis 缓存的架构图"，它直接产出一份出版级质量、可离线打开、截图就能用的独立 HTML 文件。2026 年 8 月 12 日，它登顶 GitHub Trending 全语言第一；截至当月安全扫描数据，Star 数已达 2.77 万并持续攀升，Fork 超过 1700。它的仓库标语只有一句话，挑衅得很直白：

无阴影。拒绝 Mermaid 垃圾。

这篇文章把它的设计系统、架构、工程质量、社区争议一次讲透——读完你就知道，它凭什么这么狂，以及它是不是你的菜。

一、它到底是什么

diagram-design 不是一个新的图表渲染器，也不是 SaaS。它是一个Agent Skill（智能体技能），安装进 Claude Code、Codex、Factory Droid、Pi 四个 AI 编码智能体后，你的 AI 助手就获得了"画出杂志级图表"的能力。核心规格一句话说完：

• 39 种视觉图表类型，从架构图、时序图、ER 图，到桑基图、沃德利地图、鱼骨图、用户旅程图，每种都有浅色、深色、完整出版级三种变体；
• 输出是单个自包含 HTML 文件：内联 SVG + 内联 CSS，唯一的外部引用是 Google Fonts——双击就能打开，离线可用，无需构建步骤、无需 JavaScript、无需外部图片；
• 支持导出 SVG / PNG（PNG 通过 Playwright 光栅化，默认 2 倍缩放）；
• 可以把现有的Mermaid 代码和 draw.io 文件重绘成它的出版级风格；
• 全流程默认无障碍：每张图自带role="img"、可解析的aria-labelledby、有前缀的，并遵守prefers-reduced-motion

所有 39 种类型在官方在线画廊里都能翻，浅色 / 深色 / 出版级三个选项卡逐一切换，就能判断这套审美是否对你胃口。

二、先说说为什么 AI 画的图普遍很丑

diagram-design 的 README 里藏着一份"AI 生成粗劣产物目录"——12 种反模式，每一种都在给市面上的 AI 图表画像：

• 暗色模式 + 青色 / 紫色发光，"看似有技术感，实则回避了设计决策"；
• 把 JetBrains Mono 当万能"开发者字体"，人类可读名称也用等宽体；
• 每个节点都是同样的方框，层级全灭；
• 图例浮在图表中间、箭头标签压在连线上、对角线乱飞；
• 三个等宽摘要卡片排排坐，rounded-2xl圆角糊脸；
• 给每个"重要"节点都上强调色——于是没有任何东西是重要的。

这份清单之所以扎心，是因为它描述的正是大多数 AI 生成图表的默认形态：渲染器逻辑代替了设计决策。Mermaid 和 draw.io 解决的是"把结构画出来"，从来没打算解决"画得好看"。diagram-design 的全部野心，就是把这层设计决策补上。

三、设计系统：一套近乎固执的编辑纪律

打开它的产出，你会先注意到配色：白烟色纸底（#f5f5f5）、墨黑（#2d3142）、蓝板岩（#4f5d75），唯一的强调色是原子橘（#eb6c36）。这不是随便挑的——它是一套五色品牌调色板，衍生出十个语义 Token：paper（纸面）、ink（墨）、muted（弱化）、soft（柔和）、accent（强调）、link（链接蓝）、rule（极细线）等等。所有生成的 SVG 里不允许出现裸十六进制色值，只允许引用 Token 角色名——这个间接层是整个系统的承重墙，后面讲品牌换肤时会再看到它的威力。

几条铁律贯穿全部 39 种类型：

1. 强调色最多出现在 1–2 个元素上。官方原话："如果你忍不住想强调四个东西，说明你还没决定什么是焦点。"橘色是指针，是"从这里开始看"，不是装饰。五个指针等于零个指针。

2. 目标密度 4/10。一张图最多 9 个主节点、12 条箭头，超过就该拆成概览 + 详情两张。官方的说法是："示意图不是在加上所有内容时完成的——而是在无法再删除任何内容时完成的。"每张图在绘制前都要过一遍"删除测试"：能删的节点吗？能合并的节点吗？能删的箭头吗？能删的标签吗？

3. 一切坐标对齐 4px 网格。每个字号、间距、坐标、宽高都能被 4 整除，保证 1×、2×、3× 缩放下像素不糊。以 1、2、3、5、6、7、9 结尾的坐标被明确定义为缺陷。

4. 三字族分工不可撼动。Instrument Serif（衬线）只用于标题和斜体旁注，Geist 无衬线只用于节点名称，Geist Mono 只用于端口、URL、协议这类技术元数据——并且任何地方都禁止 JetBrains Mono。衬线标题 + 无衬线名称 + 等宽技术标签的对比，就是"出版感"的来源。

5. 语义靠形状和虚线，不靠颜色。流程图里椭圆是起止、矩形是步骤、菱形是判断；虚线4,3表示可选 / 异步，虚线4,4表示安全边界——两种虚线节奏刻意做得肉眼可辨。状态永远不是只靠颜色传达的，这是无障碍契约的一部分。

四、最聪明的一步：行为和布局分成两条轴

39 种类型听起来很多，但这个项目真正的架构亮点在语义模式路由。它把"系统做什么"（行为）和"信息怎么排"（布局）拆成两个独立轴：

• 7 种语义模式描述行为——扇入队列 / 瓶颈、阶段框架、非结构化输入→结构化产物、成对策略评估轨迹、安全铺设道路、治理 / 控制目录、补偿安全层；
• 每种模式路由到最接近的现有视觉类型去落地布局，模式自带语义原语和更严格的复杂度预算，但永远不引入新布局。

这是 ADR 0002（架构决策记录）定下的根本约束：语义模式永不扩展类型分类。想表达一种新行为？成本只是一个模式章节加一行路由表，而不是新类型参考 + 新模板 + 新示例的三件套。结果就是：类型数量稳定在 39，两个独立的校验脚本硬编码了这个计数，谁想悄悄加类型，CI 直接红。

对比一下同类工具的常见死法——每支持一种新场景就加一种新图表，类型表膨胀到没人能选——你会发现这条"反膨胀"约束的价值。分类增长被严格管控：2026 年 8 月 18 日矩形树图入册（27→28），19 日十种新布局语法集体入册（28→38），20 日极坐标图入册（38→39），每一次都有正式的 ADR 论证"为什么现有类型真的表达不了"。

五、60 秒品牌接入：给图表换上你公司的皮肤

默认皮肤好看，但真正让社区兴奋的是品牌接入：对着它说一句 "onboard diagram-design to https://你的网站"，它会：

1. 抓取你的主页（可采样多个页面合并信号）；
2. 提取调色板 + 字体栈——背景映射为paper，主文字色映射为ink，CTA / 链接色映射为accent字体映射为标题字族；
3. 做 AA 对比度校验（inkpaper≥ 4.5:1），8 色品牌会被强制折叠为三色体系；
4. 展示一份 diff 让你确认，然后改写style-guide.md

由于所有类型都通过 Token 角色取色，改一个文件，39 种图表全部换肤。深色变体都不用你操心——反转规则自动生成：浅色里任何rgba(墨, X)在深色里变成rgba(纸, X)，透明度不变，RGB 对调。

更细的是多客户支持。品牌皮肤可以保存为命名配置，存放在~/.diagram-design/profiles/（刻意放在安装目录外，插件更新不会冲掉）；项目根目录放一个只有一行profile: acme的.diagram-design标记文件，这个项目就永远走 Acme 的皮肤——并行服务多个客户互不干扰，标记文件甚至可以随 Git 仓库分发给协作者。安全细节也拉满：标记内容被当作不可信数据，格式不对就整个忽略，绝不当路径或指令解析。

还有一个贴心的"首次运行门槛"：在新项目里画第一张图前，如果样式指南还是出厂默认，它会先停下来问你"要接入品牌、手动贴 Token，还是就用默认？"——绝不在品牌项目里悄悄输出默认皮肤的图表。

六、四个旋钮 + 一本账：导入重绘的严谨超出预期

diagram-design 可以把存量 Mermaid 代码和 draw.io 文件重绘成出版级图表。注意是"重绘"而不是"转换"：提取器只读取内容（组件、关系、分组、方向），源坐标、源配色、源字体全部丢弃，然后按目标类型从空白画布重画。

重绘前要设定四个旋钮：

旋钮

管什么

档位

Format

交付格式

html / svg / png / html+png

Size

画布与字号阶梯

doc-inline、slide-16x9、social-og、print-a4 等 9 档

Detail

保留多少元素

faithful（≤24 节点）/ balanced（≤12）/ simplified（≤7）

Audience

措辞深浅

engineer / mixed / executive

其中 Audience 旋钮最能体现"编辑思维"：同一个认证节点，给工程师看是Auth Service · JWT · RS256 · :8443，给混合受众是Auth Service / token check，给高管则变成Sign-in——连箭头都会从POST /v2/orders退化成places order再退化成orders。细节减少不等于信息造假，它有两条铁律：绝不为了填空捏造细节；专有名词只能抽象成功能类别（Kafka → Message Bus 可以，Kafka → Event Grid 是事实错误）。

只要输出少于输入，就必须附一份保真度账本，例如：

Detail: balanced · 18 source nodes → 9 drawnMerged:  worker-01..06 → "Ingest Worker ×6"Collapsed: "Observability" group (Grafana, Loki, Tempo) → one nodeDropped: 2 sticky notes, CI pipeline (cross-cutting)Kept in full: the request path (Client → Gateway → Orders → Postgres)

理由很朴素：看图的人不知道缺了什么，但提需求的人需要知道。

安全方面同样较真。Mermaid 提取器把所有标签当惰性数据处理：%%{init}%%指令剥离、点击链接丢弃、标签里的提示词注入字符串原样当文本、样式指令全部拒绝——并且配了对抗性测试夹具逐一验证这些防御真的生效。

七、动效与无障碍：把"可选"做出"必修"的严谨度

输出默认是纯静态的。真想要动效，也只有三种被认可的模式：reveal（加载时一次性自动播放，播完即定格）、step（用户驱动的分步讲解）、loop（单个装饰性令牌的平静循环，周期 ≥3 秒）。反模式清单里明确写着：被禁止的不是"交互前的任何动效"，而是重复的、博眼球的自动播放。

工程上的关键决策是"单一固定控制器"（ADR 0001 + 0003）：所有动画文件只允许携带一个