1. 从一张草图到一套系统diagram-design 到底在解决什么问题很多人第一次听到 diagram-design 这个词脑子里浮现的画面大概是打开某个绘图工具拖几个方框、连几条箭头然后导出一张 PNG 就完事了。如果你也是这么想的那说明你还没被真正的图表需求毒打过。我做了十多年技术方案和架构文档画过的图没有一万也有八千张踩过的坑足够写一本《图表设计血泪史》。diagram-design 这个方向本质上要解决的不是“怎么画一张图”而是“怎么让图表成为一套可维护、可复用、可协作的视觉语言系统”。先把这个概念拆开看。diagram 是图表design 是设计合在一起就是“图表设计”。但这里的“设计”不是指美术层面的好看而是指一套完整的规则体系颜色怎么定、线型怎么分、节点怎么排、标注怎么写、不同层级的图之间怎么保持一致。你可以把它理解成给图表做一套“设计规范”就像前端有设计系统、品牌有视觉识别系统一样图表也需要自己的规范。为什么这件事值得单独拿出来讲因为绝大多数团队在图表上的投入是极度不均衡的。画第一张架构图的时候大家都很认真配色讲究、对齐工整、图例清晰。等到第十张、第二十张的时候就开始放飞自我了有人用蓝色表示服务、有人用蓝色表示数据库箭头一会儿实线一会儿虚线节点大小全凭手感。最后的结果就是每张图单独看都还行放在一起就像出自十个不同团队之手读者每看一张图都要重新建立认知负担。diagram-design 要做的就是终结这种混乱。它适合的人群非常明确技术文档写作者、架构师、产品经理、技术博主以及任何需要频繁产出图表并且希望这些图表保持一致性的人。不管你是用 draw.io、Excalidraw、Figma 还是代码化绘图工具这套思路都能直接套用。接下来的内容我会从底层逻辑讲到具体落地把我在实际项目中反复验证过的方法完整拆开。2. 图表混乱的根源为什么你的图越画越乱2.1 缺少“视觉语法”导致的认知灾难语言有语法音乐有乐理图表同样需要一套“视觉语法”。所谓视觉语法就是规定什么视觉元素对应什么含义的规则集合。比如圆角矩形代表服务、直角矩形代表数据存储、菱形代表判断节点、虚线箭头代表异步调用、实线箭头代表同步调用。这套规则一旦确定读者看第一张图的时候学习一次后面所有图都能直接套用认知成本急剧下降。但现实情况是大多数团队根本没有这套规则。每个人凭直觉画图直觉又各不相同。A 同学觉得数据库应该用圆柱体B 同学觉得用矩形加个标签就行C 同学干脆画个云朵表示“数据存在某处”。结果就是同一份文档里的三张图读者需要建立三套认知模型。这不是读者的理解能力有问题是图表设计者没有提供一致的视觉语法。我见过最夸张的一个案例某项目的架构文档里光是“服务”这个概念就用了四种不同的图形表示圆角矩形、直角矩形、带阴影的矩形、以及一个不知道从哪抄来的六边形。问作者为什么回答是“画到后面忘了前面用的什么”。这就是没有规范的典型症状。2.2 工具切换带来的风格断裂第二个常见根源是工具切换。很多人的工作流是这样的画架构图用 draw.io画流程图用 ProcessOn画原型图用 Figma画思维导图用 XMind。每个工具都有自己的默认样式、默认字体、默认配色。你在 draw.io 里调好的蓝色到了 Figma 里可能因为色彩空间不同而显示成另一种蓝。你在 ProcessOn 里设置的圆角半径到了 Excalidraw 里根本没有这个参数。这种风格断裂在单人工作时还能忍一旦进入团队协作就是灾难。张三用工具 A 画的图和李四用工具 B 画的图放在同一份文档里视觉上就像两个不同时代的产物。更麻烦的是当需要修改时你甚至找不到原始文件在哪里只能对着导出的 PNG 干瞪眼。2.3 缺乏“图表资产”的复用意识第三个根源是复用意识薄弱。大多数人画图是一次性的需求来了画一张需求变了重新画一张旧图直接丢弃。但实际上图表中有大量元素是可以复用的图例、配色方案、节点样式、连线风格、标注格式。如果你每次画图都从零开始不仅效率低下而且一致性根本无法保证。真正高效的做法是把图表当成“资产”来管理。建立一套基础模板包含预设好的配色、字体、节点样式、连线样式。每次画新图时基于模板开始而不是从空白画布开始。这样既能保证一致性又能大幅提升效率。我在实际项目中推行这套方法后画一张标准架构图的时间从平均 40 分钟降到了 15 分钟左右而且风格统一度肉眼可见地提升了。3. 建立视觉语法的四个核心维度3.1 形状语义让每个图形都有固定含义形状是图表中最基础的视觉元素也是最容易产生歧义的。建立形状语义的第一步是确定你的图表中会出现哪些“概念类型”。以技术架构图为例常见的概念类型包括服务、数据库、消息队列、缓存、外部依赖、用户、网关等。每种概念类型分配一个固定的形状并且严格遵守。这里有一个关键原则形状的数量要克制。我见过有人设计了十几种形状结果自己都记不住。一般来说5 到 8 种形状足够覆盖绝大多数场景。下面是我在实际项目中常用的一套形状语义表你可以直接参考概念类型推荐形状说明服务/应用圆角矩形圆角半径统一为 8px数据存储圆柱体数据库、缓存统一用这个消息中间件六边形与普通服务区分开外部系统虚线矩形表示不在掌控范围内用户/角色圆形人形图标也可以但圆形更简洁判断/分支菱形流程图专用分组/边界虚线圆角矩形表示逻辑分组或网络边界这套表看起来简单但威力在于“强制一致性”。一旦团队达成共识所有人画图时都从这张表里选形状不再凭感觉发挥。新人加入时看一眼这张表就能上手不需要反复问“这个用什么形状”。3.2 色彩系统用颜色传递信息而不是装饰颜色在图表中的作用被严重低估了。大多数人用颜色只是为了“好看”但实际上颜色是传递信息的高效手段。关键在于建立一套色彩系统让每种颜色都有明确的语义。我的建议是采用“主色 语义色”的结构。主色用于普通节点和连线通常选中性色灰色系保证不抢眼。语义色用于表达特定含义比如绿色表示正常/健康、黄色表示警告/降级、红色表示故障/异常、蓝色表示外部依赖。这样读者扫一眼就能通过颜色判断系统状态不需要逐字阅读。具体操作上我通常会在设计工具里建立一套色板包含 5 到 7 个颜色每个颜色标注好用途。比如中性灰 #4A5568普通节点边框和文字浅灰 #E2E8F0普通节点填充语义绿 #38A169正常状态语义黄 #D69E2E警告状态语义红 #E53E3E异常状态语义蓝 #3182CE外部依赖或高亮背景白 #FFFFFF画布背景这套色板的好处是颜色数量少、对比度足够、打印和屏幕显示都清晰。更重要的是它避免了“彩虹图”的出现。我见过太多图表用了十几种颜色结果读者根本不知道哪种颜色代表什么颜色反而成了噪音。3.3 连线规则箭头方向、线型和粗细的约定连线是图表中最容易混乱的部分。箭头方向不统一、线型随意切换、粗细全凭手感这些问题几乎每个团队都遇到过。建立连线规则的核心是回答三个问题方向怎么定、线型怎么分、粗细怎么用。方向方面我强烈建议统一采用“从左到右”或“从上到下”的主流向。不要一会儿左到右、一会儿右到左、一会儿又下到上。人的阅读习惯是有方向的顺应这个方向能大幅降低理解成本。如果确实需要反向连线用颜色或线型区分而不是改变方向。线型方面实线表示同步调用或强依赖虚线表示异步调用或弱依赖点线表示可选或未来规划。这个规则简单好记而且视觉区分度足够。粗细方面我通常只用两种1px 用于普通连线2px 用于强调关键路径。不要用更多粗细等级因为人眼对线宽的辨别能力有限太多等级反而造成困惑。还有一个容易被忽略的细节连线的标签位置。标签应该放在连线的中点附近并且保持一致的偏移量。如果一会儿标签在线上方、一会儿在线下方、一会儿又压在线上视觉上会非常杂乱。统一放在线上方 4px 处或者统一放在线下方选一种并坚持。3.4 排版与间距对齐、留白和层级排版是图表设计中“看不见的功夫”。一张图看起来舒不舒服很大程度上取决于对齐和留白。对齐方面核心原则是“能对齐就对齐”。节点之间的水平间距、垂直间距、连线与节点的连接点都应该遵循统一的网格系统。我通常用 8px 作为基础网格单位所有间距都是 8 的倍数8、16、24、32、48。留白方面很多人舍不得留白恨不得把画布塞满。但留白不是浪费空间而是给读者呼吸的余地。节点之间保持足够的间距分组之间留出明显的空隙画布边缘留出边距。这些留白让图表看起来更专业、更易读。层级方面通过大小、颜色深浅、线宽来区分信息的主次。核心节点可以稍大一些、颜色稍深一些辅助节点则相反。但要注意层级差异要适度不要做成“大小不一、颜色各异”的混乱局面。一般来说两到三个层级足够表达绝大多数场景。4. 从规范到落地一套可执行的 diagram-design 工作流4.1 建立基础模板一次投入长期受益规范定好了接下来要解决“怎么让规范落地”的问题。最有效的方式是建立基础模板。模板里预置好色板、字体、节点样式、连线样式、网格设置。每次画新图时复制模板而不是从空白开始。以 draw.io 为例你可以创建一个模板文件里面包含预设的色板在“编辑颜色”里保存自定义颜色、预设的节点样式画好一个圆角矩形设置好填充色、边框色、圆角半径、字体然后保存为默认样式、预设的连线样式设置好线型、箭头、颜色保存为默认。这样每次新建图时直接调用这些预设不需要重新调整。Figma 用户可以用 Components 和 Styles 来实现同样的效果。把常用节点做成 Component把颜色和文字样式做成 Shared Styles。画图时直接从组件库拖拽风格自动统一。Excalidraw 虽然主打手绘风格但也支持自定义颜色和字体可以建立一套自己的预设。模板的维护也很重要。当规范更新时同步更新模板并通知团队成员。我通常会在模板文件里加一个“版本说明”页面记录每次修改的内容和日期方便追溯。4.2 命名与组织让图表资产可检索图表画多了之后管理就成了问题。我见过很多人的图表文件命名是“未命名-1”、“未命名-2”、“新建文件”、“最终版”、“最终版2”、“真正最终版”。这种命名方式在文件少的时候还能忍一旦超过二十张图找起来就是噩梦。我的建议是建立一套命名规范包含四个要素项目/模块名、图表类型、版本号、日期。比如“支付系统-架构图-v2-20240115”。这样命名有几个好处按名称排序时自动按项目分组、一眼能看出图表类型和版本、日期方便追溯历史。组织方面建议按项目或模块建立文件夹每个文件夹里再按图表类型分子文件夹。比如图表资产/ ├── 支付系统/ │ ├── 架构图/ │ ├── 流程图/ │ └── 时序图/ ├── 用户系统/ │ ├── 架构图/ │ └── 流程图/ └── 公共模板/ ├── 基础模板.drawio └── 色板参考.png这套结构看起来简单但能节省大量找文件的时间。更重要的是它让图表资产变得“可管理”而不是散落在各处的孤儿文件。4.3 协作流程多人画图如何保持一致性团队协作是图表一致性的最大挑战。三个人画同一份文档的图如果没有协作流程结果一定是三种风格。解决这个问题的关键是建立“画图前对齐、画图中检查、画图后审核”的流程。画图前对齐在开始画图之前先确认使用哪套模板、哪套色板、哪套形状语义。如果项目有特殊需求先讨论并更新规范而不是各自发挥。这个步骤只需要几分钟但能避免大量的返工。画图中检查画图过程中定期检查是否偏离了规范。我通常会在画完初稿后把图缩小到 50% 看一下整体效果。如果缩小后看起来杂乱说明对齐、间距或颜色有问题。这个“缩小检查法”非常有效因为缩小后细节被模糊整体结构的问题会暴露出来。画图后审核图完成之后让另一位团队成员快速过一遍检查是否符合规范。审核的重点不是“好不好看”而是“是否一致”形状语义是否统一、颜色使用是否正确、连线规则是否遵守、命名是否规范。这个步骤能拦住绝大多数不一致的问题。4.4 版本管理图表也需要迭代记录图表不是一次性的它会随着系统演进而更新。如果没有版本管理你会遇到“这张图是什么时候的”、“改了哪里”、“为什么改”这些问题。解决方法是给图表加版本管理。最简单的方式是在图表文件里加一个“版本记录”区域记录每次修改的内容、日期和修改人。比如版本日期修改内容修改人v12024-01-10初版某开发者v22024-01-15增加缓存层某开发者v32024-01-20调整服务分组A同学这个记录不需要很复杂但能解决大问题。当有人问“这张图为什么和上次不一样”时你直接指向版本记录就行。另外建议保留历史版本的文件不要直接覆盖。可以在文件名里加版本号或者用文件夹区分。5. 工具选型不同场景下的 diagram-design 实践5.1 手绘风格 vs 精确风格什么时候用哪种图表风格大致分为两类手绘风格和精确风格。手绘风格以 Excalidraw 为代表线条略带抖动、字体偏手写感整体氛围轻松。精确风格以 draw.io、Figma 为代表线条笔直、对齐精准、视觉严谨。选择哪种风格取决于使用场景。手绘风格适合头脑风暴、早期讨论、非正式分享、需要营造“还在思考中”氛围的场景。它的优势是降低“完成度”的预期让读者更愿意提出修改意见。精确风格适合正式文档、架构评审、对外发布、需要长期维护的场景。它的优势是专业、严谨、经得起推敲。我的建议是不要混用。一份文档里如果既有手绘风格的图又有精确风格的图视觉上会非常割裂。要么全用手绘要么全用精确保持统一。如果确实需要两种风格用在不同类型的文档里而不是同一份文档里。5.2 代码化绘图当图表需要频繁更新时如果你的图表需要频繁更新比如随着代码变更自动更新架构图那么代码化绘图工具值得考虑。这类工具用文本描述图表然后渲染成图片。常见的包括 Mermaid、PlantUML、Graphviz 等。代码化绘图的优势很明显图表即代码可以纳入版本管理修改方便改几行文本就能更新整张图风格统一因为渲染引擎是同一套。但劣势也很明显样式控制能力有限很难做出精细的视觉效果学习成本较高需要掌握特定的语法。我的经验是如果图表更新频率高、样式要求不高用代码化绘图如果图表更新频率低、样式要求高用可视化工具。两者也可以结合用代码化工具生成初稿再导入可视化工具精修。但要注意精修后的图就无法自动更新了需要手动同步。5.3 团队协作工具的选择标准团队协作场景下工具选择需要考虑几个关键因素实时协作能力、版本历史、评论功能、导出格式、以及是否支持自定义模板。实时协作能力是基础。如果两个人不能同时编辑一张图协作效率会大打折扣。版本历史很重要能追溯每次修改。评论功能方便讨论和反馈。导出格式要丰富至少支持 PNG、SVG、PDF。自定义模板决定了能否落地 diagram-design 规范。综合来看Figma 在协作方面最强但学习成本较高。draw.io 免费且功能全面协作能力稍弱但够用。Excalidraw 轻量且支持实时协作但样式控制有限。我的建议是如果团队已经在用 Figma直接用 Figma 画图如果没有draw.io 是最稳妥的选择。6. 实操中的坑与经验那些文档不会告诉你的事6.1 颜色在导出后“变样”的问题这是一个非常隐蔽的坑。你在设计工具里调好的颜色导出成 PNG 后可能看起来不一样。原因通常是色彩空间不同设计工具用 sRGB导出时可能转成了其他色彩空间或者导出设置里的色彩配置不对。解决方法是导出时明确选择 sRGB 色彩空间并且关闭任何“自动优化颜色”的选项。如果导出后颜色仍然不对检查设计工具的色彩设置确保和导出设置一致。另外如果图表要打印还要考虑 CMYK 色彩空间的转换问题打印出来的颜色通常比屏幕暗一些。我的经验是重要图表导出后一定要在目标环境里检查一遍。如果是在网页上展示就在浏览器里看如果要打印就先打一张样张。不要假设“屏幕上看着对导出后也对”。6.2 字体缺失导致的排版错乱字体是另一个容易出问题的地方。你在本地用了一款特殊字体导出后发给别人别人打开时字体缺失系统自动替换成默认字体结果排版全乱了。文字溢出、换行位置改变、对齐失效各种问题都会出现。解决方法是要么使用系统通用字体如 Arial、Helvetica、思源黑体要么在导出时把文字转成轮廓SVG 支持PNG 不支持。如果必须用特殊字体就在文档里附上字体文件或者导出成 PDF 并嵌入字体。我的建议是图表字体尽量用通用字体不要为了“好看”而用特殊字体。图表的重点是传递信息不是展示字体。通用字体在绝大多数环境下都能正常显示省去了大量麻烦。6.3 图表过大导致的性能问题当图表节点超过一定数量时设计工具可能会变卡。我遇到过一张包含 200 多个节点的架构图在 draw.io 里编辑时卡顿明显每次拖动节点都要等一两秒。这不仅影响效率还影响心情。解决方法是拆分图表。一张图不要试图表达所有内容按层次拆分。比如总体架构图只展示核心模块每个模块的详细图单独画。这样每张图的节点数量可控编辑流畅读者也更容易理解。如果确实需要在一张图里展示大量节点可以考虑用“分组折叠”功能把不重要的分组折叠起来减少渲染压力。或者用代码化绘图工具它们通常对大量节点的处理更好。6.4 图表与文档不同步的尴尬这是最常见也最尴尬的问题文档更新了图表没更新或者图表更新了文档没更新。读者看到的信息不一致轻则困惑重则误导。解决方法有两个方向。一是流程上把图表更新纳入文档更新的检查清单每次改文档时检查相关图表是否需要同步。二是工具上如果图表是代码化的可以纳入 CI 流程代码变更时自动更新图表。如果图表是手工画的至少在图表里标注“最后更新日期”提醒读者注意时效性。我的经验是在图表旁边加一行小字“基于 v2.3 版本绘制最后更新于 2024-01-15”。这样读者能判断图表是否还准确。如果图表已经过时至少他们知道。6.5 过度设计当规范变成负担最后说一个反向的坑过度设计。有些人建立了非常复杂的规范颜色有二十种、形状有十五种、连线规则有八条。结果画图时光是对照规范就要花十分钟效率反而降低了。规范的目的是提升效率和一致性不是增加负担。如果一套规范让画图变得更慢、更痛苦那它就是失败的。我的建议是规范从简够用就好。先建立最小可用的规范比如五种形状、五种颜色、三条连线规则在实际使用中逐步完善。不要一开始就追求完美那只会让你放弃。我在实际项目中的体会是一套好的 diagram-design 规范应该让新人能在十分钟内学会让老人能在不查手册的情况下记住。如果做不到这两点规范就需要简化。7. 让图表成为团队的视觉资产回到最初的问题diagram-design 到底在解决什么它解决的不是“怎么画图”而是“怎么让图表成为团队共有的视觉资产”。当一套视觉语法建立起来之后图表就不再是某个人的即兴创作而是团队认知的载体。新人看图表能快速理解系统老人看图表能快速回忆细节跨团队看图表能快速对齐认知。这套方法的核心其实就三件事定义规则、建立模板、坚持执行。规则不需要多复杂模板不需要多精美执行不需要多严格关键是“有”和“坚持”。我见过太多团队在规范上花了大量时间结果执行了两周就放弃了。反而是那些规则简单、执行松散的团队因为坚持得久最终形成了一致性。如果你现在正准备开始整理团队的图表规范我的建议是从一张图开始。选一张最常用的图表类型定义它的形状、颜色、连线规则做成模板然后用这个模板画接下来十张图。十张之后你会看到明显的一致性提升。然后再扩展到其他图表类型。不要试图一次定义所有规则那只会让你陷入分析瘫痪。图表设计的本质是沟通。每一张图都是在和读者对话而 diagram-design 就是确保这场对话清晰、一致、不产生歧义。工具会变、风格会变但这个本质不会变。
入门实战：从环境搭建到CSV转Excel)
