1. 从一张草图到一套系统：diagram-design 到底在解决什么问题
第一次看到 “diagram-design” 这个标题，很多人会以为它只是教你怎么把流程图做得好看一点。但真正在项目里画过架构图、部署图、数据流图的人都知道，图的美观只是最表层的事。真正让人头疼的，是图画完之后没人看得懂、改一个节点要动五个地方、不同人画出来的风格完全不统一、评审会上大家对着同一张图却理解出三种意思。
diagram-design 这个项目，核心就是要把“画图”这件事从个人审美行为，变成一套可复用、可协作、可维护的设计系统。它不是一个单纯的绘图工具教程，也不是某个冷门软件的说明书，而是一套围绕“图”的完整设计方法论——包括图元规范、布局逻辑、色彩语义、标注体系、版本管理，以及在不同场景下如何选择最合适的表达方式。
我做过不少内部系统文档和对外技术方案的配图工作，踩过的坑可以说非常密集。早期我习惯打开工具直接拖框、连线、调色，一张图磨两三个小时，结果评审时被问“这个虚线框代表什么”“为什么这两个模块颜色一样但层级不同”，当场卡壳。后来我才意识到，图不是画给自己看的，它是信息传递的载体。diagram-design 要解决的，就是让这个载体变得可靠、可读、可维护。
这篇文章适合几类人看：一是经常需要输出架构图、流程图、时序图的技术同学；二是需要统一团队文档配图规范的技术负责人；三是对可视化表达有要求的产品、设计、运营同学；四是单纯觉得自己画的图“总差点意思”的任何人。不管你现在用的是哪款绘图工具，这套思路都能直接迁移过去。
接下来我会从整体设计思路、核心细节拆解、实操落地流程、常见问题排查四个大块展开，中间会穿插我自己的踩坑记录和参数选择逻辑。你可以把它当成一份 diagram-design 的实战手册，也可以当成一次关于“如何用图讲清楚一件事”的系统复盘。
2. 整体设计思路：为什么图需要一套“设计系统”
2.1 图的本质是信息压缩，不是美术创作
很多人画图时第一反应是“怎么好看”，但 diagram-design 的第一原则是“怎么准确”。一张架构图如果颜色很漂亮但层级混乱，它的价值是负的——因为它会让读者产生错误理解。图本质上是一种信息压缩格式：把一段文字描述、一套系统关系、一个流程逻辑，压缩成二维平面上的节点和连线。
既然是压缩，就必然有损。设计系统的作用，就是控制“损”在哪里、损多少。比如：
- 用实线表示同步调用，虚线表示异步消息，这是语义约定；
- 用圆角矩形表示服务，直角矩形表示外部系统，这是形状约定；
- 用冷色表示数据层，暖色表示业务层，这是色彩约定。
这些约定一旦固定下来，读者就不需要每次重新学习。diagram-design 的整体思路，就是先建立约定，再在约定内做表达。这跟写代码先定接口规范是一个道理。
2.2 三层结构：图元层、布局层、语义层
我在实际项目中把 diagram-design 拆成三层来理解，这个分层方式帮我解决了很多选择困难。
第一层是图元层，也就是最小的视觉单元：矩形、圆形、菱形、箭头、文字标签。这一层要解决的是“用什么形状表达什么类型的对象”。比如在我的规范里，所有“服务”统一用圆角矩形，所有“数据存储”统一用圆柱体，所有“外部依赖”统一用虚线边框矩形。这样读者扫一眼形状就能分类。
第二层是布局层，解决的是“东西放在哪里”。常见布局有分层布局（从上到下表示调用层级）、分组布局（用背景框把相关模块圈起来）、流向布局（从左到右表示数据流动）。布局的核心不是好看，而是让读者的视线路径和系统的逻辑路径一致。
第三层是语义层，解决的是“颜色、线型、标注代表什么”。这一层最容易被忽略，但也最容易出问题。比如红色到底表示“错误”还是“高优先级”还是“核心模块”？如果不提前定义，同一套图里红色会出现三种含义，读者直接崩溃。
2.3 为什么不用“一套模板走天下”
有人会问：既然要统一，那直接做一套模板所有图都用不就行了？我试过，结论是不行。因为不同图种的表达目标完全不同：
| 图种 | 核心目标 | 布局重点 | 常见误区 |
|---|---|---|---|
| 架构图 | 展示系统组成与关系 | 分层、分组 | 节点过多，连线交叉 |
| 流程图 | 展示步骤与分支 | 流向、判断节点 | 分支条件不标注 |
| 时序图 | 展示交互顺序 | 时间轴、消息编号 | 消息顺序混乱 |
| 数据流图 | 展示数据流转 | 数据源、处理节点 | 混淆控制流与数据流 |
| 部署图 | 展示物理/逻辑部署 | 环境边界、集群 | 环境层级不清 |
diagram-design 的做法是：底层约定统一（图元、色彩语义、字体、线型），上层模板按图种分化。这样既保证了整体一致性，又不会让架构图被迫套用流程图的布局逻辑。
2.4 工具选型：别让工具限制你的设计系统
关于工具，我的观点很明确：diagram-design 是方法论，不是某个软件的功能。你可以用任何工具实现它。我实际用过的组合包括：
- 代码化绘图：适合需要版本管理、频繁修改的场景，图是文本，可以 diff、可以 review；
- 在线白板类工具：适合头脑风暴和快速草图，但不适合最终交付；
- 传统桌面绘图软件：适合精细排版和导出高精度图片，但协作性差；
- 文档内嵌绘图：适合和文档一起维护，但复杂图会很难受。
我的建议是：草图阶段用白板类工具快速试错，定稿阶段用代码化或桌面工具精细输出，最终交付统一导出为矢量格式（SVG 或 PDF），避免位图放大模糊。工具选型的关键不是哪个流行，而是哪个能让你把上面三层结构落地。
3. 核心细节解析：图元、色彩、连线与标注的实操规范
3.1 图元设计：形状即语义
图元层最核心的原则是“形状即语义”。什么意思？就是读者不需要看图例，光看形状就能猜出对象类型。我在项目里固定了一套图元映射：
- 圆角矩形：业务服务、应用模块；
- 直角矩形：外部系统、第三方依赖；
- 圆柱体：数据库、缓存、消息队列等存储组件；
- 菱形：判断节点、条件分支；
- 平行四边形：输入输出、数据源；
- 圆形：起点或终点；
- 虚线边框：逻辑分组或可选组件。
这套映射不是随便定的，它参考了常见工程图的习惯，同时控制了形状总数不超过七种。为什么是七种？因为人的短期记忆容量有限，超过七种形状读者就需要频繁回看图例，阅读流畅度直线下降。
注意：图元形状一旦在团队内确定，就不要轻易增加。每增加一种形状，所有历史图的理解成本都会上升。
3.2 色彩语义：颜色不是装饰，是信息维度
色彩是 diagram-design 里最容易翻车的部分。我见过太多图，颜色纯粹为了“好看”，结果读者完全不知道颜色代表什么。我的做法是：颜色必须绑定语义，且语义数量控制在三到五个维度。
比如一套典型的色彩语义表：
| 颜色 | 语义 | 使用场景 |
|---|---|---|
| 蓝色系 | 核心业务 | 主服务、主流程节点 |
| 绿色系 | 数据与存储 | 数据库、缓存、数据流 |
| 橙色系 | 外部依赖 | 第三方接口、外部系统 |
| 灰色系 | 辅助与背景 | 分组框、注释、非重点 |
| 红色系 | 风险与异常 | 错误分支、告警节点、待办 |
这里的关键是：同一张图里，红色只能表示一种含义。如果红色既表示错误又表示核心，读者就会混淆。如果确实需要表达多个维度，就用“颜色+线型”或“颜色+形状”组合，而不是增加颜色数量。
另外，色盲友好也要考虑。红绿对比对部分人群不友好，所以我通常会用蓝色和橙色作为主要对比色，红色只用于真正的异常提示。
3.3 连线规范：箭头方向、线型与交叉处理
连线是图的血管，但也是最容易被忽视的部分。diagram-design 对连线有几条硬性规范：
第一，箭头方向必须明确。同步调用用实线箭头，异步消息用虚线箭头，数据流用带空心三角的箭头。不要出现没有箭头的线，那等于没说清楚关系方向。
第二，线型要有区分度。实线表示强关系（直接调用、同步依赖），虚线表示弱关系（异步、可选、逻辑关联），点线表示推测或待确认关系。线型种类同样控制在三种以内。
第三，交叉处理要克制。连线交叉是架构图最大的可读性杀手。我的经验是：如果一张图交叉超过五处，就应该考虑拆分或重新布局。处理交叉的常用手段包括：调整节点顺序、使用跳线符号、把部分关系移到注释里、拆成多张子图。
第四，连线标签要短。标签超过六个字就会挤压空间，建议用缩写或编号，然后在图例或注释里展开说明。
3.4 标注体系：让图自己会说话
标注是 diagram-design 里最体现功力的部分。一张好图应该做到“自解释”——读者不需要问你，就能看懂大部分内容。标注体系包括：
- 标题：图的名称，必须包含范围和版本；
- 图例：解释形状、颜色、线型的含义；
- 编号：给节点和连线编号，方便在文档正文中引用；
- 注释：对特殊设计决策的说明，用灰色小字放在角落；
- 版本信息：日期、作者、变更摘要。
我特别想强调编号系统。很多图评审时大家说“那个左边的服务”，结果左边有三个服务，根本对不上。如果每个节点有编号（比如 S1、S2、D1、D2），评审时直接说“S3 到 D2 的调用为什么是异步的”，沟通效率会高很多。
实操心得：编号规则建议用“类型首字母+序号”，比如 S 代表 Service，D 代表 Database，E 代表 External。这样编号本身也携带语义。
4. 实操落地：从需求到成图的完整流程
4.1 第一步：明确图的读者和目的
在动手画任何一笔之前，先回答三个问题：
- 这张图给谁看？是给开发同事看细节，还是给管理层看全局？
- 这张图要回答什么问题？是展示系统组成，还是解释某个流程？
- 这张图会在哪里使用？是放在文档里，还是评审会上投屏？
这三个问题决定了图的详细程度和布局方式。给管理层看的图，节点不超过十五个，重点突出层级和边界；给开发看的图，可以到三十个节点，但要保证连线清晰。投屏用的图，字体要大，颜色对比要强；文档里的图，可以信息密度更高。
我踩过的坑是：一张图想同时满足所有人，结果谁都不满意。后来我学会了按读者分层出图——先出一张全局概览图，再按模块出细节图，用编号关联。
4.2 第二步：先列节点和关系，再考虑布局
很多人习惯打开工具直接拖框，这是效率最低的做法。我的流程是：
- 在文本编辑器里列出所有节点，每个节点一行，标注类型；
- 列出所有关系，格式为“源节点 -> 目标节点：关系说明”；
- 检查节点和关系是否有遗漏或冗余；
- 根据关系密度决定布局方式。
这个文本化的步骤看起来笨，但它能避免你在绘图工具里反复调整。节点和关系确定后，布局就是水到渠成的事。
比如一个典型的微服务架构，文本清单可能是：
S1 网关服务 S2 用户服务 S3 订单服务 S4 支付服务 D1 用户数据库 D2 订单数据库 E1 支付外部接口 关系： S1 -> S2：同步调用 S1 -> S3：同步调用 S3 -> S4：同步调用 S2 -> D1：读写 S3 -> D2：读写 S4 -> E1：同步调用有了这个清单，布局时自然会把 S1 放最上面，S2/S3/S4 放中间层，D1/D2 放下面，E1 放右侧。连线方向也一目了然。
4.3 第三步：布局与对齐的实操技巧
布局是 diagram-design 里最考验耐心的环节。我的实操技巧包括：
- 网格对齐：所有节点对齐到统一网格，间距保持一致。手动拖拽很难对齐，建议开启工具的网格吸附功能。
- 层级间距：不同层级之间的垂直间距要大于同层节点之间的水平间距，这样视觉分组更清晰。
- 分组背景：相关模块用浅灰色背景框圈起来，背景框和节点之间留出足够内边距。
- 流向一致：主流程统一从上到下或从左到右，不要一会儿横一会儿竖。
- 留白：图边缘留出至少 10% 的空白，避免内容贴边显得拥挤。
关于间距的具体数值，我通常用 8 的倍数作为基准单位：节点内边距 16，同层间距 24，层级间距 48，分组内边距 32。这套数值在大多数屏幕上都能保持舒适的阅读节奏。
4.4 第四步：色彩与线型的最终调整
节点和连线布局完成后，最后才上色。上色顺序建议：
- 先给分组背景上浅色，确定视觉分区；
- 再给节点按语义上色，同一语义用同一颜色；
- 最后调整连线颜色，通常用中性灰，避免抢眼；
- 检查对比度，确保文字在背景色上清晰可读。
这里有个细节：连线颜色不要和节点颜色冲突。如果节点用了蓝色系，连线就用深灰，不要再用蓝色，否则读者会误以为连线也属于某个语义类别。
4.5 第五步：导出、嵌入与版本管理
图定稿后，导出格式的选择也很关键：
| 格式 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| SVG | 文档嵌入、网页 | 矢量、可缩放、体积小 | 部分工具编辑兼容性差 |
| PNG | 演示、聊天分享 | 通用、兼容性好 | 位图、放大模糊 |
| 打印、正式交付 | 矢量、排版稳定 | 不便在线预览 | |
| 源文件 | 后续修改 | 可编辑 | 需要对应工具 |
我的习惯是：源文件归档到项目仓库，导出 SVG 用于文档嵌入，导出 PNG 用于即时分享。版本管理方面，如果工具支持文本化存储，直接进 Git；如果是二进制源文件，就在文件名里带日期和版本号，比如architecture-v2.3-20240115.svg。
注意：每次修改图后，记得同步更新图内的版本信息和变更摘要，否则过两个月你自己都记不清改了什么。
5. 常见问题与排查技巧实录
5.1 图太乱怎么办：从信息架构入手，而不是调格式
图乱的根本原因通常不是格式问题，而是信息架构问题。排查顺序应该是：
- 节点是不是太多？超过三十个节点就该考虑拆图；
- 关系是不是太杂？如果一张图里有五种以上关系类型，读者很难跟上；
- 层级是不是不清？检查是否所有节点都在同一水平线上，没有分层；
- 分组是不是缺失？相关模块没有用背景框圈起来，视觉上散成一片。
我的经验是：先做减法，再做美化。删掉不必要的关系、合并同类节点、拆分子图，比调字体和颜色有效得多。
5.2 评审时被问“这个虚线什么意思”：图例不是装饰
图例被忽略是常见问题。很多人觉得图例占地方，或者觉得“这么明显还需要图例吗”。但评审时被问最多的就是线型和颜色的含义。我的做法是：图例必须放在图的固定位置（通常是右下角或左下角），且图例本身要简洁，只列图中实际用到的形状、颜色和线型。
如果图例太长，说明你的视觉编码太复杂，应该精简。一张图里形状不超过七种、颜色不超过五种、线型不超过三种，图例就能控制在一小块区域内。
5.3 不同人画的图风格不统一：建立检查清单
团队协作时，风格不统一是必然的。解决办法不是反复开会强调，而是建立一份“出图检查清单”，每个人提交图之前自查：
- [ ] 节点形状是否符合团队图元规范？
- [ ] 颜色是否绑定了明确语义？
- [ ] 连线是否有箭头和线型区分？
- [ ] 是否有标题、图例、版本信息？
- [ ] 节点和连线是否有编号？
- [ ] 导出格式是否为 SVG 或 PDF？
- [ ] 源文件是否已归档？
这份清单看起来琐碎，但能挡住 80% 的低级问题。剩下的 20% 靠评审时互相提意见逐步改进。
5.4 图改不动了怎么办：文本化是你的救星
如果你用的是纯图形工具，改图时经常遇到“牵一发而动全身”的情况——移动一个节点，所有连线乱掉。这时候文本化绘图的优势就体现出来了。图是代码，改一个节点位置只需要改一行，重新渲染即可。
即使你不用代码化工具，也可以保留一份文本版的关系清单。改图前先改清单，再按清单调整图形，这样逻辑不会乱。
5.5 常见问题速查表
| 问题现象 | 可能原因 | 排查方向 | 解决建议 |
|---|---|---|---|
| 图看起来很乱 | 节点过多或关系过杂 | 统计节点数和关系类型数 | 拆图或合并节点 |
| 读者理解偏差 | 色彩或线型语义不明确 | 检查图例是否完整 | 补充图例，统一语义 |
| 评审沟通低效 | 节点无编号 | 检查是否有编号系统 | 增加编号，文档引用 |
| 修改成本高 | 图形与逻辑耦合 | 检查是否有文本清单 | 先改清单再改图 |
| 导出后模糊 | 使用了位图格式 | 检查导出格式 | 改用 SVG 或 PDF |
| 风格不统一 | 缺少团队规范 | 检查是否有检查清单 | 建立并执行清单 |
5.6 我踩过的最大的坑：过度设计
最后分享一个我踩过的最大的坑：过度设计。早期我追求图的“专业感”，用了大量渐变、阴影、立体效果、图标，结果图看起来很华丽，但读者反馈“不知道重点在哪”。后来我全部改成扁平化、纯色、无阴影，可读性反而大幅提升。
diagram-design 的核心不是让图变漂亮，而是让图变清晰。每一个视觉元素都应该有存在的理由。如果一个阴影不携带任何信息，它就应该被删掉。这个原则我到现在还在用，也推荐给你。
图是给人看的，不是给工具炫技的。把信息结构理清楚，把视觉编码统一好，把版本管理做到位，你的图就已经超过大多数人了。剩下的，就是多画、多评审、多迭代。
