diagram-design 实测：让智能体画出编辑级示意图，单文件 HTML+SVG，告别 Mermaid 味

Mermaid 画图有个通病：语法倒是简单，输出却千篇一律——默认配色、默认箭头、默认字号，贴不进任何品牌，也谈不上"出版级"。drawio 能精修，但每一根线都要手拖。最近 GitHub 趋势榜上有个 5.2 万星的项目 diagram-design（MIT 协议），思路很不一样：它不给你一个新画板，而是给智能体立一套画图的规范——你用人话描述需求，agent 按规范产出一个自包含的 HTML 文件，内联 SVG，双击就能开。

我把仓库拉下来，读完它的规范，按规则亲手画了一张图。这篇是实测记录。

一、它到底是什么

diagram-design 是一个 Agent Skill（v2.6）：安装到 Claude Code、Cursor、Codex、Copilot 等任何支持 Agent Skills 的宿主里，之后你用自然语言说"给我画一个前端、后端、数据库、Redis 缓存的架构图"，agent 会选图型、说明计划，然后写出一个 .html 文件——样式全部内联，无外部依赖，无构建步骤。

它覆盖 45 种图型：架构图、流程图、时序图、状态机、ER 图、时间线、四象限、雷达图、桑基图、鱼骨图、甘特图等等。定位一句话：让 agent 画出设计师不会嫌弃的示意图。

安装：

npx skills add cathrynlavery/diagram-design

Claude Code 用户还可以走插件市场装，能拿到斜杠命令和后续更新。

二、规范里最值得抄作业的几条

我读完 SKILL.md（394 行）和 references/ 下的样式指南，挑几条对"画好一张图"最关键的：

1. 删减哲学：图不是加完为止，是删到不能再删

规范原话的精神是：每个节点必须是一个独立的想法，两个总是同时出现的节点就该合并；每条连线必须携带信息，布局已经说明白的线就删掉。目标密度 4/10——技术上完整，但不需要配说明书。超过 9 个节点，大概率应该拆成两张图。

2. 语义色板，不写死色值

所有颜色按语义角色引用：paper（纸面）、ink（墨色）、muted（次级）、accent（焦点）、link（外向调用）。默认皮肤是白灰纸面 + 焦黑墨色 + 焦橙点缀。accent 全网最多 1~2 个节点——它是"编辑性强调"不是"高亮笔"，五个节点都描边等于没强调。

3. 连线纪律：圆角直角是强制的

非水平/垂直的连接必须走两段弯的圆角正交路径（r=8），对角线直连是硬失败。出线必须垂直离开它起始的那条边；同一条边引出多条线时端口要错开。这些规则机械可检查，所以 agent 画出来的图连线不会"随手一拉"。

4. 对比度契约

正文文字对背景 ≥ 4.5:1，大字 ≥ 3:1，线条/箭头 ≥ 3:1——而且 accent 在两处用途不同（描边 + 文字），就按更严的 4.5:1 要求。仓库里有 verify-contrast.py 在 CI 里逐个 token 验算，不达标直接挂。翻译成人话：这套模板直接拿去贴品牌也不会产出"浅灰字白底"的丑图。

5. 分区有专门规矩

同层/同信任边界的节点用分区框起来，填充是 2% 的墨色淡洗（再浓就和节点底色打架），分区要先画保证层级顺序，眉标和节点之间留 ≥16px。

三、我的实测：按规范画一张「内容发布链路」

我选了最基础的架构图型，画一条内容发布链路：本地 Git 仓库 → CI 构建 → 产物打包 → 对象存储 → CDN 边缘节点 → 读者。严格执行上面的规矩：6 个节点（<9）、1 个焦点（CDN，全图唯一 accent）、1 个分区（构建与发布）、正交连线、外向交付用 link 色。

产物是一个 4.5KB 的 HTML 文件，完整源码如下（可直接保存为 .html 双击打开）：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>内容发布链路 · diagram-design 规范实测</title>
<style>
  :root{
    --paper:#f5f5f5; --paper-2:#ececec; --ink:#2d3142; --muted:#4f5d75;
    --soft:#5a6580; --rule:rgba(45,49,66,.12); --rule-solid:#bfc0c0;
    --accent:#bf4520; --accent-tint:rgba(191,69,32,.08); --link:#2e5aa8;
  }
  body{margin:0;background:var(--paper);font-family:"Segoe UI","Microsoft YaHei",sans-serif;}
  .wrap{width:1000px;margin:0 auto;padding:36px 20px 44px;}
  h1{font-size:20px;color:var(--ink);margin:0 0 4px;font-weight:650;}
  .cap{font-size:13px;color:var(--soft);margin:0 0 28px;}
  svg{display:block;}
  .n-title{font-size:14px;fill:var(--ink);font-weight:600;}
  .n-sub{font-size:11px;fill:var(--soft);}
  .edge{stroke:var(--muted);stroke-width:1.5;fill:none;}
  .edge-ext{stroke:var(--link);stroke-width:1.5;fill:none;}
  .zone-eyebrow{font-size:11px;fill:var(--soft);letter-spacing:.08em;}
