还在手绘架构图？用 diagram-design 三分钟出图，架构评审会被你卷到

【免费下载链接】diagram-designEditorial diagram design for Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, and Pi. 44 diagram types. Self-contained HTML + SVG. No shadows. No Mermaid slop.项目地址: https://gitcode.com/GitHub_Trending/di/diagram-design

每次架构评审前最痛苦的不是改代码，而是「画图」：打开 draw.io 拖半小时框，被 Mermaid 的自动布局气到放弃，或者从 Figma 抄个模板回来改半天配色，最后 PPT 上一张图比系统本身还难看。diagram-design 这个开源项目给出的解法完全不同——它是一个挂载在 Claude Code、Codex、GitHub Copilot、Factory Droid、Pi 等 Agent 上的技能（skill），你只用自然语言描述系统，Agent 就会按一套写死的「编辑级设计规范」输出一份自包含的 HTML + SVG 架构图：无需构建、无阴影、无外部依赖，双击即可打开。

仓库 README 里有一句话说得非常坦白："No Mermaid slop"。它的目标不是像 Mermaid 那样输出「能渲染就行」的图，而是让 AI 直接产出你愿意放到博客、PPT 和评审现场的设计稿。这篇文章从仓库源码出发，拆解为什么架构图场景最适合它、如何三步完成从自然语言到成图，以及评审场景下它真正值钱的部分——可验证、可迭代、可交付。

架构图场景为什么最适合 diagram-design

架构图是所有技术图表中「信息密度」和「审美要求」同时拉满的类型：节点之间的依赖关系、信任边界、数据流向都不能错，而画出来的样子又要能让评审会上的非技术人员一眼看懂。社区里关于 diagram-design 的讨论也几乎都聚焦在架构图上——从「14 种专业图表一键生成」到「从画图工具人到图表设计者」，架构图都是被反复拿来当例子的场景。

先看它和主流工具的直接对比。README 的对比表把这个项目的立场讲得很清楚：

更关键的是它在「行为建模」层面做的抽象。SKILL.md 把图表拆成两层：语义模式（semantic pattern）描述系统做什么，44 种视觉类型描述信息怎么排布。架构图对应的行为场景被单独路由——例如「哪些路径跨越信任边界、哪些被拦截」会命中Secure paved road模式并路由到 Architecture 类型（见 skills/diagram-design/references/semantic-patterns.md）；一次系统快照里的组件与连接，则直接对应 type-architecture.md。这意味着 Agent 不是「画一个框一个箭头」，而是先判断你要表达的行为语义，再选布局语法。

从自然语言到架构图：三步实测

第一步：安装

diagram-design 本质是一个 Agent Skill，安装即把skills/diagram-design/下的 SKILL.md、references、assets 挂到你的 Agent 上。以 Claude Code 为例：

npx skills add cathrynlavery/diagram-design

或在 Claude Code 里通过插件市场安装：

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

Codex、GitHub Copilot、Factory Droid、Pi 都有对应的原生命令（README 的 Install 章节逐条列出）。装完后打开本地画廊 skills/diagram-design/assets/index.html，可以一次翻完 44 种类型的浅色 / 深色 / 全编辑三种变体。

第二步：用自然语言描述

安装只是开始，真正的工作发生在对话里。README 首页给了三个最典型的入口，架构图是第一个：

"Make me an architecture diagram of my app: frontend, backend, database, Redis cache."

Agent 会先做两件事：声明计划（SKILL.md §3 要求画之前用一句话讲清楚所选类型、尺寸预设、复杂度预算会裁掉什么），然后确认风格指南。首次在新项目使用时会触发「风格指南门」——如果style-guide.md还是默认 token，它会停下问你：要按网站自动取色、粘贴 token、加载保存的 profile，还是就用默认皮肤。这是该项目最反直觉也最讲究的一点：它拒绝静默地产出默认皮肤的图。README 的原话是：

