写图这件事，大部分团队一开始都没当回事。直到系统复杂到一定程度，架构图画出来没人看得懂、流程图改一版要半天、新人看着一堆形状和箭头完全找不到重点，才会意识到：图表设计（diagram-design）不是随手画几笔，它是一套完整的表达方法。我维护这个名为 diagram-design 的项目，其实就是一套从信息分层、布局规范到工具链落地的图表设计体系。它解决的核心问题很直接：怎么让团队画出的每一张图都一样清晰、好维护、能复用。本文会把这套体系从设计取舍到实操细节完整讲一遍，适合那些需要绘制系统架构图、业务流程图、拓扑图，或者正在被"图上画得乱、代码里改不动"困扰的工程师、设计师和技术文档负责人。
1. 项目定位：为什么需要一个统一的图表设计体系
1.1 当图表开始失控
很多团队最初并没有"图表设计"这个明确概念。画图工具五花八门，有人用在线白板，有人用离线客户端，还有人直接在代码里写ASCII图。风格差异越来越大之后，问题开始集中暴露：同样的系统组件，不同人画出来的形状不一样、颜色语义反着来，流程图的分支箭头歪七扭八，架构图的层级关系要靠猜才能看懂。
diagram-design 这个项目最开始就是为了控制这种混乱。它不是某个单一工具，而是一套约束，覆盖图表的元素定义、绘制规则、输出格式，以及和自动布局、渲染管线的衔接方式。凡是接进这套规范的图，画出来在视觉上就是一套语言，信息密度可控，修改成本也在可接受范围。
1.2 服务对象与适用场景
我在整理这套方案时，主要面向四类场景：
- 系统架构图：说明服务之间怎么调用、数据怎么流转，重点是层次关系。
- 业务流程图：描述一个事务从触发到结束的完整路径，重点是判定分支和异常出口。
- 网络拓扑图：展示设备、网段、链路之间的物理或逻辑连接，重点是连通关系。
- 数据模型图：呈现表结构、字段关联和依赖，重点是实体关系。
这套体系还适合给技术文档配图。写接口文档、故障报告、设计方案评审材料时，一套统一的图表表达能显著缩短阅读方理解上下文的时间。我见过不少项目因为图太乱，评审会上多少时间花在"这张图的边框颜色到底是什么意思"上，相当不值。
2. 图表设计的核心要素拆解
2.1 信息分层是第一步，不是配色
很多人画图上来就选色卡，这是本末倒置。图形设计的第一层是信息分层：这张图里哪些是主体、哪些是辅助说明、哪些是背景容器。分层的核心原则是，图上的元素必须能被读者在 5 秒内分成主次。
我自己常用的分层方法是三层模型：
- 主图层（L1）：核心对象，通常是系统、模块、实体或流程节点。这是读者第一眼应该看到的东西。
- 关系层（L2）：连线、箭头、数据流，负责表达主图层对象之间的交互。
- 装饰层（L3）：分组框、注释、图例、标题，只在需要时出现，绝不抢眼球。
判断是否分层到位有一个简单标准：把图缩到很小，眯着眼看，如果只能看到一团乱线，说明层次没做好；如果能看到明确的"大块模块 + 关键连接"，就是合格的。L1 要用大色块和粗描边撑起来，L2 的连线要让路，不要从节点正中穿过，最好贴着边缘走，L3 的元素全部用低饱和中性色。
2.2 布局策略：方向、对齐、留白
布局决定一张图的骨架。我在这套体系里定了三条硬规则：
第一，方向语义必须统一。一张图里只能混用"从上到下"和"从左到右"两种主流流向，且必须是分区域使用。比如主流程统一从左到右，子模块内部的依赖关系从上到下，这样读者视线有明确路径。我最忌讳的就是同一层节点里一会儿竖排一会儿横排，箭头还拐来拐去。
第二，对齐比美观重要。所有同级节点必须严格对齐到同一水平线或垂直线上。手工拖拽时，开启网格吸附只是基础，更关键的是要让同级节点的宽度保持一致。宽度不一致时，文字折行位置就会参差不齐，视觉噪声立刻上升。
第三，留白就是呼吸感。节点与节点之间的间距至少要有节点宽度的四分之一。很多人为了省空间把图塞得满满当当，结果一旦要加新节点，整张图都得重排。自动布局算法通常有默认间距参数，我建议把默认值调大一到两倍，观感提升非常明显。
布局这块，我额外强调一点：连线永远不要在节点正下方垂直转弯接进节点。这样视觉上线索是断的，对不上。经验做法是，连线从节点左右两侧引出，水平走一段距离后再统一转向，形成明确的"导线槽"。这有点像电路板布线，总线区域保持平行线间距一致，图面干净得多。
2.3 配色和字体的实用规范
配色这块我不推荐创作自由，只推荐克制。图表不是视觉海报，它的任务是快速传达结构。我定的基础调色逻辑是：
- 一套主色调用于 L1 层，控制在 4 到 6 个色相内。
- 不同含义的节点用不同色相，比如业务服务用蓝色系、数据存储用绿色系、外部系统用灰色系。
- 同一色相内用明度区分状态，比如正常态和异常态。
这里有个我非常看重的细节：状态颜色不能只用色相区分，必须配合形状或图标。因为色盲用户在红绿难以分辨的情况下，只知道"颜色变了"，却不知道"变了是什么意思"。所以这版规范里增加了节点左下角的小标记，比如"故障"会加一个实心小三角，既保留颜色提示，又提供了第二重信息通道。
字体的核心要求只有一条：全图不超过两种字体，标题和正文各一种。中文环境下，标题用默认的加粗正文也可以，关键是字号梯度要清晰：图标题 16px，组标签 13px，节点内文字 12px，注释文字 10px。这套梯度在导出 PNG 后依然清晰可读。字体渲染有一个常见坑：同一字体在不同操作系统上的回退不一样，Windows 上显示正常宋体图，到了 macOS 回退成苹方，字重一旦变化，整个图的立体感就没了。后面第三节会讲怎么从根上规避。
3. 实操：从草图到交付的完整流程
3.1 工具选型背后的取舍
diagram-design 在工具选型上经历过一些反复，核心诉求有三个：可编程、可渲染、可嵌入文档。
纯手工拖拽的工具胜在交互流畅，但致命弱点是不可批量化、不可版本控制。一张几百个节点的图，每次手工调整都要花费大量时间。而纯代码绘制对新手不友好，布局逻辑一旦复杂，代码维护成本也高。diagram-design 的选型策略是：存图用声明式文本格式，画图用可视化前端编辑，导出走静态渲染管线。这样既能在编辑器里所见即所得，又能把图的源文件放进 Git 里做版本管理，还保留了自动生成、自动布局的可能。
我的建议是，做这类方案前先列一个决策矩阵。把工具能力列为"声明式文本格式、可视化编辑、自动布局、插件扩展、导出多样性、许可证合规"六个维度，逐项打分对比。看起来全面，其实最后决定输赢的往往是两个隐藏维度：格式是否开放，以及社区生态是否活跃。格式开放意味着你永远有办法自己写脚本批量处理图；生态活跃则意味着自动布局、主题渲染这类插件有人持续维护。这两个维度不过关，前期再好用后期都会变成坑。
3.2 定义样式表：把视觉规则代码化
进入实操，我建议所有设计规范都固化成一份样式表，不要只停留在文档里。diagram-design 的样式体系是按照"主题（Theme）、样式（Style）、规则（Rule）"三层组织的。
主题层定义全局变量：背景色、主色、五种功能色、字体族、三档字号。样式层定义节点样式：圆角矩形的圆角半径、边框宽度、填充色、阴影参数。连线样式则定义线宽、颜色、箭头样式、折线圆角。规则层是真正有意思的部分，它定义"什么情况下应用什么样式"。
举例来说，规则可以这样定义：
// 规则：标记为异常状态的节点，应用告警样式 { "target": "node[state='error']", "style": "status.error", "priority": 10 }这段代码的意思是，凡是 state 属性为 error 的节点，统一套用 error 样式，不需要每次画图时手动调整颜色。开发人员写新图时，根本不用关心该上什么色，只要在业务语义里正确标注 state，渲染时自动套用正确视觉。
规则层还有一个好处，它让"图例"变成可计算的。传统画图方式中，图例是在画布角落手工画的方块和说明文字。在样式规则体系下，图例可以直接从样式表动态生成，永远不会和实际样式不一致。我在多个文档项目中靠这个特性免去了一堆返工。
3.3 渲染与导出的踩坑记录
样式表和布局规则都定了之后，下一步是把图渲染出来集成到文档里。这块坑非常多，我挑几个影响最大的记录一下。
第一个坑是导出图片的尺寸问题。SVG 渲染天然是矢量的，导出 PNG 时如果不按实际尺寸放大，文字就会发虚。我用过一个笨办法：导出前先把 SVG 的实际 CSS 尺寸强制放大 2 倍，再渲染成 PNG，最后在文档里用 CSS 重新缩回原尺寸显示。这样既保证清晰度，又不影响排版布局。因为 SVG 里的文字都是独立文本节点，光栅化时分辨率越高越清晰，而 2 倍缩放对性能压力也在可接受范围。
第二个坑是中文换行和截断。很多绘图组件在处理 CJK 文本时，默认不会在合适位置换行，导致节点文字溢出边框。我用过一个比较可靠的策略：在数据预处理阶段，根据节点宽度和字体字号估算每行可容纳的字符数，手动插入换行符，而不是依赖渲染端智能换行。这个估算公式非常简单：节点宽度减去左右 padding，除以单字符宽度，向下取整。对于中文可以近似把每个字符宽度当作 1em 来计算，稳妥性比英文高很多。
第三个坑是连线路径计算。很多绘图库默认采用直线连接，或者简单使用贝塞尔曲线。节点多的时候，两条连线会交叉穿过，视觉上一团浆糊。diagram-design 采用的方案是自定义连线路由：先计算两个节点的相对方位，决定从哪个边出线，然后生成一条水平-垂直-水平（或垂直-水平-垂直）的折线路径，转折处加小圆角。这个策略比贝塞尔曲线好用的地方在于，它与节点常见的矩形形状天然契合，也更容易让读者对齐。
3.4 一个完整的从无到有操作实例
我用一个真实的内部场景来做演示：给"订单处理"流程画图。手工草稿时它很简单，只有创建、校验、支付、完成四个步骤，但需求细化后发现校验环节拆出十余种异常分支，图面立刻失控。
我按 diagram-design 的流程来处理，第一步不是画图，而是枚举节点：
- 主流程节点：创建订单、校验库存、扣减库存、生成支付单、等待支付、支付确认、订单完成。
- 异常分支节点：库存不足、并发冲突、支付超时、支付取消。
- 外部交互节点：支付网关、库存服务、消息队列。
第二步是定义层级关系，主流程放中间一条水平主线，异常分支从主线对应节点向下引出，外部交互节点放在最外侧。第三步用代码写图源文件，此时不关心任何样式，只关心节点属性和关系。第四步进入渲染管线，自动套用主题样式和布局规则，产出初稿。
初稿出来后做了三个调整：一是外部交互节点和主流程节点的间距不够，让支付网关的连线与消息队列的连线重叠了，于是调整了留白参数；二是库存不足这个异常分支的语义是从"校验库存"出去的，但和后边的"扣减库存"路径视觉上离得太远，我把它改成从这个节点下方直接引出短虚线；三是给异常分支统一加了虚线边框和标记，一眼就能识别这是"失败路径"而不是"正常路径"。整个调整过程都是改数据、跑渲染，没有一次手工拖拽。
4. 自动布局：终于不用再手动拖节点了
4.1 为什么要引入布局算法
画图项目做到后面，手工放置节点会成为最大的瓶颈。十几二十个节点的图，手工拖还能接受，一旦超过一百个节点，手动调整对齐和间距就是一种折磨。diagram-design 在第二版里引入了自动布局引擎，我不再需要关心坐标值，只要描述节点之间的结构关系，引擎会算出合理的位置。
自动布局的常见模式有两种：分层布局和力导向布局。分层布局适合表达有方向的流程，比如架构分层、调用链路，它把图分成若干层，每一层的节点排列在同一条线上。力导向布局适合表达无方向的关联网络，比如社交关系、依赖分析，它通过模拟物理弹力和斥力来摆放节点，让关联紧密的节点靠近。
diagram-design 默认采用分层布局为主，因为技术类图大部分有明确方向。但这里有一个经验教训：纯自动布局的结果通常只能打 60 分。它保证节点不重叠、边不长，但不会理解业务语义，比如某两个节点应该在视觉上靠近，因为它们属于同一套子系统。所以我采用的是"主结构自动布局＋关键位置手动锚定"的混合模式。允许在描述文件里给节点加一个"固定位置"标记，锚定的节点不参与自动布局，其余的交给引擎。这样既保留了自动布局的高效，又不丢失人工经验对关键信息的突出。
4.2 数据驱动的图表维护方式
当图表从"拖出来的画"变成"写出来的数据"，维护方式就彻底变了。我举一个项目里很典型的例子：系统新增了一个微服务，需要更新架构图。手工画图的流程是：打开编辑工具，找到相关区域，添加节点，连线，调样式，调整周边坐标，导出，提交。这一套下来少说 20 分钟。
用 diagram-design 的方式，只需要在数据源里加一段节点描述：
{ "id": "svc-payment", "name": "支付服务", "group": "核心服务域", "dependsOn": ["svc-order", "svc-user"], "state": "normal" }然后重新跑一遍构建脚本，新节点出现、依赖边连上、样式自动套用，全程不到 30 秒。更重要的是，因为有了数据源，架构图可以和实际服务注册信息做比对，自动发现"代码里已经删掉的服务还在图上残留"。这种一致性保障，是手工画图永远做不到的。
数据驱动还有一个我之前没预料到的收益：图的 Diff 可以做了。以前评审改版架构图，两张图放一起肉眼比，累且容易漏。在数据驱动模式下，渲染出的同一张图的前后两版，可以直接做结构化 Diff，精确到"哪个节点新增了依赖、哪个服务移出了某个分组"。评审效率提升非常明显。
5. 常见问题与排查技巧实录
5.1 节点重叠与布局错乱
自动布局模式下，节点重叠是出现频率最高的故障。原因多数不是渲染引擎的问题，而是输入关系里存在不可达的孤立节点。孤立节点没有边连接，引擎不知道把它放在哪里，就随机丢到画布角落，有时叠在别的节点上。
排查方法很有规律：先检查图数据源，找出没有任何连线引用的节点 id，单独处理。还有一个隐蔽原因：两个节点之间存在双向边，导致布局引擎计算时陷入强烈的弹簧振荡，间距始终收敛不了。这个问题的对策是检查双向关系描述是否真的必要，如果只是"互相调用"，在布局描述里合成一条主依赖方向即可，视觉表达更简洁，布局也更稳定。
手工微调模式下，节点重叠的原因通常是某个节点被锚定后，周围的其他节点重新参与布局计算，但没有把锚定节点的位置排除出碰撞检测。diagram-design 的锚定机制里有一套"隐形边界盒"，锚定节点要根据自身尺寸扩展一个禁区，布局引擎不允许其他节点落入禁区。我在早期版本里漏掉了这个边界盒，结果每次锚定一个节点，周围就会乱成一团。加上之后，这个困扰就消失了。
5.2 跨端渲染不一致
同一张图在浏览器里正常，贴到文档里字号变大、线框加粗，这类问题在跨端场景非常典型。根源几乎都是 CSS 重置差异。不同渲染端默认样式表不同，SVG 里的文本节点继承的字体、字重、行高都会变化。
我的应对方法是给 SVG 的根节点显式写入全套关键样式属性，不依赖任何外部 CSS：
<!-- 显式声明关键样式 --> <svg style="font-family:Arial,sans-serif; font-size:12px; line-height:1.4;">这样做虽然代码啰嗦，但可以彻底杜绝文档站点/编辑器对渲染的干扰。把样式内联进 SVG 后，再复制到任何支持 SVG 的载体里，图的表现都会和本地预览一致，这是个笨但非常有效的策略。
另一个跨端问题是箭头缺失。PNG 导出后箭头消失了，排查发现是渲染端的 marker 路径引用了外部 URL，那个 URL 在光栅化时不可访问，箭头就退化成普通端点。修复方式是把 marker 路径改为内嵌定义，永远不要引用相对路径或外部资源。
5.3 色彩观感不一致
导出图片在深色背景和浅色背景下观感差异极大。因为很多绘图工具会默认叠加一层透明背景，放到不同背景色文档里，半透明节点的混色效果完全变了。对策是在导出配置里显式设置画布底色，而不是保持透明。凡是面向文档交付的图，我都强制填白底或浅灰底。
还有显示器色域差异带来的问题，这个属于优先级较低的优化点。硬要处理的话，可以在样式表里面向导出场景把色彩统一转成 sRGB，至少保证绝大部分显示设备差别不大。但说句实话，这个优化的收益在多数内部场景里感知不强，建议把时间花在更前面的信息分层上，而不是纠结色差的感知细节。
5.4 快速问题速查表
| 现象 | 排查优先级 | 常见根因 | 处理建议 |
|---|---|---|---|
| 节点重叠 | 高 | 孤立节点、双向边振荡 | 清理孤立节点，双向关系合并且定义主方向 |
| 连线不贴合节点 | 高 | 连线锚点位置错误、边界盒缺失 | 检查锚点默认值，增加锚定禁区 |
| 文字溢出边框 | 中 | 换行策略失效、宽度估算不准 | 在数据预处理阶段计算强制换行位置 |
| 字体风格变化 | 中 | 外部 CSS 覆盖 SVG 样式 | SVG 内联关键样式属性 |
| 箭头消失 | 中 | marker 引用外部资源 | 改成内嵌箭头路径定义 |
| 深色背景上层色偏差 | 低 | 透明画布混色 | 导出时强制填充底色 |
6. 一段时间实践下来的个人体会
diagram-design 这个项目做下来，我最深的感觉是：图表设计问题从来不只是技术问题。当它能长期满足团队需求时，往往是因为它顺应了人对信息的认知方式，并有稳定的迭代节奏来维护规范。当它变得难用，通常不是哪一行代码写的不好，而是团队对"这张图要表达什么"这件事想得不够清楚，把混乱的思考原样画出来了。
如果一定要给一个从零开始的建议，我认为不要急着搭建复杂的自动布局和样式规则。先找三张团队里最常更新的图，手工限定它们的元素、颜色和连线方式，跑通这一个小闭环，把能落地的规范沉淀成样式表和组件，再逐步扩展。工具是为表达服务的，图表质量最终取决于表达逻辑是否正确、信息层次是否清楚。这个认知，值得任何计划做图表体系的人当成第一课。
