diagram-design

学习要有三心，一信心，二决心，三恒心。—— 陈景润

Diagram Design：让技术图不再像模板拼装，而像一篇真正被设计过的编辑作品

项目地址：https://github.com/cathrynlavery/diagram-design

一张图，常常比一段长篇解释更快抵达读者。

架构如何连接，流程在哪里分叉，数据怎样流动，团队如何协作，时间如何推进，系统边界在哪里，复杂问题往往需要借助视觉结构才能被真正看清。

但现实中的技术图，常常陷入两种尴尬。

一种是内容很对，视觉却像从默认组件库里匆忙拼出来的。圆角卡片、阴影、渐变、密集的连线和随处可见的颜色，让读者还没理解结构，就先被视觉噪声拖住。

另一种是画面很漂亮，却缺乏准确性。它像一张精致海报，却没有承担信息组织的职责。

Diagram Design 想解决的，正是这个中间地带的问题。

它是一套面向 Claude Code、Codex 与 Pi 的图表设计技能。它不把图当作随手生成的装饰，也不把技术结构塞进千篇一律的模板，而是尝试用一套带有编辑感的设计系统，把复杂内容整理成清晰、克制、可阅读的视觉表达。

它的目标并不是制造更多图，而是让每一张图都值得被画出来。

图表不是附属品，而是信息的第二种语言

Diagram Design 有一个非常鲜明的立场：图表应该帮助读者理解，而不是制造阅读负担。

因此，它强调删除。

每一个节点都需要证明自己有存在的必要。重点不应被平均分配，强调色只保留给最值得读者第一眼注意的一到两个元素。整体密度保持克制，让空白也成为信息结构的一部分。

这是一种很像编辑工作的思路。

编辑不会把所有句子都加粗，也不会让每一段都成为标题。真正重要的内容，往往需要周围留出空间，才能显现出它的重量。

Diagram Design 也试图把这种节奏带进图表。

一张好的图不该让人感觉“元素真多”，而应该让人感觉“原来事情是这样”。

不只画流程图，而是覆盖多种信息结构

不同的信息，需要不同的视觉结构。

系统组件与连接关系，适合用架构图表达。

带有判断分支的执行逻辑，适合用流程图表达。

多方之间随时间展开的消息传递，适合用时序图表达。

实体、字段与关联关系，适合用数据模型图表达。

Diagram Design 提供了覆盖多种场景的视觉类型，包括：

• 架构图
• 流程图
• 时序图
• 状态机图
• ER 与数据模型图
• 时间线
• 泳道图
• 象限图
• 嵌套层级图
• 树状图
• 组织架构图
• 韦恩图
• 层级堆栈图
• 金字塔与漏斗图
• 顾问式二维矩阵
• 雷达图
• 循环图
• IT 现状图
• 高层级系统图
• 柱状图
• 折线图
• 甘特图
• 散点图
• 多参与者流程图
• 数据分层图
• 数据流图
• 数据平台集成图
• 数据权限矩阵图

这些类型并不是为了让图表目录看起来更丰富。

它们对应的是不同的表达任务。

当你想解释应用前端、后端、数据库与缓存的关系，架构图能够把组件与连接摆在正确的位置。

当你想解释一次认证调用在令牌失效后如何刷新，时序图能够让交互顺序变得可见。

当你想展示项目在影响与投入之间的位置，象限图比一段解释更直接。

当你想描述跨部门工作如何传递，泳道图能够把责任边界和流程顺序同时呈现出来。

图的类型不是装饰选择，而是信息结构的选择。

先理解行为，再决定布局

Diagram Design 的一个核心设计，是把行为模式与视觉布局分开。

通常，人们画图时会先问：“我要画流程图还是架构图？”

但有些内容真正重要的，不是它表面上属于什么图，而是它要表达的行为。

例如，一个队列可能表现为多个输入汇聚到一个瓶颈。

一个政策追踪过程可能需要呈现规则、判断、分支与后续路径。

一个信任边界可能需要强调信息或请求跨越不同区域时的约束。

这些内容如果只从图表类型开始选择，很容易落入形式正确、语义模糊的结果。

Diagram Design 会先判断行为模式，再选择合适的视觉类型。

这样，队列、策略追踪、信任边界、重复阶段、非结构化输入等行为，可以使用最贴近自身语义的表达方式，而不是被强行塞进同一种布局里。

图表不只是摆放节点。