Do not silently ship default-skinned diagrams into a branded project.

如果你说"Onboard diagram-design to https://yoursite.com"，技能会抓取站点首页、提取主色调和字体栈，映射成paper/ink/muted/accent/link五个语义角色，先给你看 diff、再写入style-guide.md（流程见 skills/diagram-design/references/onboarding.md）。整个 onboarding 约 60 秒。

第三步：拿到一份自包含的 HTML

产物始终是一个文件：内联 CSS + 内联 SVG，静态优先，唯一的网络请求是 Google Fonts（用系统字体则零请求）。双击就能打开。仓库里自带成品示例，比如 skills/diagram-design/assets/example-architecture.html 就是一个「Content site in production」架构图，下面这张是它的官方截图：

注意这张图的几个细节，它们全写在规范里：节点是 Geist 600 字重的名称 + Geist Mono 技术小字（端口、协议、路径）；HTTPS、SSR、READ MDX这类箭头标签都有不透明底色遮罩、不与线段重叠；唯一的强调色（burnt-tangerine）只给了 Astro Origin 一个焦点节点；底部是一条水平图例带而不是悬浮图例。这就是「编辑式设计系统」的落地效果。

分层建模：清单→分层→连线→规范

diagram-design 不会让你从白纸开始，它的 type 参考文件本身就是一套「分步施工图」。以架构图为例，type-architecture.md 按四步规定了建模顺序：

第一步，列清单，但要克制。复杂预算在 SKILL.md §7 里写死：单图默认≤9 节点、≤12 条连线、≤2 个强调色元素，超了就拆成 overview + detail 两张图。理念是 "The highest-quality move is usually deletion"——两个永远一起出现的节点就该合并成一个，布局上已经显而易见的关联就不该画箭头。

第二步，按层级或信任边界分组。布局约定要求组件按 tier 或信任边界分组（frontend → backend → data，或 public → private），主流向固定为从左到右或从上到下，二选一并保持。2 个以上同层节点用 zone 矩形框起来，zone 画在箭头和节点之前保证 z 序：背景 → zones → 箭头 → 节点。zone 填充是 2% 的 ink 浅染，标签永远用soft角色而不是给 ink 降透明度——因为透明度在不同paper上合成结果不可控（规范原文解释了为什么ink @ 0.40在暖色纸面上只有约 2.2:1 对比度）。

第三步，连线有六条强制规则。这是 SKILL.md §6 中最硬核的部分：

1. 非水平/垂直的连线只能用r=8的圆角直角拐弯（orthogonal），对角线直接判负；
2. 箭头标签要坐在不透明遮罩上，与线段保持 6–10px 间距，且永不落在线上；
3. 平行连线间距 ≥12px，交叉处用 bridge/hop 弧线让次要线让路；
4. 同一盒子边上的多条连线各占一个独立锚点，间距 ≥12px；
5. 连线不能穿越非终点盒子，实在绕不开才允许虚线 + 可见端标签；
6. 标签遮罩不能压住后画的节点。

type-architecture.md 给了具体的 SVG 写法，比如双拐角直角连线的 path：

<!-- right+down: from (x1,y1) to (x2,y2), mid = (x1+x2)/2 --> <path d="M x1,y1 H mid-8 Q mid,y1 mid,y1+8 V y2-8 Q mid,y2 mid+8,y2 H x2" fill="none" stroke="…" stroke-width="1.2" marker-end="url(#arrow)"/>

第四步，视觉规范兜底。4px 网格是硬规则：节点原点、宽高、间距、内边距全部能被 4 整除（style-guide.md里grid = 4）。字体角色严格分工：节点名用 Geist sans，端口 / 协议 / URL 这类技术小字用 Geist Mono，页面标题用 Instrument Serif，绝不出现 JetBrains Mono。accent只给 1–2 个焦点元素，多画 4 个强调色等于没做焦点决策。

