1. diagram-design：从“画图”到“设计图”的转变
diagram-design 是我最近在团队文档体系里专门负责的一类工作——把散落在需求文档、口头沟通和技术方案里的信息，整理成一套结构清晰、视觉一致、可长期维护的图表。很多人觉得画图不就是拖几个框、连几条线的事，但真到用的时候才发现问题一大堆：流程图箭头指向混乱，架构图层级不清，看的人五分钟都找不到核心链路。diagram-design 这个项目要解决的，恰恰就是“一张图能不能在十秒内被看懂”这件事。
这个项目适合三类人参考：一是经常写技术方案、要给上下游讲清楚设计的工程师；二是做产品规划、需要把复杂规则画成业务逻辑的产品经理；三是想把文档里的插图从“随手画”升级成“规范化组件”的技术写作人员。说白了，只要你的工作里离不开图，这套思路就能用得上。
我最早也是“打开画板就开画”的类型，后来迭代了几轮才发现，真正稳定的图表产出靠的不是手感和灵感，而是一套可复用的设计规则：先定图型、再分层、后定视觉参数，最后落到工具和脚本里。这篇文章就把我从 diagram-design 这个项目里沉淀出来的完整思路、参数规范和踩坑记录摊开来写，尽量做到你看完就能直接套用。
2. 图型选型：先别拿鼠标，先想清楚画什么
2.1 常见图型的适用场景
很多图之所以难看，不是因为线条画得不直，而是压根选错了图型。比如有人把系统模块关系画成一张思维导图，中心一个节点、四周全是子节点，这种图表达上下层关系还行，但表达模块间的数据流向就非常别扭。我在项目里先把高频场景做了归类，整理成下面这份选型清单：
| 图型 | 适用场景 | 不适用场景 | 典型例子 |
|---|---|---|---|
| 架构图 | 展示系统分层、模块归属 | 表达时序变化 | 后端服务分层、前后端依赖 |
| 流程图 | 表达步骤、分支、异常处理 | 表达复杂网状依赖 | 登录流程、工单审批流程 |
| 时序图 | 展示跨对象交互顺序 | 表达静态归属 | 下单接口调用链、第三方回调 |
| 实体关系图（ER图） | 建模数据表之间的关联 | 表达业务活动顺序 | 用户、订单、商品模型 |
| 状态图 | 表达对象状态流转 | 表达并发分支 | 订单状态、任务状态 |
| 思维导图 | 头脑风暴、结构拆解 | 表达严格依赖关系 | 需求拆解、知识梳理 |
这张表我贴在工位旁边很久了，每次动手前都会对着它问自己一句：“我要表达的核心关系到底是什么？”如果是“谁包含谁”，优先看架构图；如果是“先做什么、再做什么”，优先看流程图；如果是“数据表之间怎么关联”，老老实实用 ER 图。选对了图型，整张图的信息传达效率就成功了一半。
2.2 图型选型的三个判断维度
光靠场景表还不够，我在实际项目中慢慢发现，选型其实可以拆成三个更底层的维度，组合起来判断会更稳。
第一个维度是“信息的核心关系”。任何一张图都可以被抽象成三种关系之一：层级关系（包含/归属）、流程关系（先后/条件）、网状关系（双向/多对多）。如果是混合关系，不要硬塞进一张图里，宁可拆成主图和子图，后面维护也会轻松很多。我见过太多人想一张图画尽天下事，最后每个关系都没讲清楚。
第二个维度是“看图人的使用习惯”。如果是给开发同事对着做接口设计，时序图远比思维导图好沟通；如果是给业务方同步一个决策路径，流程图比架构图更直观。看图人决定了信息的粒度，也决定了你能不能省掉那一堆“众所周知”的细节。
第三个维度是“变更频率”。我通常在选型时会额外问一句：这张图多久会变一次？如果每周都要跟着需求改，尽量选文本化、可 diff 的表达方式，比如声明式脚本生成的图；如果一年都动不了几次，手工绘制完全够用。我自己在 diagram-design 项目里定了条规矩：带“数据关系”属性的图，一律走脚本生成，从源头规避改图时找不到原文件的尴尬。
3. 信息分层与视觉参数：让图经得起细看
3.1 信息三层结构：主视觉层、辅助层、注释层
选好图型之后，进入最容易被忽略的一步——信息分层。我一开始画图总是把所有信息堆在一起，框里塞满文字，每个框都要加个红框强调，结果整张图看起来像打翻了的调色盘。后来在 diagram-design 的规范里，我把一张图的信息拆成三层来组织：
主视觉层是图的骨架，包括最核心的实体框、关键箭头和主导航路径。这一层的目标是人眼第一扫就能看到“从哪开始、到哪结束”。以一张订单流程图为例，主视觉层就是“创建订单 → 支付 → 发货 → 完成”这条线，其他东西都得给这条线让路。
辅助层负责补齐主链路附近的重要分支和异常路径，比如“支付超时”“库存不足”这些情况。这一层的视觉权重必须明显低于主链路，常用做法是弱化描边颜色、降低图标饱和度，必要时用虚线框归类。
注释层放的是补充说明、数据指标、版本信息和来源备注。这一层要么沉到图底，要么统一放到一个角标里，绝不能和主视觉元素抢注意力。我见过不少团队把注释文字直接堆在主干线旁边，导致图还没讲完，观众的眼神已经飞了。
这里有一个我在项目里反复用的判断标准：把图拿给一个完全不了解业务的人看，十秒钟后让他回答“这个图在讲什么”，如果答不出来，说明主视觉层没有做干净。
3.2 色彩、字体、线条与网格的参数建议
视觉参数是我在 diagram-design 里迭代最久的部分，下面这组参数是我们目前比较稳定的默认方案，你可以直接抄去用，也可以作为底线再衍生出自己的调性。
色彩方面，我建议一张图里同时出现的颜色不超过四种，并且每种颜色都要有明确的语义。比如蓝色表示“系统模块”、绿色表示“正常业务路径”、橙色表示“待确认或中间态”、红色表示“异常或阻断”。背景色一律用浅灰或纯白，不用渐变。给实体加填充色时，饱和度不要超过 70%，否则打印出来或投到会议大屏上都会显得特别脏。
字体方面，中文字体优先使用无衬线体，英文字体保持同一家族。标题字号 14 到 16，正文 12，注释 10 到 11，层级之间至少差 2px。框内文字尽量控制在 10 个字以内，一条线路上不要堆超过五个框，如果超过就说明粒度太粗，需要再加一层子图。
线条与箭头是很多人不重视的细节，其实是整张图的“语法”。我在规范里统一约定：实线表示确定关系，虚线表示条件或未来关系；箭头指向数据流方向；线宽默认 1.5px，最短路径上的主干线可以用 2.5px。连接线禁止出现斜穿过实体框的情况，尽量走正交折线，也就是横平竖直的连线方式，这样视觉上会清爽非常多。
网格与留白是最后的收尾。所有实体框都对齐到同一套网格坐标系，常见的网格间距我用 8px 或 12px。框之间至少保留 24px 的间距，分组之间至少 48px。没有网格意识的图，看起来总有一种说不出为什么的“歪”，一旦对齐，专业感立刻上来。
4. 从手绘到可维护：工具选型与脚本化生成
4.1 工具全景对比
图型选型和视觉规范定下来之后，就该讨论用什么工具落地了。我在 diagram-design 项目里对比过四类方案，各有各的适用场景，直接列成表供你参考。
| 工具类型 | 上手门槛 | 协作体验 | 可维护性 | 适用场景 |
|---|---|---|---|---|
| 在线协作白板类 | 极低 | 多人实时同步 | 较差，画完难复用 | 快速讨论、评审手稿 |
| 桌面流程图软件 | 低 | 靠文件流转 | 中等，模板丰富 | 低频插图、对外汇报 |
| 声明式脚本绘图 | 中等 | 天然适配代码评审 | 高，文本可 diff | 架构图、数据关系图 |
| 编程绘制库 | 较高 | 依赖脚本仓库 | 高，可动态生成 | 批量产出、数据驱动图 |
你会发现我最终把重心放在了“声明式脚本绘图”和“编程绘制库”这两类上，原因是 diagram-design 项目里的图表大多需要跟随代码迭代。手工画一张图很快，但三个月后改需求时找不到源文件、或者找到了但不知道改哪个图层，这些隐性成本远比当初画图的半小时高得多。
4.2 用声明式脚本维护架构图
我先把最常用的架构图实现方式演示一遍。这一套用文本描述结构，自动排版布局，不依赖手工拖拽，非常稳。
digraph system_arch { rankdir=TB; node [shape=box, style="rounded, filled", fillcolor="#E8F0FE", color="#5B7DB1", fontname="Helvetica", fontsize=12, margin="0.25,0.15"]; edge [color="#666666", arrowsize=0.8, fontname="Helvetica", fontsize=10]; subgraph cluster_frontend { label="前端层"; style="rounded, dashed"; color="#B0BEC5"; web [label="Web端", fillcolor="#D9E8FF"]; mini [label="小程序", fillcolor="#D9E8FF"]; } subgraph cluster_biz { label="业务层"; style="rounded, dashed"; color="#B0BEC5"; order [label="订单服务", fillcolor="#FFFFFF"]; pay [label="支付服务", fillcolor="#FFFFFF"]; } subgraph cluster_data { label="数据层"; style="rounded, dashed"; color="#B0BEC5"; db [label="MySQL", shape=cylinder, fillcolor="#FDECEA"]; cache [label="Redis", shape=cylinder, fillcolor="#FDECEA"]; } web -> order [label="下单"]; mini -> order [label="下单"]; order -> pay [label="发起支付"]; pay -> db [label="落库"]; order -> cache [label="缓存状态"]; }把这段文本保存成文件后，用对应的命令行工具导出成 PNG 或 SVG，整个过程不需要手动对齐任何一个节点。它的好处很具体：一是改图时只改文本，不会遇到图形软件里“找不到原始文件”的问题；二是团队成员可以直接在代码评审里对这份图提意见，线怎么连、节点叫什么，全都在文本里清清楚楚；三是可以用脚本批量生成多张版本图，比如灰度环境一套、生产环境一套，数据源是同一份定义。
4.3 用编程绘制库生成数据驱动图表
如果图表的数据本身是动态的，比如每天要根据接口监控数据画一张调用频次图，那就需要进入编程绘制库的范畴。我在项目里比较常用 Python 生态里的绘图库，核心逻辑只有三步：准备数据、设置样式、渲染输出。
import pandas as pd import matplotlib.pyplot as plt plt.rcParams["font.family"] = ["sans-serif"] plt.rcParams["axes.unicode_minus"] = False # 准备数据：接口名 + 调用次数 df = pd.DataFrame({ "接口": ["/cart/add", "/order/pay", "/user/login", "/product/detail"], "调用次数": [1200, 430, 980, 2100] }) # 设置样式，与视觉规范保持一致 fig, ax = plt.subplots(figsize=(8, 4.5)) bars = ax.bar(df["接口"], df["调用次数"], color="#5B7DB1", width=0.6) ax.set_title("核心接口调用热度", fontsize=14) ax.set_ylabel("调用次数", fontsize=11) ax.set_ylim(0, 2500) ax.spines[["top", "right"]].set_visible(False) # 高亮超过阈值的接口 threshold = 1000 for bar, count in zip(bars, df["调用次数"]): if count > threshold: bar.set_color("#D96C6C") plt.tight_layout() plt.savefig("api_heatmap.png", dpi=200)这份脚本看起来简单，但里面已经内置了我在前面定的视觉规范：颜色不超过两种、去掉了顶部和右侧的边框线、用了非衬线字体。输出结果不是那种“默认模板味”的图，而是直接符合团队文档规范的数据图。这个方式的最大价值是，以后数据一变，重新跑一次脚本就能得到最新版图表，不用再手工改数。
4.4 我整理出的单人实操流程
结合上面的工具经验，我把自己每次做图的实际流程写成了一份清单，大概五步：
第一步，写图题。不动手画，先在一句话里说清楚“这张图要表达什么关系”。这一步能筛掉一半思路不清就开始拖框的冲动。
第二步，画主干。用白板或草稿纸，只画主视觉层的实体和连线，不考虑配色和精确对齐。这个阶段的目标是把“骨架”立起来。
第三步，列分支。把异常分支、辅助节点和注释信息整理成清单，标出哪些属于辅助层、哪些属于注释层。如果分支数量超过主干数量的一半，就考虑拆子图。
第四步，套样式。回到脚本或绘图软件，按照色彩、字体、线条、网格的规范开始正式制作，优先保证主链路突出。
第五步，做检查。导出图片后，我习惯把它缩到 50% 再放大到 100% 各看一遍。缩小时看整体结构是否平衡，放大时看文字有没有出框、箭头有没有压线。
这份流程看起来平平无奇，但每一条都是从多次返工里换来的。我尤其推荐你试试第一步，只写一句话描述图的目标。很多图改来改去，最后发现根本不是画法的问题，而是制图人自己都没想清楚要表达什么。
5. 常见问题与排查技巧
5.1 高频问题汇总
在推行 diagram-design 规范的过程中，团队里反馈最多的问题集中在下面几个，我整理了一张排查速查表，你可以对照着自检。
| 现象 | 可能原因 | 解决思路 |
|---|---|---|
| 图看起来“很乱” | 颜色过多 / 线条交叉 / 框未对齐 | 色彩降为三种以内，连线改正交折线，启用网格吸附 |
| 重点不突出 | 所有元素视觉权重相同 | 给主干线加粗，平行分支降低饱和度，注释沉底 |
| 改了需求但找不到图 | 图形文件是二进制格式，没有源文件和版本 | 切换成声明式脚本，文本入库 |
| 文字到处出框 | 框边长宽比不合适 / 字号过大 | 框内字数限 10 字，超出就拆节点或修改措辞 |
| 图太密、信息过载 | 单张图承载了多种关系 | 按关系类型拆图，用子图维护细节 |
| 评审时没人看 | 缺少开场白和图题 | 加一个简明标题，并在正文里写清楚“读图顺序” |
这里我最想强调的就是“评审时没人看”这一条。技术评审会上，一张没有图题、没有读图顺序的图扔上去，观众挣扎几秒就放弃理解了。后来我在每张图的标题下面强制加一行小字说明，比如“从下往上看，先看数据层再向上看”，效果立竿见影。
5.2 针对脚本化绘图的排查笔记
如果你也切到了声明式脚本或编程绘制库这条路上，还会遇到一些文本绘图特有的问题。我把常踩的坑单独拎出来讲一下。
第一个坑是乱码。脚本绘图里最经典的翻车现场就是中文标签全部变成了方块。原因基本都出在字体配置上，系统没有找到你指定的中文字体文件。解决方法是显式指定一个系统存在的字体路径，不要写完字体名就以为万事大吉。验证办法也简单，命令行里先查一下字体是否存在，再跑绘图脚本。
第二个坑是布局溢出。声明式脚本绘图虽然自动排版，但长文本节点偶尔会把图撑得非常宽。我的处理方法是给节点设置固定宽度，并通过换行标签强制折行，尽量避免一个框里堆二十个字的场景。
第三个坑是版本兼容。升级绘图库版本之后，之前的脚本偶尔会出现行为变化，比如默认配色变了、边框样式不再生效。为了减少这类问题，我习惯在项目里锁定绘图库的版本号，把依赖写死。
第四个坑是批量生成时样式不统一。如果脚本里散落着很多魔法数字，比如颜色值到处写，后期调起来会非常痛苦。我的习惯是把所有样式常量提取到一个单独的文件里，用一个统一的配置对象去管理颜色、字号、线宽。
5.3 复盘改进：把每一张图当成一次小型设计评审
diagram-design 做到现在，我最大的体会是：画图不是一个一次性交付，而是一个持续收敛的过程。每次图被退回或者被指出“看不懂”，我都会在复盘记录里写三件事：第一，是图型选错了还是分层没做干净；第二，有没有重复出现同类问题；第三，这次能不能沉淀出一条新的参数规则或检查项。
比如我最初并没有“注释层”这个概念，后来连续两次都被指“图上信息太杂”，才意识到需要把注释统一压到底部。又比如“主干线加粗”这个规则，也是因为评审时有人直接在会上说了一句“我不知道该看哪条线”，才被正式写进规范。这些规则看似微小，但累积起来就是一套团队能共同使用、新人三小时就能上手的图表设计语言。
这里再分享一个我个人的小技巧：每次正式发图前，把图发给一个不在项目里的同事，只问一个问题——“你看懂了什么”。对方复述出来的内容，往往能一针见血地指出主视觉层到底有没有做对。这比我自己对着屏幕反复检查十分钟都管用。
最后说说这套方法还能往哪走。diagram-design 目前主要覆盖了技术文档里的架构图、流程图和时序图，但同样的思路完全可以平移去做产品说明书里的操作指引图、汇报材料的逻辑图、甚至是知识库的索引图。只要抓住“先定图型、再分层、后定参数”这条主线，很多时候你会发现，文档质量提升不一定需要写更多字，把图画清楚就够了。