图表是在呈现系统如何运作。

一张 HTML 文件，就是完整的图

Diagram Design 的输出形式非常直接。

图表以自包含的 HTML 与 SVG 形式存在。

不需要构建步骤，不依赖 JavaScript，不要求额外图片资源。打开一个 HTML 文件，就可以在浏览器中查看图表。

这带来了一种很轻盈的使用体验。

图不是某个在线工具中的临时状态，也不是需要复杂环境才能重现的工程产物。它可以作为单独文件被保存、交付、分享与归档。

项目提供了不同风格的静态模板，包括极简浅色版本、极简深色版本，以及带有编辑式摘要卡片的完整版本。

cp skills/diagram-design/assets/template.html my-diagram.html

cp skills/diagram-design/assets/template-full.html my-diagram.html

cp skills/diagram-design/assets/template-motion.html my-diagram.html

极简模板适合希望让图表专注于结构本身的场景。

完整编辑版本则在图之外增加了摘要卡片与内容层级，适合文章、说明页与更完整的叙事表达。

带有动态效果的模板则提供可选动画能力，同时保留静态输出作为默认状态。

为品牌而生，而不是强迫品牌适应模板

很多图表系统默认假设：所有人都应该使用同一套颜色、同一组字体、同一种视觉语言。

Diagram Design 不想走这条路。

它提供品牌接入流程，让技能读取网站主页中的视觉信息，并将其映射为图表中的语义化设计令牌。

网站背景色可以成为图表纸张颜色。

正文主色可以成为图表墨色。

次级文本可以成为辅助文字颜色。

卡片与容器颜色可以成为第二层纸张颜色。

网站中最常使用的品牌色可以成为强调色。

标题字体、正文字体与代码字体，也可以分别映射到图表中的标题、节点名称与技术标签。

整个过程并不是把网页截图后随便提取几种颜色，而是把视觉信息整理成明确的角色。

paper
ink
muted
accent
link

当这些令牌被写入风格指南后，后续生成的图表就能够延续网站已有的视觉气质。

网站的纸张颜色，会成为图表背景。

网站中最明显的行动色，会成为图表的视觉焦点。

网站正文使用的字体，会进入节点标签体系。

这样生成出来的图，不再像某个外部工具突然插入页面的陌生组件，而更像内容本身自然延伸出来的一部分。

品牌接入并不只是配色

真正的品牌一致性，并不只是换掉默认蓝色。

Diagram Design 在接入过程中还会记录颜色角色、字体族、字体权重、字体来源与备用方案。

同时，它会检查文字与背景之间的对比度。

对于图表中的小字号文字，颜色看起来好看并不够。它还需要具有足够的可读性。

如果检测到某种颜色在图表尺寸下无法满足可读性要求，系统会提出调整后的建议值，并说明原因。

这让图表设计不只追求“像品牌”，也追求“读得清”。

可访问性被放进 SVG 的结构里

一张图常常承担大量信息。

如果图表只依赖视觉呈现，那么无法直接看到图的人就会被排除在理解之外。

Diagram Design 为每一张图的内联 SVG 提供可访问性结构。

图表会带有可访问名称与描述，使用 role="img"、aria-labelledby、title 与 desc 等结构，让屏幕阅读器能够识别图表的标题和说明。

同时，不同图表中的标识符会使用前缀，避免多个图表出现在同一页面时发生冲突。

这种设计看起来像细节，但它实际上决定了图是否真正具备完整的信息表达能力。

图不是只服务于视觉浏览者的装饰。

图应该是一种可以被理解的信息载体。

动画是可选能力，不是强制特效

动态图表很容易陷入一个误区：为了显得高级，让所有元素都动起来。

Diagram Design 对动画保持克制。

动画不是新的图表类型，而是一层可选行为。项目定义了 none、reveal、step 与 loop 等动画模式。

静态输出仍然是默认状态。

对于偏好减少动态效果的用户，图表会呈现完整静态画面。

这意味着动画不会成为理解内容的必要条件。

如果动画存在，它应该帮助读者理解过程、顺序和循环，而不是把原本清晰的结构变成不断跳动的界面。

在导出动态图表时，也可以通过显式静态状态捕捉最终画面。

从一句自然语言开始生成图表

Diagram Design 可以通过自然语言请求被调用。

例如，用户可以直接描述自己想解释的结构：

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

I need a quadrant showing Q2 projects by impact vs effort.

