1. 从一张草图到一套视觉语言diagram-design 到底在解决什么问题很多人第一次听到 diagram-design 这个词会下意识觉得它只是“画图”的另一种说法。但真正在项目里做过架构图、流程图、时序图、部署拓扑图的人都知道画图本身从来不是难点难点在于图与图之间的一致性、可维护性和表达效率。你画第一张架构图的时候可能花十分钟就搞定了配色随意、字体随意、箭头样式随意看起来还挺清爽。等到项目里需要第五张、第十张图的时候问题就来了颜色对不上、线宽不统一、图例缺失、同一个模块在不同图里叫法不一样最后整份文档看起来像是五个人分别做的。diagram-design 要解决的就是这个问题。它不是某个具体的绘图工具也不是某个库的别名而是一套围绕图表设计的系统性方法论加落地规范。你可以把它理解成“给图表做设计系统”的思路先定义一套视觉语言包括颜色语义、形状语义、间距规则、字体层级、连线规范然后再用这套语言去批量生产图表。这样做的好处非常直接——当你需要新增一张图时不需要从零开始纠结“这个框用什么颜色”而是直接查表数据层用蓝色、服务层用绿色、外部依赖用灰色虚线框照着规则拼就行。我最初接触这套思路是因为一个跨平台系统项目。当时项目文档里有二十多张图分别由后端、前端、运维三拨人维护。每次评审总有人问“这个黄色框是什么意思”“为什么这两张图的数据库图标不一样”。后来我们花了两天时间把所有的图停掉先做了一套 diagram-design 规范再回头统一重绘。重绘之后评审时间直接缩短了一半因为大家不再需要花精力去解读图的“方言”而是直接看结构本身。这套方法适合谁如果你是技术文档撰写者、系统架构师、产品经理或者任何需要频繁用图表沟通的人它都能帮你省下大量反复解释和返工的时间。哪怕你只是偶尔画一张流程图了解这套思路也能让你的图看起来更专业、更易读。接下来我会从核心构成、工具选型、实操步骤、常见坑几个角度把这套东西完整拆开讲清楚。2. diagram-design 的四个核心支柱颜色、形状、排版、连线2.1 颜色不是装饰而是语义载体很多人选颜色凭感觉觉得蓝色专业、绿色清新、橙色醒目。但在 diagram-design 里颜色的第一原则是语义固定第二原则才是美观。也就是说一旦你定义了“蓝色代表数据存储”那么所有图里的数据库、缓存、消息队列都必须用蓝色系不能因为这张图里蓝色不好看就换成紫色。具体怎么定我通常建议按“层”来分色。比如一个典型的后端系统图可以分成四层接入层、服务层、数据层、外部依赖。每层给一个主色再给一个浅色作为填充、一个深色作为边框。这样即使图里元素很多读者也能通过颜色快速定位到“这是哪一层的东西”。层级主色填充色边框色适用元素接入层深蓝浅蓝中蓝网关、负载均衡、CDN服务层深绿浅绿中绿微服务、业务逻辑模块数据层深紫浅紫中紫数据库、缓存、消息队列外部依赖深灰浅灰中灰第三方 API、外部系统这张表一旦定下来就贴在团队 wiki 里。任何人画图之前先查表不允许自由发挥。你可能会觉得这样太死板但实际用下来正是这种“死板”换来了跨图一致性。而且当所有人都遵守同一套颜色规则时图与图之间的对比、拼接、复用会变得非常顺畅。还有一个细节颜色数量要克制。我见过一些图用了七八种颜色结果读者根本记不住哪个颜色代表什么。一般来说主色不超过五种加上黑白灰作为辅助足够了。如果确实需要区分更多类别优先用形状或标签来区分而不是继续加颜色。2.2 形状承载角色圆角方角都有讲究颜色之外形状是第二层语义。在 diagram-design 里不同形状代表不同角色这个规则也要提前定好。比如矩形普通服务、模块、组件圆角矩形有状态的东西比如数据库、缓存圆柱体传统数据库的经典符号但现代图里也可以用圆角矩形替代菱形判断节点用于流程图平行四边形输入输出用于数据流图虚线框外部系统或边界之外的东西这些规则看起来是常识但实际画图时很容易被忽略。我见过有人用菱形表示服务用矩形表示判断结果读者完全懵了。所以我的建议是在项目开始前把形状规则写成一页纸的规范附上示例图让所有人照着做。另外形状的尺寸也要有层级。核心模块可以画大一点辅助模块画小一点但同一层级的模块尺寸要一致。不要出现“这个服务框比那个服务框大一圈”的情况除非你确实想表达“这个服务更重要”。但即便如此也建议用颜色或标签来表达重要性而不是用尺寸因为尺寸不一致会破坏整体视觉节奏。2.3 排版决定可读性字体和间距不能随意图表的排版包括字体、字号、对齐方式、间距、留白。这些东西在单张图里可能不明显但多张图放在一起时排版混乱会非常刺眼。字体方面我强烈建议全项目统一使用一种无衬线字体比如思源黑体、Noto Sans、Inter 这类。不要在一张图里混用宋体和黑体也不要用艺术字体。字号一般分三档标题 16-18px正文 12-14px注释 10-11px。同一层级的文字必须用同一字号不能因为“这个标签字多就缩小一点”。对齐方面能对齐就对齐。模块之间的水平间距、垂直间距要一致文字在框内要居中或左对齐统一。我见过一些图模块位置全靠手动拖拽结果间距忽大忽小看起来像随手撒上去的。正确的做法是使用工具的“对齐分布”功能或者直接用网格布局。留白也很关键。图不要太满边缘留出至少 20px 的空白模块之间留出至少 30px 的间距。如果图很复杂可以考虑分块用浅色背景或虚线框把相关模块圈在一起形成视觉分组。2.4 连线是图的血管箭头和路由要统一连线是最容易被忽视的部分。很多人画图时只关心框画得对不对连线随便拉一条结果线交叉、线穿框、箭头方向混乱。diagram-design 对连线的要求有三条方向明确、路由清晰、样式统一。方向明确是指箭头必须指向数据或控制流的方向不能双向箭头满天飞。路由清晰是指连线尽量走直角或平滑曲线避免斜线和交叉。样式统一是指所有同类连线用同一种线型、线宽、箭头样式。比如同步调用用实线箭头异步消息用虚线箭头数据流用带圆点的线。这些规则定好之后图的可读性会大幅提升。另外连线上的标签要放在线的上方或旁边不要压在线上也不要离得太远。3. 工具选型从手绘到代码化哪条路适合你3.1 手绘工具和在线白板的适用边界说到画图工具很多人第一反应是 ProcessOn、Draw.io、Excalidraw 这类。它们的特点是上手快、拖拽方便、适合快速表达。如果你的图不多或者只是内部讨论用这些工具完全够用。但如果你要维护一个长期项目图会频繁更新那手绘工具的劣势就暴露了版本管理困难、样式复用麻烦、批量修改几乎不可能。你改了一个模块的名字得手动去每张图里找。你换了一个主色得一张一张调。这种重复劳动在项目中期会让人非常烦躁。我的经验是探索阶段用手绘工具固化阶段用代码化工具。前期讨论时用 Excalidraw 快速画草图大家看个大概。等结构定下来了再用代码化工具生成正式图纳入版本管理。3.2 代码化绘图工具的核心优势代码化绘图工具比如 Mermaid、PlantUML、Graphviz、D2 这些最大的优势是图即代码。你可以把图的定义写在文本文件里用 Git 管理用 CI 自动生成图片。改一个模块名字只需要改一行文本所有引用它的图都会自动更新。以 Mermaid 为例画一个简单的流程图只需要几行graph TD A[客户端] -- B[网关] B -- C[服务A] B -- D[服务B] C -- E[(数据库)] D -- E这段代码生成的图样式可能不如手绘工具那么精致但胜在可维护。而且 Mermaid 支持自定义主题你可以通过配置文件把颜色、字体、间距统一改掉实现 diagram-design 的规范落地。PlantUML 在时序图和类图上更强Graphviz 在复杂拓扑布局上更灵活D2 则是新兴的声明式绘图语言语法更现代。选择哪个取决于你的主要图类型和团队技术栈。3.3 混合工作流草图用白板定稿用代码实际项目中我推荐一种混合工作流先用白板工具快速勾勒结构确认无误后再用代码化工具重绘定稿。这样做的好处是前期沟通效率高后期维护成本低。具体操作上可以在项目仓库里建一个diagrams目录里面放.mmd或.puml源文件再配一个脚本用命令行工具批量导出 PNG 或 SVG。每次 CI 跑的时候自动检查图是否能正常生成避免源文件语法错误导致图挂掉。提示代码化工具的布局算法有时会出人意料比如把两个本该在一起的模块分得很远。这时候不要硬调而是调整节点声明顺序或加一些不可见的辅助节点来引导布局。4. 落地实操从零搭建一套 diagram-design 规范4.1 第一步盘点现有图表找出共性问题在定规范之前先把你项目里现有的图全部过一遍。不用细看内容只看形式颜色用了多少种字体有几种箭头样式有几种模块命名是否一致把这些问题列出来你就知道规范需要覆盖哪些方面了。我通常会做一个简单的表格把每张图的问题记下来。比如“图3用了橙色表示数据库图7用了蓝色表示数据库”“图5的箭头是实心三角图9的箭头是空心三角”。这些问题就是规范要解决的重点。4.2 第二步定义最小可行规范不要一上来就搞几百页的规范文档没人会看。先定一个最小可行规范覆盖最核心的几件事颜色语义、形状语义、字体字号、连线样式。这四件事定下来图的统一性就能提升 80%。规范文档建议用 Markdown 写放在项目仓库里配上一张示例图。示例图要包含所有颜色和形状的用法让人一眼就能看懂。比如## 颜色规范 - 蓝色 #4A90D9数据存储 - 绿色 #50B86C业务服务 - 灰色 #9B9B9B外部依赖 ## 形状规范 - 矩形无状态服务 - 圆角矩形有状态组件 - 虚线框外部系统4.3 第三步制作模板和片段库规范定好之后下一步是降低执行成本。如果每次画图都要手动调颜色、调字体没人能坚持。所以要做模板和片段库。在 Draw.io 里可以做一个自定义形状库把常用的模块做成拖拽即用的组件。在 Mermaid 里可以写一个主题配置文件把所有样式预定义好。在 PlantUML 里可以用!include引入公共样式文件。我自己的做法是在项目仓库里放一个diagram-theme目录里面包含theme.json颜色和字体定义shapes.xml自定义形状库template.mmdMermaid 模板文件example.png示例图新成员加入时直接把这个目录拷走照着示例图改就行。4.4 第四步建立评审和更新机制规范不是定完就完了还需要评审和更新机制。每次新增图或修改图都要检查是否符合规范。可以在代码评审时加一条如果 PR 里包含图表变更必须检查颜色、形状、字体是否合规。同时规范本身也要定期回顾。如果发现某条规则在实际使用中经常被违反可能是规则本身不合理需要调整。比如我们曾经规定“所有外部依赖必须用灰色虚线框”后来发现有些外部依赖很重要用灰色显得太弱就改成了“核心外部依赖用灰色实线框非核心用灰色虚线框”。5. 踩坑实录那些年我们在图表设计上犯过的错5.1 颜色太多导致图例失效早期做项目时我们觉得颜色越多越好看结果一张图里用了九种颜色。读者看的时候根本记不住哪个颜色代表什么每次都要回头看图例。后来我们砍到四种主色图例直接省了因为读者看一眼就能猜到“蓝色是数据库、绿色是服务”。这个坑的本质是把颜色当装饰而不是语义。颜色一旦超过五种人的短期记忆就跟不上了。所以我的建议是主色不超过五种辅助色用黑白灰特殊强调用红色或橙色但只用于标注重点。5.2 模块命名不一致引发沟通成本另一个常见的坑是模块命名。同一个服务在架构图里叫“用户服务”在时序图里叫“UserService”在部署图里叫“user-svc”。看起来是小事但每次评审都要花时间确认“这三个是不是同一个东西”。解决办法是建立术语表把所有模块的正式名称、缩写、别名都列出来画图时统一使用正式名称。如果图里空间不够可以用缩写但缩写也必须在术语表里定义。5.3 连线交叉导致的阅读障碍连线交叉是图表可读性的头号杀手。我见过一张图十几条线交叉在一起像一团乱麻。读者根本分不清哪条线连哪里。解决连线交叉的方法有几个一是调整模块位置把有连线的模块放近一点二是使用正交路由让线走直角而不是斜线三是分层布局把不同层的模块放在不同水平线上四是如果实在太多拆成多张图不要硬塞在一张图里。5.4 过度追求美观导致维护困难有些人为了图好看用了大量渐变、阴影、3D 效果。单张图确实漂亮但一旦要修改就得重新调所有样式。而且不同人做的图渐变方向、阴影深度都不一样放在一起反而更乱。我的观点是图表的首要目标是清晰传达信息美观是第二位的。扁平化、简洁的风格不仅好看而且好维护。少用特效多用留白和对比效果反而更好。6. 让 diagram-design 融入团队工作流6.1 把图表源文件纳入版本管理图表源文件一定要放进 Git 仓库和代码一起管理。这样做的好处是每次修改都有记录可以回滚可以对比差异。如果图是二进制文件至少也要把源文件放进去导出的图片可以放文档目录。对于代码化工具源文件本身就是文本天然适合版本管理。对于手绘工具可以导出为 XML 或 JSON 格式也能纳入 Git。6.2 在 CI 中自动生成和检查图表如果使用代码化工具可以在 CI 里加一步自动生成图表并检查是否有语法错误。这样能避免源文件改坏了没人发现。更进一步可以把生成的图自动发布到文档站点保证文档里的图永远是最新的。# 示例用 Mermaid CLI 批量生成图表 for file in diagrams/*.mmd; do mmdc -i $file -o docs/images/$(basename $file .mmd).png done6.3 定期做图表审计每隔一个季度或半年把项目里的图全部过一遍检查是否有过时的、重复的、不符合规范的。过时的图直接删掉或归档重复的图合并不符合规范的图重绘。这个工作看起来繁琐但能避免文档里堆积大量无效信息。我自己的习惯是每次大版本发布前花半天时间做一次图表审计。把审计结果记在一个清单里逐项处理。这样文档里的图始终是“活”的而不是一堆没人看的旧图。6.4 培养团队的图表设计意识最后一点也是最重要的一点规范再好没人执行也没用。所以要在团队里培养图表设计意识。新成员入职时把 diagram-design 规范作为培训材料之一。代码评审时把图表质量作为评审项之一。定期分享一些好的图表案例和坏的案例让大家有直观感受。我见过最有效的做法是在团队里设一个“图表守护者”的角色由一个人负责维护规范、审核图表、解答疑问。这个人不一定是领导但一定是对视觉表达有敏感度的人。有了这个角色规范才能真正落地。7. 一些让我少走弯路的实操心得第一先定规范再画图不要边画边定。很多人觉得“我先画几张画着画着规范就出来了”。但实际情况是画着画着就画歪了后面再回头统一成本更高。正确的顺序是先花半天定规范再花半天画图总时间反而更短。第二规范要配示例不要只写文字。文字描述“蓝色代表数据存储”不如直接放一张示例图用蓝色框标出数据库。人是对图像敏感的动物示例图比文字管用十倍。第三工具选型不要追求最新最酷要追求团队能用起来。我见过团队引入了一个很强大的绘图工具结果学习成本太高没人用最后还是回到 Draw.io。工具是手段不是目的。第四图表不是越详细越好。一张图如果塞了五十个模块读者根本看不过来。该拆就拆一张图讲清楚一件事就够了。细节可以放在附录或单独的图里。第五定期清理旧图。项目迭代过程中会产生大量过时的图。这些图如果不清理会干扰读者也会增加维护负担。我的做法是每次大版本发布时把旧图移到archive目录文档里只保留当前版本的图。第六颜色要考虑色盲用户。红绿色盲是最常见的色盲类型如果只用红绿区分这部分用户会看不懂。解决办法是颜色加形状双重编码比如红色用圆形、绿色用方形这样即使分不清颜色也能通过形状区分。第七图里的文字要能选中和搜索。如果导出的是图片文字就变成了像素无法搜索。所以尽量导出 SVG 格式或者在文档里同时提供源文件和图片。这样读者可以搜索关键词快速定位到相关图。第八不要忽视图例的作用。如果图里用了多种颜色或形状一定要加图例。图例放在图的角落不要太大但要清晰。图例的样式也要统一不要这张图图例在左上那张图图例在右下。第九连线上的标签要精简。我见过连线上写了一大段话结果线被文字挡住根本看不清。标签最好控制在五个字以内比如“HTTP”“异步”“写入”。详细说明可以放在图下方的注释里。第十多看图多借鉴。平时看到好的图随手保存下来分析它为什么好。是颜色用得好还是布局清晰还是连线简洁。积累多了自己的图表设计能力自然就上去了。这套 diagram-design 的思路我从第一次尝试到现在已经用了好几年。中间踩过不少坑也总结了不少经验。最大的感受是图表设计不是天赋而是可以习得的技能。只要有一套清晰的规范加上持续的实践和迭代任何人都能画出专业、清晰、易维护的图。希望这些内容能帮你在下一个项目里少走一些弯路把更多时间花在真正重要的事情上。