1. 为什么我专门为“画图”做了一个设计项目
如果你跟我一样，写文档和方案的时间有一半花在图上，那你大概率经历过这种烦躁：同一个业务模块，上周画的是蓝色方块，这周变成了绿色圆角框；流程图里实线代表数据流，过两天又用来表示调用关系。等到跨团队协作时，别人盯着图问“这条线为什么是虚线”，你会发现自己也答不上来。
我后来做了一个决定：把“画图”从随手操作里拎出来，当作一个正经项目去设计。项目名就叫 diagram-design。这不是某个开源软件的代称，也不是要做一个画图App，而是一套关于图表从构思、布局、配色到导出的完整规则和流程。它的目的很简单：让任何人、在任何一篇文档里，用任何工具，画出来的图都能保持同一种信息表达逻辑。
这类需求并不新鲜，但真正落地的人不多。多数团队死在“设计规范”这一步：要么写得像教科书，没人执行；要么管得太死，连快速画一张草图都觉得累。diagram-design 的思路是从实际输出反推规则，先定最少必要的规定，再逐步补充模板和脚本，最终让图表设计变成一件可以复制、可以验收、可以自动化的事。
1.1 一张图暴露的问题
我印象很深的一次评审会上，团队投影了一张架构图。乍一看层次清楚，但细问下去全是隐患：蓝色节点有的代表前端，有的代表中间件；虚线既表示异步消息，又表示缓存失效；图里还有三个地方用了同一种灰色，含义却完全不同。当时我意识到，这不是某一个人画得不好，而是缺少一套共同语言。
另一个常见问题是“图”与“图”之间没有血缘关系。方案里一张流程图，下方一张时序图，单看都还行，放在同一个文档里就明显不协调：字号不一样、圆角不一样、配色习惯不一样。读者在切换段落时会有一种微妙的割裂感，甚至会怀疑是不是不同团队拼凑的内容。
这种问题很难用“多画几次”来解决。只要没有规则、没有模板、没有导出标准，每次画图都是在重新发明轮子。diagram-design 的核心，就是先把这些反复出现的问题抽象成规则，再把规则固化到流程和工具里。
1.2 diagram-design 要解决的三件事
我给自己定下三个目标。第一，统一信息层级。每张图只能有一个视觉重点，其他元素必须主动退让。第二，统一图形语义。颜色、线型、箭头、形状都必须有稳定含义，不允许“看心情”。第三，统一输出标准。图的尺寸、清晰度、字体、间距，在一篇文章和整套文档里保持一致。
这三个目标听起来不大，但执行起来会牵扯到很多细节。比如“重点唯一”要求限制颜色数量和节点数量；“图形语义”要求维护一份对照表；“输出标准”要求规定网格基准和导出倍数。每一条都会在后面的章节展开。
1.3 谁适合参考这套思路
我整理这套东西的过程中，经常假设读者是这样的人：经常要写方案、做汇报、写技术文档，或者负责团队知识库建设；不一定是设计师，但愿意为“让信息更清楚”花一点时间。如果你只是偶尔画一张图发给朋友，那这套规则对你可能太重。但只要你一个月要产出五张以上正式图表，或者需要好几个人一起维护文档，diagram-design 的思路就能帮你省掉大量来回修改的时间。
2. 定义 diagram-design 的设计语言：层级、配色、间距、字体
设计语言是一套图表的“语法”。没有它，画图只是拼积木；有了它，拼出来的东西才有统一秩序。diagram-design 在设计语言上只做了四件事：定层级、限颜色、统间距、选字体。每一步都不复杂，但每一步都要有明确理由。
2.1 信息层级：在动手前先回答“重点是谁”
不少图表的问题不是信息不够，而是一张图里所有元素都在抢注意力。原因很简单：画图时没有先问“这张图到底想让人记住什么”。
我通常在画任何正式图表前，先标出三个层级。一级信息是主流程或核心结构，视觉权重最大；二级信息是支撑模块、分支路径或次要组件，权重居中；三级信息是备注、版本、引用来源等，应该退到背景。这个层级决定了颜色深浅、面积大小、边框粗细和文字字号，而不是反过来。
举个实际场景：画一张订单处理流程图，主链路一定是“下单—支付—库存锁定—发货—完成”。那这条链路上的节点就要用最高的对比度，线条最粗；而像“反作弊检查”“优惠券计算”这类旁路逻辑，即使技术上很重要，在视觉上也要做得更轻。否则读者第一眼看到的可能是边上那个闪烁的异常分支，而不是主流程。
2.2 配色规则：少用颜色，但让颜色有唯一含义
配色是我踩坑最多的部分。以前总觉得颜色越多越丰富，后来发现一张图上超过五种彩色，基本就失控了。diagram-design 建议把颜色收紧到五类以内：一个主色用于核心节点，两到三个辅助色用于不同类别的支撑模块，一个警示色用于异常或强提示，剩下全部用中性灰。
颜色一旦承担了语义，就必须在全项目范围内保持唯一。比如主色代表“当前系统”，辅助色代表“外部依赖”，灰色代表“历史数据”，那么这个含义就不能在某张图里悄悄改变。为了维护这个一致性，我会在规范里放一张颜色语义表，并在每次导出图片前快速核对一遍。
另外要注意背景和前景的关系。同一组色块在白色画布上没问题，放进浅灰背景就会显得脏；在深色模式下又会变得刺眼。diagram-design 的做法是：正式图表尽量使用透明背景或固定浅色背景，深色模式单独提供变体，而不是让同一张图生硬地兼容所有场景。
2.3 间距、线宽、圆角与字体：统一让图“像一家人”
间距方面，我采用 4 像素作为基础网格单位。画布边距用 12 的倍数，节点内边距用 8 或 12，组与组之间的间距用 16 或 24。这样即使不同人画同一张图，视觉密度也不会差太多。线宽和圆角也要定死：连接线用 2 像素，外边框用 2 像素，辅助线用 1 像素；圆角一般统一为 8 像素，特殊圆角保留给状态标签。
字体是最容易被忽略的。图表里的文字不是正文，不应该使用大段说明样式。建议标题文本用 16 到 18 像素，节点标签用 12 到 14 像素，注释用 11 到 12 像素。中文字体要单独指定，优先使用开源中文黑体字形，英文使用干练的无衬线体。所有字体必须允许字符间距收缩，防止标签在狭小空间里溢出。
2.4 把规范固化成一个可消费的配置文件
设计规范如果只写在文档里，很难被真正执行。diagram-design 的尝试是把颜色、间距、线宽、圆角这些内容整理成一份结构化配置，方便不同工具读取。
{ "grid": 4, "page": { "padding": 48, "background": "transparent" }, "colors": { "primary": "#2F6BFF", "secondaryA": "#00B386", "secondaryB": "#FA8C16", "warning": "#E5484D", "neutral": "#8A8F98" }, "typography": { "titleSize": 18, "labelSize": 14, "noteSize": 12, "fontFamily": "sans-serif" }, "node": { "fill": "primary", "strokeWidth": 2, "borderRadius": 8 }, "line": { "width": 2, "arrow": "closed" } }这份配置不绑定具体工具。它可以复制进在线白板工具的样式草稿，也可以转换成某种文本绘图语言的样式片段。真正关键的不是文件格式，而是让规则变得可分发、可更新、可检查。有人问“为什么不用现成的设计系统？”，我的回答是：现成系统解决的是界面设计，图表设计有自己的信息密度和连接关系，最好单独维护一套。
3. 从草图到成图：一套图表的完整制作流程
规范定完之后，最怕的还是对着空白画布发呆。diagram-design 把制图过程分成四步：梳理关系、搭骨架、写标签、检查尺寸。这套流程适合正式输出，也适合快速草图，只是正式输出多一步导出校验。
3.1 先梳理关系，再打开画布
我见过太多人一上来就拖色块，结果越画越乱。更稳的方式是先列清单：这张图涉及哪些节点？节点之间的关系是什么？哪些是主路径，哪些是例外分支？用一句话写清楚图的中心观点。
比如要画“登录链路”的图，我会先写：核心观点是“登录态建立需要经过四个环节，其中短信验证在异常设备上会触发二次校验”。然后列出四个主要节点和一个分支节点。这个过程通常只要五分钟，却能避免画到一半推倒重来。千万别小看这一步。逻辑容错率最低的时刻，就是你觉得已经“差不多想明白了”却还没落笔的时候。
3.2 骨架布局的三种基本模式
diagram-design 很少允许自由散漫的节点定位。推荐先选一种基本布局模式，再在模式内部做调整。
第一种是线路布局，适合主流程。所有节点沿横向或纵向主轴排列，分支均匀分布在两侧。第二种是分层泳道布局，适合架构图。每一行代表一个层级或一类组件，节点放在对应泳道内，跨层连线必须有明确理由。第三种是中心辐射布局，适合模块关系图。核心节点放中间，外围模块按重要程度绕圈排布。
如果一张图元素太多，我会优先拆图，而不是硬塞。一张图的极限信息量大约是九个主要节点加三条分支。超过这个数，读者就会开始数节点而不是理解关系。拆成两张图，每张负责一个子主题，看起来是违背“合在一页”的习惯，实际上理解效率更高。
3.3 标签、注释与箭头语义的统一
节点标签要遵循“动词+名词”的短句式，比如“检查库存”“发送短信”，而不是“库存检查器”“短信发送处理模块”。名词也要统一：同一系统里同一个服务，在流程图里叫“支付服务”，在时序图里就不能改叫“交易网关”。否则读者会以为这是两个不同组件。
注释是非常考验功力的部分。diagram-design 的原则是：注释不要遮挡连线，不要放在节点正中间；使用弱化的字体颜色；注释内容控制在 20 字以内。超过 20 字的内容不要写进图里，放进正文说明。
箭头语义也要固定。我习惯这样定义：实线箭头表示确定性调用或数据流；虚线箭头表示异步消息或事件通知；点线箭头表示配置引用或非关键依赖。如果团队有自己的约定，可以替换，但必须在规范里写死。
3.4 最后的检查清单：别让细节毁掉前面的功夫
每次导出图片前，我会花十几秒过一遍检查清单。节点是否全部对齐到网格？是否出现同一层级内间距不一致的情况？文字与节点边框是否留够了内边距？导出后把图缩到实际使用大小，能不能在三秒内看清主线？颜色是否仍然符合语义表？
这套清单不复杂，但非常有效。有一次我急着发文档，漏掉了“缩到实际大小看可读性”这一步，结果图在画布上很清晰，贴进文档后所有标签糊成一团。自那以后，检查清单就老老实实贴在了项目首页。
4. 工具链选型：手绘、文本绘图与脚本生成如何取舍
diagram-design 没有绑定单一工具，因为不同场景适合不同手段。工具的取舍不只是“好不好用”，还要看是否便于版本管理、是否支持协作、是否能批量生成。
4.1 三类方案的真实差异
我把画图方式分成三类。第一类是图形化白板工具，鼠标拖拽节点连线，交互直观，适合快速讨论，但不适合统一规范。第二类是文本绘图语言，比如通过代码定义节点和边，再自动排版出图，优点是可以用 Git 管理、可以嵌入文档生成流程，缺点是复杂布局仍需人工干预。第三类是脚本生成，用程序根据数据批量产出图表，适合拓扑图、网络关系图、监控大屏这类重复性强的场景。
三类手段的差异可以用一张表表达：
| 方式 | 上手成本 | 样式统一难度 | 适合场景 |
|---|---|---|---|
| 图形化白板 | 低 | 高 | 草图、即时评审 |
| 文本绘图语言 | 中 | 中 | 正式文档、持续维护 |
| 脚本生成 | 较高 | 低 | 批量图表、高复用模板 |
这里有个容易被忽略的点：多数团队不是只用一类工具，而是三者在一条流程里衔接。草图用白板，定稿转成文本绘图语言，批量生成的部分交给脚本。不要试图让一个工具统治所有场景，否则学成本高、维护成本更高。
4.2 我的分工策略
我的默认策略是：快沟通用白板，正式文档用代码，重复内容用脚本。
白板阶段允许粗糙，但必须同步做一件事——记录关键节点和连线关系，而不是只留下一张充满手写笔迹的截图。等关系确认后，再把它翻译成文本绘图语言，赋予统一的样式和间距。这样从“讨论图”到“正式图”之间有一个相对干净的翻译过程，而不是拿着截图反复重画。
对于重复的架构图，我会把节点清单和连接关系放在一个数据文件里，再写一段几十行的脚本生成图。这样当系统组件发生变化时，只需要改数据文件，重新跑一次脚本，所有相关图表都会同步更新。这比手动改图稳得多，也省得多。
4.3 文本绘图 DSL 也要处理“自动排版的失控”
文本绘图工具看起来很省心，写几行代码就能出图，但真正深入后会遇到两个问题。第一是节点文字过长导致的排版错乱，解决办法是提前在数据源定义短标签，或设置节点最大宽度。第二是自动布局的稳定性，文本绘图语言默认的布局算法可能把边排得很长，把不相关的模块拉得很近。
我的处理方式是在自动生成之后，人工检查一次整体布局，并允许在少数关键节点上强制指定坐标。diagram-design 的原则是“自动负责产能，人工负责审美”。完全相信自动排版，通常会在复杂图里暴露问题；完全手动排版，又会丧失效率。合理的平衡是把强制指定限制在五处以内，否则就不如直接手画。
5. 高频踩坑实录与排查链路
这一章是从真实使用中累积的教训。很多问题单独看不大，但组合起来足以让整套图表规范显得不专业。我按排查思路把四个高频问题拆开说。
5.1 导出后图片发虚：不是软件问题，是画布尺寸问题
症状：图在编辑器里很清楚，一放进文档就模糊。很多人以为是导出画质选项不对，其实根因多数是画布尺寸和实际使用尺寸不一致。编辑器里的画布是 1200 像素宽，但文档中图片显示宽度只有 600 像素，只要导出分辨率低于两倍，就会发虚。
排查链路很简单。先确认图片在文档里的目标宽度，再乘以 2 或 3 作为导出宽度。如果文档同时有桌面端和移动端排版，就取最大目标宽度再乘 2。导出后把图片拖进预览工具，按 100% 缩放查看边缘是否平滑。高频踩坑后，我把导出倍率直接写进了项目检查清单，不再依赖临时记忆。
5.2 中文内容断行、文字溢出
中文图表最容易遇到的问题是文字溢出和野蛮断行。症状包括：标签只显示两三个字、句子在奇怪的位置断开、节点边框包不住文字。根因通常在字体栈和换行规则上：默认字体缺失时，渲染引擎会回退到一套不支持中文紧凑排版的字体，同时按英文字符边界断行，中文自然就乱了。
排查修复建议分三层：第一，给节点文本设置明确的中文字体优先顺序，不要依赖系统默认；第二，固定节点最小宽度，并在文本超出 12 个字时自动截断或换行；第三，手动审查所有标签的长度，尽量控制在 8 个字以内。短标签不是偷懒，而是长久可维护的必然选择。
5.3 深色模式下图片刺眼
很多文档平台已经支持深色模式，但图表通常是浅色底、深色字。放到深色页面里，等于在夜里贴了一张白纸，读者第一眼就会被亮斑吸引。解决方式有两种：第一种是导出时去掉背景填充，使用透明背景并给节点加白色系描边；第二种是提供一套深色变体，把背景改成深灰，节点使用浅色文字。
diagram-design 初期只维护浅色一套，后来在深色模式下被多次吐槽，才补了第二套。经验是：越早把主题变体纳入设计语言，返工越少。如果硬件资源和时间有限，至少保证正式大图提供深色版。
5.4 颜色语义前后不一致的排查
这种情况最隐蔽。某一张图里红色代表“异常”，另一张图里红色却代表“重点强调”，两张图放在同一篇文档中，读者会默认它们是同一个意思。大多数时候不是故意改颜色，而是换了工具、换了模板之后，默认色板覆盖了手动设置。
我的排查办法是在每次渲染前跑一遍“颜色语义检查”：把图中出现的每个彩色色值列出来，和语义表一一对照。一旦发现没出现在语义表中的颜色，就直接替换。这个动作不值得做成自动化，但只要坚持两次，团队的默认审美就会明显收敛。
6. 在真实文档场景中的扩展用法
diagram-design 最终要落到具体场景里，否则就是一套没有生命力的规则。我把它用在了架构图、流程图、时序图和用户旅程图四种场景中，效果比较明显。
6.1 架构图的“分层泳道”写法
架构图最忌讳把所有组件平铺在一张画布里。diagram-design 的做法是先画横向泳道，每一道代表一个层级，比如“客户端”“接入层”“业务层”“数据层”。节点必须进入对应泳道，跨层连线要尽量少。如果一根线要从客户端直接连到数据层，说明中间省略了太多环节，往往应该在接入层或业务层补一个代理节点。
泳道还能起到信息压缩的作用：读者不用看具体标签，只看节点落在哪一层，就知道它大概承担什么职责。这样即使图很密，视觉上也还是有顺序。泳道间距统一用 24 像素，泳道标题用 14 像素的辅助色，和节点区分开。
6.2 流程图和时序图的箭头语义
流程图最需要稳定的是箭头和线型语义。diagram-design 把线型分成了三种用途：实线代表同步调用或直接数据流，虚线代表异步事件或回调，点线代表配置引用或轻量关系。这三条规则看起来简单，但生产力和理解成本的改善非常明显：没有人再需要对着图例来回查。
时序图则要注意“生命线”的使用。不要为每一个临时变量画一条生命线，那样会把图撑爆。只保留服务级别或模块级别的生命线，内部细节留给代码或文字说明。每条消息标签尽量采用“动作+目标”的写法，比如“查询订单状态”，而不是“order.status.query”。
6.3 面向非技术读者的用户旅程图
给非技术读者画图时，diagram-design 会刻意减少术语，并把视觉重点放在情绪或体验变化上。节点标签从技术动作改成用户在做什么，比如“打开页面”“找不到入口”“联系客服”。配色上会用暖色标识情绪低谷，用冷色或绿色标识顺利节点。
这张图不追求完整的逻辑链路，而是追求“读者能迅速判断用户在哪里最受挫”。为了达到效果，可以牺牲部分技术准确性，但必须在注释中写明是示意而非严格流程。面向不同受众的图，采用不同精度，这也是图表设计的一部分。
6.4 从单张图走向一套图
当我把 diagram-design 用到一套文档后，还发现一个附带好处：图与图之间可以互相引用。流程图中出现的某个模块，在架构图里有对应的泳道；架构图里的数据层，在时序图里有对应的数据服务。因为命名和颜色语义统一了，读者可以跨图追踪同一实体，文档整体性大大提高。
如果你也要做一套图，建议先画一张全局架构总图，再拆出流程细节图。总图负责定位，细节图负责解释。没有总图时，每个细节图看起来都像孤岛；有了总图，细节图才有上下文。这个顺序一旦固定，文档结构会清晰很多。
我在实际维护过程中最大的体会是：图表规范不需要复杂，但需要存在。哪怕只定下“最多三种主色”“实线代表调用”“导出宽不低于使用宽两倍”这三条，也比完全没有规则强。diagram-design 做到后期，其实没有增加多少“设计感”，它只是把混乱的默认状态纠正成了有秩序的表达。给自己画图前设一个小预算——最多几个节点、几种颜色、一条主流程，预算越少，图往往越清楚。