评审场景的交付与迭代

架构评审真正考验的不是「画得漂亮」，而是改得快。diagram-design 在这条链上做了三层工程化，这是它区别于「AI 生成一张图」的地方。

第一层：三种变体对应三种交付场景

每张图都有三个静态变体（SKILL.md §10）：minimal light是截图即用的默认版；minimal dark给暗色站点和幻灯片；full editorial带标题、摘要卡和页脚，适合长文当 hero 图。评审 PPT 里放 light 或 dark，技术博客里放 full，同一个源不重画第二遍。

第二层：导入重绘 + 导出交付

评审材料经常是「旧图改新图」。README 的 Import 章节说明它可以重绘draw.io、Mermaid、Excalidraw 三种来源——内容保留（组件、关系、分组、方向），但源坐标、源配色、Mermaid 自动布局、Excalidraw 手绘几何全部丢弃，换成这套设计系统。下面这张就是官方示例：一个 12 节点的 draw.io 文件在balanced细节度下重绘的效果，源文件六个粉彩填充被收敛成一个 accent，手拖坐标变成了 4px 网格。

导入有四个拨盘（format / size / detail / audience），其中audience 改的是措辞而不是数量：同一个系统，对工程师是Auth Service / JWT · RS256 · :8443，对高管就是Sign-in。导入结束时还会输出一张fidelity ledger，如实报告哪些节点被合并、折叠或丢弃——你知道原图是什么样，它不糊弄你。

交付时用/diagram-design:export-diagram path/to/diagram.html，可导出 SVG（进 Figma / Illustrator）或 PNG（Playwright 渲染，默认 2×），也可以--scale=3出印刷级。尺寸预设按去处选择，slide-16x9投屏、social-og做链接卡片、print-a4-landscape打 A4（output-spec.md）。

第三层：可验证——这是评审会上的底气

评审最怕的是「图上这么画，实现对吗？」。diagram-design 把这句话做成了 CI 脚本：scripts/lint-skin.py校验皮肤、字体、无障碍与单文件安全；scripts/verify-geometry.py逐条检查 §6 的连线规则——有没有堆叠的连线、对角线、标签遮罩被后画的节点裁掉；scripts/verify-contrast.py计算每个文本 token 的 WCAG 对比度，要求文字 4.5:1、关键图形 3:1；打包产物用python3 scripts/self_check.py <file>自检。仓库的 CONTRIBUTING.md 列了 40 多项 gate，而普通用户生成完一张图后，跑一遍就是免费的质检。

评审里最常见的反问是「这张图能保证没人改坏吗」。README 对这个边界说得很诚实：它不是一个可编辑的源格式——没有文本可 diff，没有画布可拖拽。如果图要长期活在 Git 仓库里、每个 sprint 都变，Mermaid 依然更合适。diagram-design 的定位是「你要拿去发布的那张图」：评审会、技术博客、对外材料。所以正确的用法是：日常迭代用 Mermaid 或 draw.io 维护，评审定稿时把这张图交给 diagram-design 重绘、导出、进 PPT——三分钟拿到一张不会再被吐槽丑的架构图。

社区里有人把 diagram-design 称作「可编程图表系统」或「图表工程化范式」，但从仓库源码看，它的内核更朴素：把"品味"写成规范，让 AI 可重复执行。从 style-guide.md 的语义角色，到 SKILL.md 的复杂度预算和六条连线规则，再到 CI 里几十个 verifier，每一层都在做同一件事——让一张架构图既信息准确、又审美达标、还可被机器验证。下次评审前，试着把docs目录里的那张旧 drawio 交给它重绘一次，你会回来谢谢它的。

【免费下载链接】diagram-designEditorial diagram design for Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, and Pi. 44 diagram types. Self-contained HTML + SVG. No shadows. No Mermaid slop.项目地址: https://gitcode.com/GitHub_Trending/di/diagram-design