Give me a sequence of a bearer call with token refresh on 401.

Agent 会根据请求选择合适的类型，构建 HTML，并保存输出文件。

这一过程的重点不只是自动生成。

更重要的是，Agent 会根据图表任务选择合适的表达方式，而不是把所有问题都画成同一种盒子和箭头。

让旧图重新拥有设计质量

很多团队已经有了历史图表。

它们可能来自 draw.io、diagrams.net 或 Mermaid。

这些图中包含真实的系统结构、流程关系和业务信息，只是视觉上可能过于拥挤、配色杂乱、坐标手工拖拽、连线交错，或者不适合直接放进文章、演示文稿与正式文档。

Diagram Design 提供导入与重绘能力。

它不会把旧图原样搬运，而是读取内容后重新绘制。

/diagram-design:import platform.drawio

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

/diagram-design:import platform.drawio --detail=faithful --format=png --page=all

/diagram-design:import-mermaid README.md --diagram=all

/diagram-design:import-mermaid architecture.mmd --size=slide-16x9 --detail=simplified

它支持常见的 draw.io 文件容器，包括 .drawio、.drawio.xml、.drawio.png 与 .drawio.svg。

对于 Mermaid，它支持 .mmd、.mermaid，以及 Markdown 中的 Mermaid 代码块。

导入 Mermaid 时，项目会解析文本内容，不依赖渲染、浏览器、网络或跟随外部点击目标。

这让重绘过程更专注于结构本身。

组件、关系、方向、标题、分组与语义边界会被保留。

原始坐标、原始配色、原始字体、杂乱连线与自动布局结果则不会被直接继承。

换句话说，Diagram Design 想保留的是原图说了什么，而不是原图如何把内容挤在画布上。

四个调节器，决定图最终应该长什么样

同一张源图，放进不同场景时，不该拥有完全一样的形态。

给工程团队看的系统图，可以保留更多技术细节。

给管理层展示的系统图，则可能更适合突出关键能力和业务路径。

放进文档中的图，需要适应阅读宽度。

放进演示文稿中的图，需要适应屏幕比例。

放进社交媒体中的图，需要在更小的画面中保留核心重点。

Diagram Design 使用四个维度来控制导入与重绘后的结果。

调节器	可选方向	作用
格式	HTML、SVG、PNG、HTML 与 PNG	决定最终交付形式
尺寸	文档内嵌、宽文档、十六比九幻灯片、四比三幻灯片、社交卡片、打印页面等	决定画布与排版密度
细节	faithful、balanced、simplified	决定保留多少源信息
受众	engineer、mixed、executive	决定用词与表达层级

其中，细节控制尤其有趣。

faithful 模式适合保留更多节点与区域。

balanced 模式会进行适度整理。

simplified 模式则进一步收束内容，只留下最关键的结构。

系统还会生成保真记录，明确说明哪些内容被合并、折叠、删除或完整保留。

Detail: balanced · 12 source nodes → 8 drawn
Collapsed: "Token valid?" decision → edge label on Gateway → Auth
Dropped:   1 sticky note
Kept in full: the request path

这让简化不再是一种悄无声息的删减。

读者和作者都能知道，原始结构在什么地方被重新组织过。

导出为 SVG 与 PNG

虽然 Diagram Design 的图以自包含 HTML 形式存在，但它也支持将图本身导出为 SVG 或 PNG。

这让图表可以进入更多使用场景。

SVG 适合被放进 Figma、Illustrator 或其他支持矢量图的工具中。

PNG 适合幻灯片、社交媒体卡片和需要固定像素输出的场景。

/diagram-design:export path/to/diagram.html

/diagram-design:export path/to/diagram.html --svg-only

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

SVG 导出会提取图中的 <svg> 节点，并注入 Google Fonts，使其能够在浏览器、Figma 与 Illustrator 中独立渲染。

PNG 导出则通过 Playwright 进行栅格化，默认使用两倍缩放。

pip install playwright
playwright install chromium

导出的 SVG 和 PNG 会聚焦于图本身，不包含完整编辑版中额外的标题区域与摘要卡片。

这种区分很合理。

图本身可以被放到各种载体中，而完整编辑版则更适合作为独立内容页面的一部分。

渐进式加载，让 Agent 不必一次读完所有规则

Diagram Design 的目录结构背后，有一个很实用的原则：渐进式披露。

