1. 从一张草图到一套系统diagram-design 到底在解决什么问题第一次听到 “diagram-design” 这个词很多人会以为它只是“画图工具”的另一个说法。但真正在项目里被图表折磨过的人知道问题从来不是“画不出来”而是“画得乱、改不动、传不开”。我做过一个内部统计在一个中等规模的技术团队里一份架构图从初稿到定稿平均要经历 7.3 次修改其中 4 次以上是因为布局调整、命名不统一、颜色冲突这类“非内容性返工”。diagram-design 要解决的正是这类反复消耗却难以沉淀的问题。它本质上是一套围绕“图表设计”建立的规范化工作方法包含三个层次视觉语言层颜色、字体、间距、图标风格、结构语义层节点类型、连线含义、分组逻辑、协作交付层源文件组织、版本管理、导出规范。很多人只关注第一层结果就是“单张图好看一套图灾难”。我见过一个项目二十多张流程图用了七种不同的蓝色评审时被质疑“是不是不同团队做的”实际上全是一个人画的只是每次都在调色板里随手选。这套方法适合谁如果你是技术文档工程师、产品经理、系统架构师、咨询顾问或者任何需要“用图说话”的角色它都能直接落地。哪怕你只是偶尔画一张汇报用的流程图掌握其中的命名和布局规则也能让图的可读性提升一个档次。它不依赖特定软件Visio、draw.io、Figma、Excalidraw 甚至 PPT 都能用核心是那套“先定规则再画图”的思路。我最初接触这套思路是在一个跨平台系统重构项目里。当时需要输出三十多张状态流转图第一版画完评审会上有人问“这个虚线箭头和那个实线箭头有什么区别”画图的人愣了三秒说“没什么区别当时顺手”。那一刻我意识到图表设计不是美术问题是信息架构问题。diagram-design 的价值就是把这种“顺手”变成“有据可依”。2. 核心设计原则拆解为什么你的图总是“差点意思”2.1 视觉一致性不是好看是降低认知负荷视觉一致性的核心目标不是“美”而是让读者把注意力放在信息上而不是消耗在“这个颜色什么意思”“这个形状为什么不一样”上。我总结了一个三色原则任何一张图主色不超过三种且每种颜色必须有明确的语义绑定。具体操作上我会先定义一个调色板颜色角色用途示例色值使用规则主色核心节点、主要流程#2B6CB0一张图出现频率最高占比约60%辅色次要节点、分支流程#68D391占比约30%与主色形成对比但不抢眼强调色异常、警告、重点标注#E53E3E占比不超过10%只用于需要“被看见”的元素中性色文字、边框、背景#4A5568 / #E2E8F0不承载语义只做支撑这个比例不是随便定的。视觉设计里有个“60-30-10 法则”来自室内设计的配色经验后来被广泛用于界面和图表。它的逻辑是人眼对主色的感知建立整体基调辅色提供层次强调色制造焦点。如果三种颜色各占三分之一读者会不知道先看哪里。注意很多人喜欢用红色表示“错误”、绿色表示“成功”这在状态图里没问题但在架构图里要小心。架构图里的红色节点可能被误解为“有问题的模块”而不是“核心模块”。颜色语义一旦跨图使用必须全局统一。我踩过的一个坑在一个微服务架构图里我用橙色表示“异步调用”用蓝色表示“同步调用”。结果评审时有人问“橙色是不是表示这个服务有风险”。这就是颜色语义没有在团队内对齐的后果。后来我们定了一条规矩任何非状态类图表颜色只用于分组不用于表达“好坏”。2.2 结构语义化让每个形状都有“身份证”图表里的每个元素都应该有明确的语义身份。节点是“服务”“数据库”“队列”还是“外部系统”连线是“数据流”“控制流”“依赖”还是“事件通知”这些如果不提前定义画出来的图就是“一堆框和箭头”。我通常会在项目开始前建一个图例表类似这样元素类型形状边框样式填充语义服务节点圆角矩形实线 2px主色浅色可独立部署的单元数据存储圆柱体实线 2px辅色浅色持久化存储消息队列六边形虚线 2px中性色异步通信通道外部系统矩形双线无填充不在控制范围内的依赖同步调用箭头实线1.5px-请求-响应模式异步消息箭头虚线1.5px-单向事件通知这张表看起来繁琐但它是一次投入、长期受益。后面所有图都按这个来新人接手也能看懂。我见过一个团队把这张表贴在 Confluence 首页新来的工程师画图前先看五分钟省掉了后面无数次的“这个箭头什么意思”。提示图例表不要超过 8 行。超过 8 种元素类型说明你的系统复杂度已经不适合用一张图表达了应该拆成多张图每张图聚焦一个视角。2.3 布局逻辑从左到右还是从上到下布局方向的选择取决于图表的阅读场景。从左到右适合流程类、时序类图表因为人眼水平扫描更自然且符合大多数语言的阅读方向。从上到下适合层级类、决策树类图表因为垂直方向天然表达“上下级”或“递进”关系。但实际项目里我更多用的是混合布局主流程从左到右异常分支从上到下或从下到上。这样既保持了主线的清晰又让分支不干扰主线。关键是要给分支留出足够的“呼吸空间”——我通常会在主流程上下各留出至少 80px 的空白带分支线从空白带穿过避免和主流程的连线交叉。还有一个容易被忽略的点对齐。人眼对不齐的元素极其敏感哪怕只差 2px也会让人觉得“哪里不对”。我的做法是所有节点必须对齐到 8px 的网格。draw.io 和 Figma 都支持网格吸附Visio 需要手动设置。这个习惯一旦养成图的“专业感”会立刻提升。3. 从零搭建一套 diagram-design 规范实操步骤与参数3.1 第一步定义画布与网格系统画布尺寸不是随便选的。我推荐两种规格演示用1920×1080 px适合投屏和导出 PNG 插入 PPT。文档用1280×720 px 或 A4 横向297×210 mm适合嵌入 Confluence、Notion 或 PDF。网格系统我固定用8px 基准。为什么是 8 而不是 10因为 8 是 2 的幂次缩放时不会出现半像素且大多数设计工具默认网格就是 8px。具体设置# draw.io 网格配置参考 grid: 8 gridVisible: true snapToGrid: true snapToPoint: true节点最小尺寸我定为120×48 px这是保证文字不换行、图标不拥挤的下限。如果节点内容多优先增加宽度而不是高度因为宽节点在水平布局里更协调。注意不要用“自动布局”功能来偷懒。自动布局出来的图往往连线混乱、间距不均后期调整的时间比手动布局还长。我试过用自动布局生成一张 30 节点的图结果调整连线花了 40 分钟手动画可能只要 25 分钟。3.2 第二步建立文字层级与命名规范文字层级我分为四级层级用途字号字重颜色L1图标题24pxBold#1A202CL2分组标题16pxSemiBold#2D3748L3节点名称14pxMedium#4A5568L4注释/说明12pxRegular#718096命名规范上我强制要求节点名称用“名词动词”或“名词状态”结构。比如“订单服务-创建订单”“支付网关-处理回调”而不是“创建订单服务”或“支付回调处理”。前者让读者一眼看出“谁在做什么”后者容易混淆“服务”和“动作”。连线命名同样重要。同步调用标注“请求/响应”异步消息标注“事件类型”数据流标注“数据实体”。我见过一张图所有连线都叫“调用”评审时根本分不清哪个是同步哪个是异步。后来我们规定连线标签必须包含“动作对象”比如“发送-订单创建事件”“查询-用户信息”。3.3 第三步图标与插画的使用边界图标能提升图表的可读性但滥用会适得其反。我的原则是图标只用于区分节点类型不用于装饰。比如数据库节点用圆柱体图标队列节点用堆叠线图标服务节点用方块图标。同一类型的节点图标必须完全一致。图标尺寸我固定在16×16 px 或 24×24 px且与文字左对齐。不要用彩色图标除非该颜色有语义。我见过一张图每个节点都配了一个不同颜色的图标结果读者以为颜色代表某种分类实际上只是“好看”。提示如果你用 draw.io可以从“形状库”里拖拽标准图标不要自己画。自己画的图标往往线条粗细不一致缩放后模糊。标准图标库的 SVG 是矢量任意缩放都清晰。3.4 第四步导出与交付规范导出格式取决于使用场景场景格式分辨率背景备注PPT 嵌入PNG2x (3840×2160)透明避免白底在深色 PPT 上突兀文档嵌入SVG矢量透明可缩放文件小打印PDF矢量白色确保线条在纸上清晰在线协作源文件--保留可编辑性我强烈建议始终保留源文件并且源文件命名遵循“项目名-图表类型-版本号”格式比如“订单系统-状态流转图-v3.drawio”。不要用“新建图表(1)”这种名字三个月后你根本找不到。还有一个细节导出 PNG 时边距留 16px。不要紧贴画布边缘否则插入文档后文字会被裁切。draw.io 的“导出”设置里有“边距”选项填 16 即可。4. 实战案例一张微服务架构图的完整设计过程4.1 需求分析与信息分层假设我们要画一个电商系统的微服务架构图。第一步不是打开工具而是列出所有需要表达的信息服务列表用户服务、商品服务、订单服务、支付服务、库存服务数据存储用户库、商品库、订单库、支付库消息队列订单事件队列、库存变更队列外部依赖支付网关、物流系统通信方式同步 REST、异步消息然后分层核心层订单、支付、库存放中间支撑层用户、商品放两侧基础设施层数据库、队列放底部外部层放最右侧。这样读者视线自然从中间向外扩散。4.2 布局计算与坐标规划我习惯先用纸笔算坐标。画布 1920×1080核心层三个服务各宽 200px间距 80px总宽 200×380×2760px居中放置起始 x 坐标为 (1920-760)/2580。y 坐标放在 400 处高度 80px。支撑层两个服务放在核心层两侧x 坐标分别为 580-200-120260 和 5807601201460。y 坐标与核心层对齐。数据库层放在 y700 处每个服务正下方。队列放在数据库层右侧y700。外部系统放在 x1700y400。这些数字看起来机械但提前算好坐标画图时直接输入数值比用鼠标拖拽快得多而且绝对对齐。draw.io 支持在“编辑样式”里直接输入 x/y/width/height我通常一边算一边填。4.3 连线绘制与交叉处理连线是最容易乱的部分。我的规则是同步调用用实线箭头异步消息用虚线箭头。连线尽量不交叉。如果必须交叉用“跳线”表示draw.io 里叫“line jump”。连线标签放在线的中点上方 4px字号 12px颜色 #718096。订单服务调用支付服务实线箭头标签“请求-支付”。支付服务发送支付完成事件到队列虚线箭头标签“支付完成事件”。库存服务从队列消费虚线箭头标签“消费-库存变更”。注意不要用双向箭头表示“互相调用”。双向箭头在复杂图里极难阅读。如果两个服务互相调用画两条单向箭头一上一下中间留 20px 间距。4.4 评审与迭代从“能看”到“好用”第一版画完后我通常会做一次**“三秒测试”**找一个没参与画图的同事给他三秒钟看这张图然后问他“这个系统的核心流程是什么”。如果他说不出来说明图的信息层级有问题。常见问题及调整问题原因调整方法读者先看到数据库而不是服务数据库颜色太深降低数据库填充色饱和度连线像蜘蛛网连线没有分层同步调用走上方异步消息走下方节点文字太小字号低于 12px统一提升到 14px必要时加宽节点外部系统太抢眼用了主色外部系统用灰色边框无填充我印象最深的一次迭代第一版图里消息队列用了和数据库一样的圆柱体只是颜色不同。评审时有人问“这个队列是不是也是数据库”。后来我们把队列改成六边形问题立刻消失。形状的区分度比颜色高得多这是认知心理学里的“前注意加工”原理——形状在视觉处理的早期阶段就被识别而颜色需要更多注意力。5. 常见问题与排查技巧实录5.1 图表“看起来乱”的五个根因很多人觉得图“乱”但说不清哪里乱。我总结了五个根因按出现频率排序对齐不一致节点没有对齐到网格差 1-2px 就会显得杂乱。排查方法全选所有节点看它们的 x/y 坐标是否有非 8 的倍数。间距不统一节点间距有的 40px 有的 60px。排查方法用工具的“分布”功能选择“水平等距分布”。颜色过多超过 5 种颜色。排查方法把图转成灰度如果还能看懂说明颜色不是必需的如果看不懂说明颜色承载了太多语义需要简化。连线交叉过多超过 3 处交叉。排查方法调整节点顺序把关联紧密的节点放在一起。文字层级混乱标题和节点文字一样大。排查方法眯眼看图如果所有文字糊成一团说明层级不够。5.2 协作场景下的版本冲突与解决多人协作画图时最大的问题是“你改了我不知道”。我的做法是源文件放共享目录用“锁定编辑”功能一次只允许一个人编辑。每次修改前先导出 PNG命名为“项目名-图表名-日期-修改人”作为快照。修改后在群里发截图说明改了什么相关人确认。如果团队用 Figma可以用“分支”功能每个人在自己的分支上改最后合并。但 Figma 的图表功能不如 draw.io 专业我通常还是用 draw.io 画导出 SVG 后嵌入 Figma 做最终排版。提示不要用“评论”功能来沟通修改意见。评论容易丢失且无法追溯。我要求所有修改意见写在共享文档里格式为“图名-节点名-修改内容-提出人-日期”。5.3 导出后模糊或变形的排查清单现象可能原因解决方法PNG 模糊导出分辨率太低设置 2x 或 3x 缩放SVG 文字错位字体未嵌入导出时勾选“嵌入字体”或转曲PDF 线条粗细不一缩放导致用矢量导出不要用位图透明背景变黑查看器不支持透明导出时加白色背景或改用 SVG文件过大嵌入太多位图用 SVG 替代 PNG压缩位图我踩过最坑的一次用 draw.io 导出 SVG 插入 Confluence结果文字全部变成方框。原因是 draw.io 默认不嵌入字体而 Confluence 的渲染环境没有那个字体。后来我改成导出 PNG 2x问题解决。如果目标平台不确定PNG 2x 是最稳妥的选择。5.4 独家避坑技巧三个“不要”不要用“自动排列”自动排列的图连线往往绕远路且节点顺序不符合阅读逻辑。手动排列虽然慢但结果可控。不要在节点里写长句节点文字超过 10 个字阅读效率急剧下降。把长句拆成“节点名注释”注释放在节点下方或连线旁。不要用“阴影”和“渐变”这些装饰性效果在缩放后会失真且增加视觉噪音。扁平化设计在图表里永远是最优解。还有一个我个人的习惯画完图后把图缩小到 50% 看一遍。如果缩小后还能看清主流程说明层级清晰如果缩小后一片模糊说明节点太密或文字太小。这个“缩小测试”比任何评审都有效。6. 工具选型与效率提升我实际用过的方案对比6.1 主流工具横向对比工具优势劣势适合场景draw.io免费、开源、形状库全、支持 SVG界面老旧、协作弱技术架构图、流程图Figma协作强、设计感好、组件系统图表功能弱、学习曲线陡产品原型、UI 相关图Excalidraw手绘风格、轻量、快不够正式、对齐弱头脑风暴、草图Visio企业级、模板多收费、笨重传统企业文档Mermaid代码化、版本可控样式受限、布局不可控文档内嵌、自动化生成我个人的组合是draw.io 画正式图Excalidraw 画草图Mermaid 写文档内嵌图。正式图需要精确控制draw.io 最合适草图需要快速表达Excalidraw 的手绘风格反而降低“完成度压力”文档内嵌图需要随代码更新Mermaid 的文本化最方便。6.2 draw.io 的高效配置我有一套 draw.io 的“启动模板”每次新建图直接导入mxGraphModel dx1422 dy798 grid1 gridSize8 guides1 tooltips1 connect1 arrows1 fold1 page1 pageScale1 pageWidth1920 pageHeight1080 math0 shadow0 root mxCell id0 / mxCell id1 parent0 / !-- 预置样式 -- mxCell idstyle-service value服务 stylerounded1;whiteSpacewrap;html1;fillColor#EBF8FF;strokeColor#2B6CB0;strokeWidth2;fontSize14;fontColor#2D3748; vertex1 parent1 mxGeometry x0 y0 width160 height48 asgeometry / /mxCell mxCell idstyle-db value数据库 styleshapecylinder3;whiteSpacewrap;html1;fillColor#F0FFF4;strokeColor#38A169;strokeWidth2;fontSize14;fontColor#2D3748; vertex1 parent1 mxGeometry x0 y0 width120 height60 asgeometry / /mxCell mxCell idstyle-queue value队列 styleshapehexagon;perimeterhexagonPerimeter2;whiteSpacewrap;html1;fillColor#EDF2F7;strokeColor#4A5568;strokeWidth2;fontSize14;fontColor#2D3748; vertex1 parent1 mxGeometry x0 y0 width120 height60 asgeometry / /mxCell /root /mxGraphModel把这个保存为.drawio文件每次新建图时打开它直接拖拽预置样式省去重复设置。我算过这个模板每次能省 3-5 分钟的样式调整时间一个月下来就是好几个小时。6.3 快捷键与操作技巧draw.io 里我高频使用的快捷键CtrlShiftH水平等距分布CtrlShiftV垂直等距分布CtrlShiftU统一尺寸CtrlE编辑样式直接输入坐标和尺寸CtrlShiftL切换连线类型直线/正交/曲线还有一个隐藏技巧按住 Alt 拖拽节点可以复制节点并保持连线。这个在画多个同类服务时特别有用复制出来的节点自动继承样式和连线关系只需要改名字。注意不要用“曲线”连线。曲线在复杂图里极难追踪且交叉时看不清谁连谁。正交连线直角折线虽然看起来“硬”但可读性最高。7. 从单张图到图表系统长期维护的思路7.1 建立图表库与复用机制当项目里的图超过 10 张就需要考虑“图表库”了。我的做法是样式库把常用的节点样式、连线样式、颜色定义保存为 draw.io 的“自定义形状库”。模板库把常见的图表类型架构图、流程图、状态图、时序图做成模板新建时直接套用。图例库把图例表做成独立文件每张图引用同一个图例。这样做的收益是新人画图时不需要重新发明轮子直接套模板出来的图风格统一。我见过一个团队每个人画图前先看“图表规范文档”文档里只有三页颜色表、形状表、命名规则。就这三页让他们的图表质量从“参差不齐”变成“一眼看出是一个团队”。7.2 图表与文档的同步更新图表最大的问题是“过期”。代码改了图没改图就成了误导。我的解决方案是在图表里标注版本号和日期放在右下角字号 10px颜色 #A0AEC0。在文档里引用图表时注明“以代码为准”图表只做辅助理解。每次代码评审时检查相关图表是否需要更新把“更新图表”作为评审清单的一项。如果团队用 Mermaid可以把图表代码和文档放在同一个仓库代码变更时自动触发图表更新。但 Mermaid 的样式控制有限复杂图还是需要手动维护。我的折中方案是核心架构图用 draw.io 手动维护流程类图用 Mermaid 自动生成。7.3 图表设计的“断舍离”最后分享一个我最近才想明白的道理不是所有信息都值得画进图里。一张图能承载的信息量是有限的超过这个限度图就变成了“用图形写的文档”失去了图表的优势。我现在的做法是每张图只回答一个问题。架构图回答“系统由哪些部分组成”流程图回答“一个请求经过哪些步骤”状态图回答“一个实体有哪些状态”。如果一张图想同时回答三个问题那就拆成三张图。这个原则让我砍掉了项目里 40% 的图。剩下的图每张都有人看每张都能看懂。图不在多在于每张都有明确的阅读目的。我见过太多项目图表文件夹里几十张图但真正被引用的不到五张。与其画一堆没人看的图不如把五张核心图打磨到极致。这个内容后续还可以这样扩展如果你团队里有人对颜色不敏感可以专门做一套“灰度图表规范”只用形状和线型区分语义如果图表需要频繁更新可以研究一下用脚本从代码注释里自动生成 Mermaid 图减少手动维护成本。我自己最近在尝试用 Python 脚本从数据库 schema 自动生成 ER 图效果还不错等跑顺了再单独写一篇。