</style>
</head>
<body>
<div class="wrap">
<h1>内容发布链路</h1>
<p class="cap">从本地仓库到读者：六个节点、一个焦点、一个分区 —— 按 diagram-design 规范绘制</p>
<svg width="960" height="300" viewBox="0 0 960 300" xmlns="http://www.w3.org/2000/svg">
  <!-- 分区（先画：bg → zones → arrows → nodes） -->
  <rect x="196" y="72" width="352" height="116" rx="10" fill="#2d3142" fill-opacity="0.02" stroke="rgba(45,49,66,.12)" stroke-width="1"/>
  <text class="zone-eyebrow" x="212" y="94">构建与发布（CI）</text>

  <!-- 连线：圆角直角，两段弯 r=8；水平直线段允许直连 -->
  <defs>
    <marker id="ah" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M0,0 L10,5 L0,10 z" fill="#4f5d75"/>
    </marker>
    <marker id="ah-ext" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
      <path d="M0,0 L10,5 L0,10 z" fill="#2e5aa8"/>
    </marker>
  </defs>

  <!-- 本地 → CI -->
  <path class="edge" d="M170,130 L206,130" marker-end="url(#ah)"/>
  <!-- CI → 打包 -->
  <path class="edge" d="M346,130 L382,130" marker-end="url(#ah)"/>
  <!-- 打包 → 对象存储 -->
  <path class="edge" d="M528,130 L564,130" marker-end="url(#ah)"/>
  <!-- 对象存储 → CDN -->
  <path class="edge" d="M710,130 L746,130" marker-end="url(#ah)"/>
  <!-- CDN → 读者（外向交付，link 色） -->
  <path class="edge-ext" d="M812,194 L812,228" marker-end="url(#ah-ext)"/>

  <!-- 节点（后画，压住连线端部） -->
  <!-- 本地 Git 仓库 -->
  <rect x="40" y="98" width="130" height="64" rx="8" fill="#f5f5f5" stroke="#bfc0c0" stroke-width="1.5"/>
  <text class="n-title" x="105" y="126" text-anchor="middle">本地 Git 仓库</text>
  <text class="n-sub" x="105" y="146" text-anchor="middle">源码与静态资源</text>

  <!-- CI 构建 -->
  <rect x="206" y="98" width="140" height="64" rx="8" fill="#f5f5f5" stroke="#bfc0c0" stroke-width="1.5"/>
  <text class="n-title" x="276" y="126" text-anchor="middle">CI 构建</text>
  <text class="n-sub" x="276" y="146" text-anchor="middle">安装依赖 · 生成产物</text>

  <!-- 产物打包 -->
  <rect x="382" y="98" width="146" height="64" rx="8" fill="#f5f5f5" stroke="#bfc0c0" stroke-width="1.5"/>
  <text class="n-title" x="455" y="126" text-anchor="middle">产物打包</text>
  <text class="n-sub" x="455" y="146" text-anchor="middle">zip / tar，带哈希校验</text>

  <!-- 对象存储 -->
  <rect x="564" y="98" width="146" height="64" rx="8" fill="#f5f5f5" stroke="#bfc0c0" stroke-width="1.5"/>
  <text class="n-title" x="637" y="126" text-anchor="middle">对象存储</text>
  <text class="n-sub" x="637" y="146" text-anchor="middle">版本化 · 可回滚</text>

  <!-- CDN 边缘（唯一焦点：accent 描边 + tint 底） -->
  <rect x="746" y="98" width="132" height="64" rx="8" fill="rgba(191,69,32,.08)" stroke="#bf4520" stroke-width="2"/>
  <text class="n-title" x="812" y="126" text-anchor="middle">CDN 边缘节点</text>
  <text class="n-sub" x="812" y="146" text-anchor="middle">缓存 · 就近分发</text>

  <!-- 读者 -->
  <rect x="746" y="230" width="132" height="56" rx="8" fill="#f5f5f5" stroke="#bfc0c0" stroke-width="1.5"/>
  <text class="n-title" x="812" y="255" text-anchor="middle">读者</text>
  <text class="n-sub" x="812" y="272" text-anchor="middle">浏览器直接打开</text>
</svg>
</div>
</body>
</html>

实际渲染效果：白灰纸面、焦黑文字、CDN 节点焦橙描边 + 淡橙底，分区是 2% 墨色淡洗，连线全部圆角直角。整个过程我的输入只有一句"画一条内容发布链路架构图，遵守规范"，选型、布局、配色都是 agent 按规范完成的。

四、适合谁，边界在哪

适合：重度使用 Claude Code / Cursor 等 agent 工作流的人——README、周报、技术方案里要插图时，一句话出图，风格稳定；对"图要贴品牌"的团队，它的 onboarding 支持传一个网址自动提取你的色板和字体。

边界：它是个技能不是编辑器——精细调节最终还是回到改 HTML（好在是纯文本，好改）；支持从 drawio/Mermaid/Excalidraw 导入（有专门 prompt），导出 PNG/SVG 要走它给的命令；45 种图型各自有参考文档，选型靠 agent 匹配，极端冷门的图型效果看运气。

五、小结

Mermaid 解决"能画出图"，diagram-design 解决"画出的图能见人"。它的核心资产不是代码而是那套写进 SKILL.md 的设计规范——删减、语义色板、连线纪律、对比度契约——这套规矩本身对所有"要让 agent 生成 UI 产出"的场景都有参考价值。MIT 协议，试一下的成本只有一个 npx。

参考与署名：本文实测项目为 cathrynlavery/diagram-design（MIT License，v2.6，2026-10-13 克隆）；文中示例图为笔者按其规范绘制，非项目官方配图。