当 Agent 刚启动时，它不需要立即读取所有图表类型、所有导入规则、所有动画定义和所有设计原语。

它先看到技能名称与描述。

当请求匹配到图表任务时，才加载核心技能说明。

如果用户需要流程图，再加载流程图对应的参考文件。

如果请求涉及策略追踪或其他行为模式，再加载语义模式参考。

如果请求需要动画，再额外加载动画规则。

这种机制让 Agent 在处理日常图表任务时，保持更紧凑的上下文。

例如：

请求内容	需要加载的内容
制作流程图	核心技能说明与流程图参考
制作架构图	核心技能说明与架构图参考
对比两条策略请求为何不同	核心技能说明、语义模式参考与流程图参考
为策略追踪添加动画	已选内容与动画参考
将技能接入网站品牌	核心技能说明、接入流程与风格指南
重绘 draw.io 文件	核心技能说明、draw.io 导入规则、输出规格与目标图类型参考
重绘 Mermaid 图	核心技能说明、Mermaid 导入规则、输出规格与目标图类型参考

图表种类再多，也不意味着每一次都要加载全部知识。

用户需要什么，Agent 就只读取完成当前任务所需的那一部分。

设计系统的克制，不是风格限制，而是阅读纪律

Diagram Design 的设计系统遵循一个简洁但明确的原则。

一张图只保留一种强调色。

强调色只服务于最需要优先关注的一到两个元素。

标题、节点名称与技术子标签使用不同字体角色。

细边框、较小圆角、充足留白、受控的箭头形式，共同构成图表的基础秩序。

项目中还提供了一些可选原语。

注释标注使用斜体标题字体与虚线贝塞尔引导线，适合把编辑性旁注放在图的边缘。

手绘滤镜使用 SVG 扰动与位移效果，适合文章与叙事性内容，而不适合严肃技术文档。

图标集合包含多种单色 IT 与云计算图标，可用于丰富架构图与时序图中的表达。

这些原语并不是为了让图变得更复杂。

它们存在的前提，是能帮助图表达更多必要信息。

有些时候，不画图反而更好

Diagram Design 对图表保持了一个难得的自我克制。

它明确指出，并不是所有内容都值得被画成图。

如果只是要列出项目，表格或项目符号通常更清楚。

如果只是进行前后对比，表格往往比图更高效。

如果只有一个形状和一句标签，那么直接写成一句话可能更好。

如果只是想发一条终端风格的短内容，简单的 Unicode 图可能更合适。

在真正开始绘制之前，应该先问一个问题：

读者能否从图中学到比一段写得很好的文字更多的东西？

如果答案是否定的，那么不画图，可能才是最好的设计决定。

质量检查，让输出不仅好看，也保持可靠

Diagram Design 并不把图表质量只交给视觉判断。

项目中提供了多项检查机制。

在新增示例前，可以运行皮肤检查工具。

python3 scripts/lint-skin.py <your-new-example.html>

对示例与模板进行整体检查时，可以使用：

python3 scripts/lint-skin.py --all --baseline

生成图表后，也可以使用自检脚本验证文件。

python3 skills/diagram-design/scripts/self_check.py <file>

项目中的检查会关注图表皮肤、语义路由、动画示例结构、可访问性、动态图控制协议、远程资源限制、draw.io 导入路径、Mermaid 导入路径与文档同步。

在可访问性方面，检查会拒绝缺少有效可访问名称的 SVG，也会拒绝空的或放错位置的标题与描述。

对于动态图，还会约束控制器结构与资源使用方式。

这些规则让 Diagram Design 不只是提供一组漂亮示例，也尝试把图表质量沉淀为可以持续验证的工程标准。

一张图应该像一篇编辑过的文章

Diagram Design 最有意思的地方，或许不在于它支持多少种图表类型，也不在于它可以导入多少种格式。

它真正传递的是一种图表观。

图不是节点与箭头的堆叠。

图不是把所有信息塞进画布。

图不是默认模板的重复使用。

图应该有主题，有视觉重点，有删减，有语气，也有明确的受众。

它应当像一篇写得好的文章。

有标题，有结构，有重点，有留白。

它知道哪些内容必须出现，也知道哪些内容不该挤进来。

当架构、流程、数据、组织、策略与时间线都需要被解释时，Diagram Design 提供的不是一台只会生成方框的机器。

它提供的是一套让信息拥有编辑质量的视觉表达方式。