1. 从一张草图到一套系统：diagram-design 到底在解决什么问题第一次看到 diagram-design 这个词，很多人会以为它只是“画图”的另一种说法。但真正在项目里做过架构图、流程图、时序图、状态机图的人都知道，画图本身从来不是难点，难的是图怎么设计、怎么统一、怎么维护、怎么让不同角色的人都能看懂。diagram-design 这个标题背后，其实指向的是一套完整的“图表设计体系”——它既包含视觉规范，也包含语义约定，还涉及工具链的选型和协作流程的搭建。我最早接触这类需求是在一个跨团队的中台项目里。当时后端、前端、测试、产品四个角色各自画图，后端用一套符号，前端用另一套，产品经理的图更是自成一体。结果就是：同一张业务流程图，四个人画出来四个样子，评审会上光是对齐“这个菱形到底代表判断还是代表子流程”就花了二十分钟。那次之后我才意识到，图表不是画给自己看的，是画给协作网络里的每一个人看的。diagram-design 要解决的，正是这种“图不同源、语义漂移、维护断裂”的问题。具体来说，diagram-design 适合以下几类人：一是需要频繁输出架构图、流程图的技术负责人；二是需要统一团队文档规范的技术写作者；三是产品经理和设计师，他们需要用图来对齐需求；四是任何在文档、博客、教程里需要嵌入高质量图表的内容创作者。不管你用的是 draw.io、Excalidraw、Mermaid、PlantUML 还是 Figma，diagram-design 的思路都能直接套用。这篇文章我会从设计思路、核心细节、实操流程、常见问题四个维度展开，把 diagram-design 从“一个词”拆成“一套可复现的方法”。中间会穿插我踩过的坑、试过的参数、以及那些文档里不会写的经验。你不需要有设计背景，只要画过图、被图坑过，就能直接抄作业。2. 内容整体设计与思路拆解2.1 为什么图表需要“设计”而不是“画”很多人把画图当成一个动作：打开工具，拖几个框，连几条线，导出 PNG，完事。但 diagram-design 的第一性原理是：图表是一种信息压缩格式。它把复杂的系统、流程、状态压缩成二维平面上的节点和边。既然是压缩，就必然有信息损失，而设计的价值就在于——控制损失在哪里发生，确保关键信息不丢。我见过太多“画得很漂亮但没人看得懂”的图。问题出在：作者只考虑了“我要表达什么”，没考虑“读者会怎么读”。一张好的 diagram，应该像一份好的 API 文档——读者不需要问作者，就能自己走通逻辑。这就要求在 design 阶段就确定三件事：图的类型、图的粒度、图的语义层。图的类型决定了基本骨架。流程图用矩形+菱形+箭头，时序图用生命线+消息箭头，状态机用圆角矩形+转移弧。图的粒度决定了信息密度，是画到“服务级”还是“接口级”，是画到“步骤级”还是“任务级”。图的语义层决定了符号约定，比如红色是异常路径、虚线是异步调用、灰色是已废弃模块。这三件事不定，后面画得再好看也是白搭。2.2 方案选型：代码驱动 vs 手绘驱动 vs 混合驱动diagram-design 在工具选型上有一个核心分叉：代码驱动（Diagram as Code）还是手绘驱动（Canvas-based）。我两种都用过，也踩过不少坑，这里直接给结论。代码驱动的代表是 Mermaid、PlantUML、Graphviz。优势是版本可控、diff 友好、容易嵌入 CI。你改一行代码，图自动更新，评审时看 git diff 就知道改了哪条边。劣势是布局不可控，复杂图容易“面条化”，而且学习曲线陡。手绘驱动的代表是 Excalidraw、draw.io、Figma。优势是布局自由、视觉表现力强、适合做演示。劣势是版本管理困难，多人协作容易冲突，改一个框要手动拖半天。我的建议是混合驱动：用代码驱动做“活图”（需要频繁更新、嵌入文档的图），用手绘驱动做“死图”（一次性演示、汇报用的图）。具体分界线是：如果这张图在三个月内会改超过三次，就用代码驱动；如果只是放在 PPT 里讲一次，就用手绘。这个判断标准帮我省了大量返工时间。还有一个容易被忽略的选型维度：输出格式。SVG 适合网页嵌入，PNG 适合文档，PDF 适合打印，Mermaid 源码适合版本控制。diagram-design 的成熟做法是“一份源码，多端输出”。比如用 Mermaid 写源码，导出 SVG 嵌网页，导出 PNG 放文档，源码本身进 git。这样既保证了单一事实来源，又满足了不同场景的展示需求。2.3 视觉规范：颜色、字体、间距的“三三制”diagram-design 的视觉规范我总结为“三三制”：三种颜色、三种字号、三种间距。听起来简单，但执行起来能解决 80% 的“图看起来很乱”的问题。三种颜色：主色（表达核心节点）、辅色（表达次要节点）、警示色（表达异常或重点）。我通常用深蓝做主色，浅灰做辅色，橙红做警示色。不要超过三种，否则读者会开始猜“这个紫色到底代表什么”。三种字号：标题字号（图名）、节点字号（框内文字）、注释字号（边上的说明）。字号差距要明显，比如 18px / 14px / 11px，这样视觉层次自然出来。三种间距：节点内边距、节点间距、图层间距。节点内边距要足够大，让文字不挤；节点间距要一致，不要有的宽有的窄；图层间距要能区分“层”的概念，比如前端层、服务层、数据层。注意：颜色不要只靠色相区分，要考虑色盲用户。深蓝和橙红的明度差要足够大，这样即使看不出颜色，也能靠明暗区分。这套规范的好处是：你不需要每次画图都重新想配色，直接套用即可。团队里其他人也能快速上手，因为规则足够简单。我试过把这套规范写成一页 Markdown 放进团队 wiki，新人在画第一张图之前花五分钟读一遍，后面基本不用再问“这个颜色行不行”。2.4 语义约定：让图“自解释”的关键视觉规范解决“好不好看”，语义约定解决“看不看得懂”。diagram-design 的语义约定包括：形状语义、线型语义、方向语义。形状语义：矩形代表“处理单元”，菱形代表“判断”，圆角矩形代表“开始/结束”，圆柱代表“存储”，平行四边形代表“输入/输出”。这套约定来自传统流程图，但很多人画图时随意混用，导致读者要反复确认。线型语义：实线代表“同步调用”，虚线代表“异步消息”，点线代表“依赖关系”，粗线代表“主路径”。方向语义：从左到右代表“时间顺序”，从上到下代表“层级关系”，双向箭头代表“双向依赖”。这些约定不需要全部用上，但一旦用了，就要全图一致。我见过一张图里实线既表示同步又表示依赖，读者直接懵了。后来我养成一个习惯：每张图下面加一行“图例”，把用到的形状和线型列出来。这行图例花不了两分钟，但能省掉评审会上十分钟的解释。3. 核心细节解析与实操要点3.1 节点设计：从“框里塞字”到“信息分层”新手画图最常见的毛病是：一个框里塞一大段文字，然后字号缩到 8px，导出后根本看不清。diagram-design 的节点设计原则是信息分层：节点标题用短词，节点副标题用一句话，详细说明放在注释或外部文档里。具体操作：节点标题控制在 6 个字以内，比如“用户服务”“订单校验”“库存扣减”。副标题控制在 15 个字以内，比如“负责鉴权与限流”“校验参数与幂等”。如果还需要更多信息，用注释线拉到旁边写，或者加一个编号，在图下方的表格里展开。这样图本身保持清爽，细节又不丢失。节点大小也有讲究。我通常用“最小可读尺寸”作为基准：宽度不小于 120px，高度不小于 60px。小于这个尺寸，文字就会挤。如果节点太多，宁可拆成两张图，也不要缩小节点。拆图的原则是“一张图一个主题”，比如“下单流程”和“支付流程”分开画，中间用“跳转到支付流程”的节点连接。还有一个细节：节点对齐。手动拖拽很容易对不齐，导出后歪歪扭扭。代码驱动工具通常有自动布局，手绘工具则要善用“对齐辅助线”和“分布”功能。我习惯先画完所有节点，全选，然后“水平居中对齐”+“垂直等距分布”，最后再连线。这样出来的图整齐度提升一个档次。3.2 连线设计：避免“面条化”的五个技巧连线是图表设计里最容易翻车的部分。节点一多，线就缠在一起，像一碗面条。diagram-design 的连线设计有五个实操技巧。第一，减少交叉。如果两条线必须交叉，用“跳线”符号（一条小弧线）表示不连接。第二，统一走线方向。主路径从左到右，分支从上到下，不要一会儿左一会儿右。第三，控制连线数量。一个节点连出超过 5 条线，就要考虑拆分子图。第四，标注连线。重要的边加文字说明，比如“超时 3s”“重试 2 次”。第五，用颜色区分路径。主路径用深色，异常路径用警示色，辅助路径用浅灰。提示：Mermaid 里可以用linkStyle给特定边设置颜色和粗细，PlantUML 里可以用-[#red,bold]->语法。手绘工具里则要手动设置线条样式。不管哪种工具，原则都是“主路径最显眼，异常路径最醒目，辅助路径最弱化”。我踩过的一个坑是：连线上的文字太小，导出后看不清。后来我定了一个规矩：连线文字字号不低于节点副标题字号，并且加白色背景描边，这样即使压在线上也能看清。这个细节在 draw.io 里叫“标签背景”，在 Figma 里叫“文本背景”，在 Mermaid 里则需要用 HTML 标签模拟。3.3 布局设计：分层、分区、分组的“三分法”布局是图表的骨架。diagram-design 的布局设计用“三分法”：分层、分区、分组。分层：把系统按逻辑层拆开，比如“接入层”“服务层”“数据层”。层与层之间用水平分隔线或背景色区分。分区：在同一层内，按业务域拆开，比如“用户域”“订单域”“支付域”。分区用垂直分隔线或虚线框区分。分组：在同一业务域内，把相关节点用背景框圈起来，比如“鉴权相关”“限流相关”。这套方法的好处是：读者可以先看层，再看区，再看组，信息接收有节奏。我通常用浅灰背景表示层，用虚线框表示区，用圆角背景表示组。三层视觉嵌套，但颜色深浅不同，不会混淆。布局的另一个关键是留白。新手容易把图塞满，觉得空白是浪费。但留白是阅读的呼吸空间。我通常保证图边缘留出至少 40px 的空白，层与层之间留出 60px，节点之间留出 30px。这些数字不是绝对的，但有一个基准后，调整起来就有参照。3.4 注释与图例：让图“自解释”的最后一公里注释和图例是很多人忽略的部分，但它们是 diagram-design 里“自解释”的关键。注释用来解释特殊节点或连线，图例用来解释符号约定。注释的写法：用一条细线从节点拉到旁边，写上一句话。不要写在节点里面，否则节点会膨胀。注释文字用注释字号，颜色比节点文字浅一度。图例的写法：在图的下方或右侧，列出用到的形状、线型、颜色及其含义。图例不需要很详细，列出“非默认”的即可。比如默认矩形是处理单元，就不需要列；但如果你用了圆柱表示存储，就要列出来。我习惯在图例里加一行“阅读顺序”：从左到右，从上到下。这行字看起来多余，但能帮读者快速建立预期。尤其是给非技术角色看的图，这行字能减少很多“这个箭头是什么意思”的提问。4. 实操过程与核心环节实现4.1 环境准备：工具链的最小可行配置diagram-design 的实操第一步是搭工具链。我的最小可行配置是：Mermaid + VS Code + Markdown Preview Enhanced + draw.io 桌面版。Mermaid 负责代码驱动的图，draw.io 负责手绘驱动的图，VS Code 负责编辑和预览，Markdown Preview Enhanced 负责实时渲染。安装步骤：VS Code 里装 “Markdown Preview Enhanced” 插件，然后在 Markdown 文件里写 Mermaid 代码块，按Ctrl+Shift+P选择 “Markdown Preview Enhanced: Open Preview”，就能实时看到图。draw.io 桌面版直接下载安装，用来画那些 Mermaid 搞不定的复杂布局。如果你团队用 Confluence 或 Notion，它们都内置了 Mermaid 渲染。Confluence 需要装 “Mermaid Diagrams for Confluence” 插件，Notion 则直接用 ```mermaid 代码块。这样图就能直接嵌在文档里，改源码即改图，不用来回导出导入。注意：Mermaid 的版本差异较大，不同渲染器的支持语法不同。建议在项目里锁定一个版本，比如 Mermaid 10.x，避免“本地能渲染、线上报错”的问题。我踩过这个坑，后来在项目根目录放了一个.mermaidrc配置文件，统一版本和主题。4.2 从零画一张架构图：完整步骤拆解下面以一张“订单系统架构图”为例，走一遍完整流程。这张图要表达：用户请求经过网关，进入订单服务，订单服务调用库存服务和支付服务，最后写入数据库。第一步，确定图的类型和粒度。这是架构图，粒度到“服务级”，不展开接口细节。第二步，列出所有节点：用户、网关、订单服务、库存服务、支付服务、订单库、库存库、支付库。第三步，确定分层：接入层（用户、网关）、服务层（订单、库存、支付）、数据层（三个库）。第四步，确定连线：用户→网关（HTTPS）、网关→订单（HTTP）、订单→库存（RPC）、订单→支付（RPC）、订单→订单库（SQL）、库存→库存库（SQL）、支付→支付库（SQL）。第五步，写 Mermaid 源码：flowchart TB subgraph 接入层 U[用户] G[网关] end subgraph 服务层 O[订单服务] I[库存服务] P[支付服务] end subgraph 数据层 OD[(订单库)] ID[(库存库)] PD[(支付库)] end U -->|HTTPS| G G -->|HTTP| O O -->|RPC| I O -->|RPC| P O -->|SQL| OD I -->|SQL| ID P -->|SQL| PD第六步，调整布局和样式。Mermaid 默认布局可能不理想，可以用direction TB控制方向，用classDef定义样式：flowchart TB classDef access fill:#e3f2fd,stroke:#1565c0 classDef service fill:#fff3e0,stroke:#ef6c00 classDef data fill:#e8f5e9,stroke:#2e7d32 class U,G access class O,I,P service class OD,ID,PD data第七步，导出和嵌入。VS Code 里右键预览区，选择 “Export to SVG” 或 “Export to PNG”。SVG 嵌网页，PNG 放文档。源码进 git，下次改图直接改代码。4.3 参数计算：节点间距和字号的经验公式diagram-design 里有一些可以量化的参数。我总结了一个经验公式：节点间距 = 节点平均宽度 × 0.3。比如节点平均宽度 150px，间距就是 45px。这个比例能保证图不挤也不散。字号 = 节点高度 × 0.25。比如节点高度 60px，字号就是 15px。连线文字字号 = 节点字号 × 0.8。比如节点字号 15px，连线文字就是 12px。这些公式不是绝对的，但有一个基准后，调整就有方向。我试过在 draw.io 里用“网格对齐”配合这些参数，画图速度提升明显。Mermaid 里虽然不能精确控制像素，但可以通过nodeSpacing和rankSpacing配置项近似控制。还有一个参数是图的宽高比。我通常控制在 4:3 或 16:9，这样适合屏幕阅读和打印。如果图太宽，就拆成上下两部分；如果太高，就拆成左右两部分。拆图的位置选在“层与层之间”或“区与区之间”，这样拆出来的子图仍然自洽。4.4 版本管理与协作：让图跟上代码的节奏diagram-design 的最后一个实操环节是版本管理。代码驱动的图天然适合 git，因为源码是文本，diff 清晰。手绘驱动的图则要导出为 SVG 或 PNG 后进 git，但 diff 不友好。我的做法是：代码图进 git，手绘图进共享云盘，并在文档里注明“此图最后更新于某日期”。协作方面，代码图用 PR 流程：改图的人提 PR，评审的人看 diff，合并后自动渲染。手绘图用“锁定编辑”模式：一次只有一个人能编辑，编辑完导出新版本，其他人基于新版本继续。这样避免多人同时拖拽导致的冲突。提示：Mermaid 源码里可以加注释，比如%% 2024-06 新增支付服务。这样看 git log 时能快速知道每次改动的原因。我习惯在每次改图时加一行注释，半年后回头看，能省很多回忆时间。5. 常见问题与排查技巧实录5.1 图太乱怎么办：从“面条图”到“清晰图”的排查清单图太乱是最常见的问题。我的排查清单是：第一，节点是否超过 15 个？超过就拆图。第二，连线是否超过 20 条？超过就合并或抽象。第三，是否有节点连出超过 5 条线？有就加中间节点。第四，是否有连线交叉超过 3 次？有就调整布局方向。第五，是否有节点没有连线？有就删掉或补上。按这个清单走一遍，大部分“面条图”都能救回来。如果还乱，就换布局方向：从左到右改成从上到下，或者把环形布局改成树形布局。Mermaid 里可以试flowchart LR和flowchart TB切换，效果差异很大。5.2 渲染报错怎么办：Mermaid 常见错误速查表错误现象可能原因解决方法图不显示，显示代码块渲染器不支持 Mermaid检查插件或平台是否开启 Mermaid报 “Parse error”语法错误，如括号不匹配逐行检查，特别是subgraph和end配对节点文字显示不全节点宽度不够加%%{init: {'flowchart': {'nodeSpacing': 50}}}%%连线文字重叠连线太密减少连线或调整布局方向中文乱码字体不支持指定字体，如fontFamily: "Microsoft YaHei"导出 SVG 后样式丢失样式未内联用classDef而非外部 CSS这张表是我踩坑后整理的，基本覆盖了 90% 的 Mermaid 报错。遇到新错误时，先看控制台报错信息，再对照这张表，通常能快速定位。5.3 团队不配合怎么办：推动 diagram-design 落地的三个策略技术方案再好，团队不用也是白搭。我推动 diagram-design 落地用了三个策略。第一，从痛点入手。先找那个被图坑得最惨的人，帮他画一张清晰的图，让他感受到差异。第二，降低门槛。把模板和规范写成一页文档，新人五分钟能上手。第三，自动化。把图渲染集成到 CI，改代码自动更新图，不用手动操作。这三个策略里，最有效的是“从痛点入手”。我试过直接推规范，响应者寥寥；后来帮一个被评审会折磨的同事画了一张清晰的架构图，他主动来问怎么做的，然后整个组就慢慢用起来了。人都是被痛驱动，不是被规范驱动。5.4 图过期怎么办：让图“活”起来的维护机制图过期是文档的通病。diagram-design 的维护机制是：图与代码同仓库、同 PR、同评审。改代码的 PR 里必须包含图的更新，否则不予合并。这样图就跟着代码走，不会过期。对于手绘图，我设了一个“季度回顾”机制：每季度检查一次手绘图，过期的归档，有效的更新。归档的图移到“历史图”文件夹，并在文档里注明“此图已过期，仅供参考”。这样既保留了历史，又不会误导读者。注意：不要追求“所有图都最新”，那是不现实的。关键是让读者知道“这张图是什么时候的”。我在每张图下面都加一行“最后更新：某年某月”，读者自己判断是否适用。这个习惯帮我避免了很多“拿旧图当新图”的尴尬。6. 从工具到习惯：diagram-design 的长期价值diagram-design 表面上是画图的方法，实际上是信息组织的习惯。当你习惯用分层、分区、分组来思考系统，用形状、线型、颜色来表达语义，用代码、版本、协作来维护图表，你输出的就不只是图，而是一套可传承的知识资产。我在实际使用中发现，最大的收益不是图变好看了，而是沟通成本下降了。以前评审会要花十分钟解释图，现在图自己会说话。以前新人要问“这个模块在哪”，现在图上一目了然。以前改一个逻辑要改五张图，现在改一处源码，五张图自动更新。这个内容后续还可以这样扩展：把 diagram-design 和 API 文档结合，用图自动生成接口依赖关系；和监控系统结合，用图实时展示服务健康状态；和 onboarding 流程结合，用图做新人培训材料。图的边界，其实就是你思考的边界。最后再分享一个小技巧：每次画完图，隔一天再看一遍。如果隔一天你自己都看不懂，那别人肯定也看不懂。这个“隔夜测试”帮我抓出了很多自以为清晰、实际模糊的图。图是给人看的，不是给作者看的。
1. 从一张草图到一套系统：diagram-design 到底在解决什么问题第一次看到 diagram-design 这个词，很多人会以为它只是“画图”的另一种说法。但真正在项目里做过架构图、流程图、时序图、状态机图的人都知道，画图本身从来不是难点，难的是图怎么设计、怎么统一、怎么维护、怎么让不同角色的人都能看懂。diagram-design 这个标题背后，其实指向的是一套完整的“图表设计体系”——它既包含视觉规范，也包含语义约定，还涉及工具链的选型和协作流程的搭建。我最早接触这类需求是在一个跨团队的中台项目里。当时后端、前端、测试、产品四个角色各自画图，后端用一套符号，前端用另一套，产品经理的图更是自成一体。结果就是：同一张业务流程图，四个人画出来四个样子，评审会上光是对齐“这个菱形到底代表判断还是代表子流程”就花了二十分钟。那次之后我才意识到，图表不是画给自己看的，是画给协作网络里的每一个人看的。diagram-design 要解决的，正是这种“图不同源、语义漂移、维护断裂”的问题。具体来说，diagram-design 适合以下几类人：一是需要频繁输出架构图、流程图的技术负责人；二是需要统一团队文档规范的技术写作者；三是产品经理和设计师，他们需要用图来对齐需求；四是任何在文档、博客、教程里需要嵌入高质量图表的内容创作者。不管你用的是 draw.io、Excalidraw、Mermaid、PlantUML 还是 Figma，diagram-design 的思路都能直接套用。这篇文章我会从设计思路、核心细节、实操流程、常见问题四个维度展开，把 diagram-design 从“一个词”拆成“一套可复现的方法”。中间会穿插我踩过的坑、试过的参数、以及那些文档里不会写的经验。你不需要有设计背景，只要画过图、被图坑过，就能直接抄作业。2. 内容整体设计与思路拆解2.1 为什么图表需要“设计”而不是“画”很多人把画图当成一个动作：打开工具，拖几个框，连几条线，导出 PNG，完事。但 diagram-design 的第一性原理是：图表是一种信息压缩格式。它把复杂的系统、流程、状态压缩成二维平面上的节点和边。既然是压缩，就必然有信息损失，而设计的价值就在于——控制损失在哪里发生，确保关键信息不丢。我见过太多“画得很漂亮但没人看得懂”的图。问题出在：作者只考虑了“我要表达什么”，没考虑“读者会怎么读”。一张好的 diagram，应该像一份好的 API 文档——读者不需要问作者，就能自己走通逻辑。这就要求在 design 阶段就确定三件事：图的类型、图的粒度、图的语义层。图的类型决定了基本骨架。流程图用矩形+菱形+箭头，时序图用生命线+消息箭头，状态机用圆角矩形+转移弧。图的粒度决定了信息密度，是画到“服务级”还是“接口级”，是画到“步骤级”还是“任务级”。图的语义层决定了符号约定，比如红色是异常路径、虚线是异步调用、灰色是已废弃模块。这三件事不定，后面画得再好看也是白搭。2.2 方案选型：代码驱动 vs 手绘驱动 vs 混合驱动diagram-design 在工具选型上有一个核心分叉：代码驱动（Diagram as Code）还是手绘驱动（Canvas-based）。我两种都用过，也踩过不少坑，这里直接给结论。代码驱动的代表是 Mermaid、PlantUML、Graphviz。优势是版本可控、diff 友好、容易嵌入 CI。你改一行代码，图自动更新，评审时看 git diff 就知道改了哪条边。劣势是布局不可控，复杂图容易“面条化”，而且学习曲线陡。手绘驱动的代表是 Excalidraw、draw.io、Figma。优势是布局自由、视觉表现力强、适合做演示。劣势是版本管理困难，多人协作容易冲突，改一个框要手动拖半天。我的建议是混合驱动：用代码驱动做“活图”（需要频繁更新、嵌入文档的图），用手绘驱动做“死图”（一次性演示、汇报用的图）。具体分界线是：如果这张图在三个月内会改超过三次，就用代码驱动；如果只是放在 PPT 里讲一次，就用手绘。这个判断标准帮我省了大量返工时间。还有一个容易被忽略的选型维度：输出格式。SVG 适合网页嵌入，PNG 适合文档，PDF 适合打印，Mermaid 源码适合版本控制。diagram-design 的成熟做法是“一份源码，多端输出”。比如用 Mermaid 写源码，导出 SVG 嵌网页，导出 PNG 放文档，源码本身进 git。这样既保证了单一事实来源，又满足了不同场景的展示需求。2.3 视觉规范：颜色、字体、间距的“三三制”diagram-design 的视觉规范我总结为“三三制”：三种颜色、三种字号、三种间距。听起来简单，但执行起来能解决 80% 的“图看起来很乱”的问题。三种颜色：主色（表达核心节点）、辅色（表达次要节点）、警示色（表达异常或重点）。我通常用深蓝做主色，浅灰做辅色，橙红做警示色。不要超过三种，否则读者会开始猜“这个紫色到底代表什么”。三种字号：标题字号（图名）、节点字号（框内文字）、注释字号（边上的说明）。字号差距要明显，比如 18px / 14px / 11px，这样视觉层次自然出来。三种间距：节点内边距、节点间距、图层间距。节点内边距要足够大，让文字不挤；节点间距要一致，不要有的宽有的窄；图层间距要能区分“层”的概念，比如前端层、服务层、数据层。注意：颜色不要只靠色相区分，要考虑色盲用户。深蓝和橙红的明度差要足够大，这样即使看不出颜色，也能靠明暗区分。这套规范的好处是：你不需要每次画图都重新想配色，直接套用即可。团队里其他人也能快速上手，因为规则足够简单。我试过把这套规范写成一页 Markdown 放进团队 wiki，新人在画第一张图之前花五分钟读一遍，后面基本不用再问“这个颜色行不行”。2.4 语义约定：让图“自解释”的关键视觉规范解决“好不好看”，语义约定解决“看不看得懂”。diagram-design 的语义约定包括：形状语义、线型语义、方向语义。形状语义：矩形代表“处理单元”，菱形代表“判断”，圆角矩形代表“开始/结束”，圆柱代表“存储”，平行四边形代表“输入/输出”。这套约定来自传统流程图，但很多人画图时随意混用，导致读者要反复确认。线型语义：实线代表“同步调用”，虚线代表“异步消息”，点线代表“依赖关系”，粗线代表“主路径”。方向语义：从左到右代表“时间顺序”，从上到下代表“层级关系”，双向箭头代表“双向依赖”。这些约定不需要全部用上，但一旦用了，就要全图一致。我见过一张图里实线既表示同步又表示依赖，读者直接懵了。后来我养成一个习惯：每张图下面加一行“图例”，把用到的形状和线型列出来。这行图例花不了两分钟，但能省掉评审会上十分钟的解释。3. 核心细节解析与实操要点3.1 节点设计：从“框里塞字”到“信息分层”新手画图最常见的毛病是：一个框里塞一大段文字，然后字号缩到 8px，导出后根本看不清。diagram-design 的节点设计原则是信息分层：节点标题用短词，节点副标题用一句话，详细说明放在注释或外部文档里。具体操作：节点标题控制在 6 个字以内，比如“用户服务”“订单校验”“库存扣减”。副标题控制在 15 个字以内，比如“负责鉴权与限流”“校验参数与幂等”。如果还需要更多信息，用注释线拉到旁边写，或者加一个编号，在图下方的表格里展开。这样图本身保持清爽，细节又不丢失。节点大小也有讲究。我通常用“最小可读尺寸”作为基准：宽度不小于 120px，高度不小于 60px。小于这个尺寸，文字就会挤。如果节点太多，宁可拆成两张图，也不要缩小节点。拆图的原则是“一张图一个主题”，比如“下单流程”和“支付流程”分开画，中间用“跳转到支付流程”的节点连接。还有一个细节：节点对齐。手动拖拽很容易对不齐，导出后歪歪扭扭。代码驱动工具通常有自动布局，手绘工具则要善用“对齐辅助线”和“分布”功能。我习惯先画完所有节点，全选，然后“水平居中对齐”+“垂直等距分布”，最后再连线。这样出来的图整齐度提升一个档次。3.2 连线设计：避免“面条化”的五个技巧连线是图表设计里最容易翻车的部分。节点一多，线就缠在一起，像一碗面条。diagram-design 的连线设计有五个实操技巧。第一，减少交叉。如果两条线必须交叉，用“跳线”符号（一条小弧线）表示不连接。第二，统一走线方向。主路径从左到右，分支从上到下，不要一会儿左一会儿右。第三，控制连线数量。一个节点连出超过 5 条线，就要考虑拆分子图。第四，标注连线。重要的边加文字说明，比如“超时 3s”“重试 2 次”。第五，用颜色区分路径。主路径用深色，异常路径用警示色，辅助路径用浅灰。提示：Mermaid 里可以用linkStyle给特定边设置颜色和粗细，PlantUML 里可以用-[#red,bold]->语法。手绘工具里则要手动设置线条样式。不管哪种工具，原则都是“主路径最显眼，异常路径最醒目，辅助路径最弱化”。我踩过的一个坑是：连线上的文字太小，导出后看不清。后来我定了一个规矩：连线文字字号不低于节点副标题字号，并且加白色背景描边，这样即使压在线上也能看清。这个细节在 draw.io 里叫“标签背景”，在 Figma 里叫“文本背景”，在 Mermaid 里则需要用 HTML 标签模拟。3.3 布局设计：分层、分区、分组的“三分法”布局是图表的骨架。diagram-design 的布局设计用“三分法”：分层、分区、分组。分层：把系统按逻辑层拆开，比如“接入层”“服务层”“数据层”。层与层之间用水平分隔线或背景色区分。分区：在同一层内，按业务域拆开，比如“用户域”“订单域”“支付域”。分区用垂直分隔线或虚线框区分。分组：在同一业务域内，把相关节点用背景框圈起来，比如“鉴权相关”“限流相关”。这套方法的好处是：读者可以先看层，再看区，再看组，信息接收有节奏。我通常用浅灰背景表示层，用虚线框表示区，用圆角背景表示组。三层视觉嵌套，但颜色深浅不同，不会混淆。布局的另一个关键是留白。新手容易把图塞满，觉得空白是浪费。但留白是阅读的呼吸空间。我通常保证图边缘留出至少 40px 的空白，层与层之间留出 60px，节点之间留出 30px。这些数字不是绝对的，但有一个基准后，调整起来就有参照。3.4 注释与图例：让图“自解释”的最后一公里注释和图例是很多人忽略的部分，但它们是 diagram-design 里“自解释”的关键。注释用来解释特殊节点或连线，图例用来解释符号约定。注释的写法：用一条细线从节点拉到旁边，写上一句话。不要写在节点里面，否则节点会膨胀。注释文字用注释字号，颜色比节点文字浅一度。图例的写法：在图的下方或右侧，列出用到的形状、线型、颜色及其含义。图例不需要很详细，列出“非默认”的即可。比如默认矩形是处理单元，就不需要列；但如果你用了圆柱表示存储，就要列出来。我习惯在图例里加一行“阅读顺序”：从左到右，从上到下。这行字看起来多余，但能帮读者快速建立预期。尤其是给非技术角色看的图，这行字能减少很多“这个箭头是什么意思”的提问。4. 实操过程与核心环节实现4.1 环境准备：工具链的最小可行配置diagram-design 的实操第一步是搭工具链。我的最小可行配置是：Mermaid + VS Code + Markdown Preview Enhanced + draw.io 桌面版。Mermaid 负责代码驱动的图，draw.io 负责手绘驱动的图，VS Code 负责编辑和预览，Markdown Preview Enhanced 负责实时渲染。安装步骤：VS Code 里装 “Markdown Preview Enhanced” 插件，然后在 Markdown 文件里写 Mermaid 代码块，按Ctrl+Shift+P选择 “Markdown Preview Enhanced: Open Preview”，就能实时看到图。draw.io 桌面版直接下载安装，用来画那些 Mermaid 搞不定的复杂布局。如果你团队用 Confluence 或 Notion，它们都内置了 Mermaid 渲染。Confluence 需要装 “Mermaid Diagrams for Confluence” 插件，Notion 则直接用 ```mermaid 代码块。这样图就能直接嵌在文档里，改源码即改图，不用来回导出导入。注意：Mermaid 的版本差异较大，不同渲染器的支持语法不同。建议在项目里锁定一个版本，比如 Mermaid 10.x，避免“本地能渲染、线上报错”的问题。我踩过这个坑，后来在项目根目录放了一个.mermaidrc配置文件，统一版本和主题。4.2 从零画一张架构图：完整步骤拆解下面以一张“订单系统架构图”为例，走一遍完整流程。这张图要表达：用户请求经过网关，进入订单服务，订单服务调用库存服务和支付服务，最后写入数据库。第一步，确定图的类型和粒度。这是架构图，粒度到“服务级”，不展开接口细节。第二步，列出所有节点：用户、网关、订单服务、库存服务、支付服务、订单库、库存库、支付库。第三步，确定分层：接入层（用户、网关）、服务层（订单、库存、支付）、数据层（三个库）。第四步，确定连线：用户→网关（HTTPS）、网关→订单（HTTP）、订单→库存（RPC）、订单→支付（RPC）、订单→订单库（SQL）、库存→库存库（SQL）、支付→支付库（SQL）。第五步，写 Mermaid 源码：flowchart TB subgraph 接入层 U[用户] G[网关] end subgraph 服务层 O[订单服务] I[库存服务] P[支付服务] end subgraph 数据层 OD[(订单库)] ID[(库存库)] PD[(支付库)] end U -->|HTTPS| G G -->|HTTP| O O -->|RPC| I O -->|RPC| P O -->|SQL| OD I -->|SQL| ID P -->|SQL| PD第六步，调整布局和样式。Mermaid 默认布局可能不理想，可以用direction TB控制方向，用classDef定义样式：flowchart TB classDef access fill:#e3f2fd,stroke:#1565c0 classDef service fill:#fff3e0,stroke:#ef6c00 classDef data fill:#e8f5e9,stroke:#2e7d32 class U,G access class O,I,P service class OD,ID,PD data第七步，导出和嵌入。VS Code 里右键预览区，选择 “Export to SVG” 或 “Export to PNG”。SVG 嵌网页，PNG 放文档。源码进 git，下次改图直接改代码。4.3 参数计算：节点间距和字号的经验公式diagram-design 里有一些可以量化的参数。我总结了一个经验公式：节点间距 = 节点平均宽度 × 0.3。比如节点平均宽度 150px，间距就是 45px。这个比例能保证图不挤也不散。字号 = 节点高度 × 0.25。比如节点高度 60px，字号就是 15px。连线文字字号 = 节点字号 × 0.8。比如节点字号 15px，连线文字就是 12px。这些公式不是绝对的，但有一个基准后，调整就有方向。我试过在 draw.io 里用“网格对齐”配合这些参数，画图速度提升明显。Mermaid 里虽然不能精确控制像素，但可以通过nodeSpacing和rankSpacing配置项近似控制。还有一个参数是图的宽高比。我通常控制在 4:3 或 16:9，这样适合屏幕阅读和打印。如果图太宽，就拆成上下两部分；如果太高，就拆成左右两部分。拆图的位置选在“层与层之间”或“区与区之间”，这样拆出来的子图仍然自洽。4.4 版本管理与协作：让图跟上代码的节奏diagram-design 的最后一个实操环节是版本管理。代码驱动的图天然适合 git，因为源码是文本，diff 清晰。手绘驱动的图则要导出为 SVG 或 PNG 后进 git，但 diff 不友好。我的做法是：代码图进 git，手绘图进共享云盘，并在文档里注明“此图最后更新于某日期”。协作方面，代码图用 PR 流程：改图的人提 PR，评审的人看 diff，合并后自动渲染。手绘图用“锁定编辑”模式：一次只有一个人能编辑，编辑完导出新版本，其他人基于新版本继续。这样避免多人同时拖拽导致的冲突。提示：Mermaid 源码里可以加注释，比如%% 2024-06 新增支付服务。这样看 git log 时能快速知道每次改动的原因。我习惯在每次改图时加一行注释，半年后回头看，能省很多回忆时间。5. 常见问题与排查技巧实录5.1 图太乱怎么办：从“面条图”到“清晰图”的排查清单图太乱是最常见的问题。我的排查清单是：第一，节点是否超过 15 个？超过就拆图。第二，连线是否超过 20 条？超过就合并或抽象。第三，是否有节点连出超过 5 条线？有就加中间节点。第四，是否有连线交叉超过 3 次？有就调整布局方向。第五，是否有节点没有连线？有就删掉或补上。按这个清单走一遍，大部分“面条图”都能救回来。如果还乱，就换布局方向：从左到右改成从上到下，或者把环形布局改成树形布局。Mermaid 里可以试flowchart LR和flowchart TB切换，效果差异很大。5.2 渲染报错怎么办：Mermaid 常见错误速查表错误现象可能原因解决方法图不显示，显示代码块渲染器不支持 Mermaid检查插件或平台是否开启 Mermaid报 “Parse error”语法错误，如括号不匹配逐行检查，特别是subgraph和end配对节点文字显示不全节点宽度不够加%%{init: {'flowchart': {'nodeSpacing': 50}}}%%连线文字重叠连线太密减少连线或调整布局方向中文乱码字体不支持指定字体，如fontFamily: "Microsoft YaHei"导出 SVG 后样式丢失样式未内联用classDef而非外部 CSS这张表是我踩坑后整理的，基本覆盖了 90% 的 Mermaid 报错。遇到新错误时，先看控制台报错信息，再对照这张表，通常能快速定位。5.3 团队不配合怎么办：推动 diagram-design 落地的三个策略技术方案再好，团队不用也是白搭。我推动 diagram-design 落地用了三个策略。第一，从痛点入手。先找那个被图坑得最惨的人，帮他画一张清晰的图，让他感受到差异。第二，降低门槛。把模板和规范写成一页文档，新人五分钟能上手。第三，自动化。把图渲染集成到 CI，改代码自动更新图，不用手动操作。这三个策略里，最有效的是“从痛点入手”。我试过直接推规范，响应者寥寥；后来帮一个被评审会折磨的同事画了一张清晰的架构图，他主动来问怎么做的，然后整个组就慢慢用起来了。人都是被痛驱动，不是被规范驱动。5.4 图过期怎么办：让图“活”起来的维护机制图过期是文档的通病。diagram-design 的维护机制是：图与代码同仓库、同 PR、同评审。改代码的 PR 里必须包含图的更新，否则不予合并。这样图就跟着代码走，不会过期。对于手绘图，我设了一个“季度回顾”机制：每季度检查一次手绘图，过期的归档，有效的更新。归档的图移到“历史图”文件夹，并在文档里注明“此图已过期，仅供参考”。这样既保留了历史，又不会误导读者。注意：不要追求“所有图都最新”，那是不现实的。关键是让读者知道“这张图是什么时候的”。我在每张图下面都加一行“最后更新：某年某月”，读者自己判断是否适用。这个习惯帮我避免了很多“拿旧图当新图”的尴尬。6. 从工具到习惯：diagram-design 的长期价值diagram-design 表面上是画图的方法，实际上是信息组织的习惯。当你习惯用分层、分区、分组来思考系统，用形状、线型、颜色来表达语义，用代码、版本、协作来维护图表，你输出的就不只是图，而是一套可传承的知识资产。我在实际使用中发现，最大的收益不是图变好看了，而是沟通成本下降了。以前评审会要花十分钟解释图，现在图自己会说话。以前新人要问“这个模块在哪”，现在图上一目了然。以前改一个逻辑要改五张图，现在改一处源码，五张图自动更新。这个内容后续还可以这样扩展：把 diagram-design 和 API 文档结合，用图自动生成接口依赖关系；和监控系统结合，用图实时展示服务健康状态；和 onboarding 流程结合，用图做新人培训材料。图的边界，其实就是你思考的边界。最后再分享一个小技巧：每次画完图，隔一天再看一遍。如果隔一天你自己都看不懂，那别人肯定也看不懂。这个“隔夜测试”帮我抓出了很多自以为清晰、实际模糊的图。图是给人看的，不是给作者看的。