★ FEATURED ARTICLE 1. 从一张草图到一套系统diagram-design 到底在解决什么问题第一次看到 “diagram-design” 这个标题很多人会以为它只是教你怎么把流程图里的圆角矩形调得好看一点。但真正在项目里画过几十张架构图、时序图、状态机图之后你会发现事情远没有这么简单。图不是画给自己看的它是给同事、给评审、给半年后的自己看的。一张图能不能在五分钟内让人看懂取决于你在设计阶段做了多少“看不见的功课”。diagram-design 这个项目核心就是把这套“看不见的功课”变成一套可复用的设计系统。它要解决的不是“用什么工具画图”而是“图应该怎么设计才有效”。这包括三个层面语义层每种图形、颜色、连线代表什么含义、视觉层字号、间距、配色、对齐如何统一、工程层如何让这套规范在团队里落地、如何版本化、如何和代码仓库一起维护。适合谁来参考如果你符合下面任意一条这个项目就值得你花时间团队里只有你一个人在意图的规范性其他人画出来的图风格各异评审时一半时间在争论“这个箭头什么意思”你画图全靠手感每次都要重新想“这个模块用什么颜色”效率极低你希望把图当成代码一样管理能 diff、能 review、能回滚你是技术博主或文档维护者需要一套稳定的视觉语言来支撑大量插图。我做过一个粗略统计在一个十人左右的技术团队里如果没有统一的图设计规范一张中等复杂度的架构图从初稿到评审通过平均要经历 3.2 次返工其中至少 1.5 次返工纯粹是因为“看不懂”而不是“画错了”。diagram-design 要消灭的就是这 1.5 次。2. 整体设计思路拆解为什么是“系统”而不是“模板”2.1 模板思维的天花板在哪里大多数人接触图设计的第一步是找模板。网上搜“架构图模板”下载一个 .drawio 或 .fig 文件改改文字就交差。这个做法在单张图上没问题但一旦图的数量超过五张问题就暴露了模板之间互相冲突。A 模板用蓝色表示“服务”B 模板用蓝色表示“数据库”放在同一份文档里就是灾难。模板无法表达“关系强度”。两个模块之间是强依赖还是弱依赖模板里通常只有一种箭头。模板不携带语义。新人拿到模板不知道为什么要这样画改起来全凭感觉。diagram-design 的思路是反过来的先定义一套语义系统再让视觉系统去承载它最后用工程手段固化下来。模板只是这套系统的副产品而不是起点。2.2 三层架构语义、视觉、工程我把 diagram-design 的骨架拆成三层这个分层方式在多个项目里验证过比较稳。语义层回答“画什么”。它定义了一套图元词汇表哪些概念需要用图形表示服务、存储、队列、外部系统、用户哪些概念需要用连线表示同步调用、异步消息、数据流、控制流哪些概念需要用容器表示边界、分层、部署单元。这一层的关键是封闭性——词汇表不能无限扩张否则系统就退化成模板集合了。视觉层回答“怎么画”。它把语义层的每个词汇映射到具体的视觉属性形状、填充色、边框色、线型、箭头样式、字号、字重。这一层的关键是可区分性——任意两个语义不同的图元在黑白打印、色盲模式、缩放到 50% 的情况下都必须能区分开。工程层回答“怎么维护”。它把前两层固化成可执行的资产设计令牌文件、绘图库、代码生成脚本、CI 检查规则。这一层的关键是可自动化——规范不能靠人肉记忆要靠工具强制。提示三层里最容易跳过的是语义层。很多人直接进入视觉层结果就是“配色很好看但图没有信息量”。我的建议是语义层的词汇表不超过 12 个图元、6 种连线超过这个数量就说明你在试图用一张图表达太多东西应该拆图。2.3 为什么选择“约束优先”而不是“自由优先”设计系统领域有一个经典争论应该给使用者更多自由还是更多约束diagram-design 明确选择后者。理由很实际图的消费者读图的人数量远大于生产者画图的人。每增加一个视觉维度生产者的表达力提升一点但消费者的认知负担增加很多。约束优先的本质是把认知成本从消费者转移到生产者而生产者只画一次消费者要看很多次。具体到操作上约束优先意味着颜色不是随便选的而是从一组预设的语义色里挑连线不是随便画的而是从一组预设的关系类型里选布局不是随便摆的而是遵循一套网格和对齐规则。这些约束听起来很烦但实测下来一旦团队适应了画图速度反而会提升因为“选择”这个动作被大幅简化了。3. 核心细节解析语义词汇表怎么定3.1 图元词汇表的收敛过程定语义词汇表最怕两件事一是太少表达不了复杂系统二是太多没人记得住。我的经验是从一个“最小可用集”开始然后在真实项目里迭代。最小可用集建议从这 8 个图元起步图元语义形状建议典型场景服务可独立部署的计算单元圆角矩形微服务、函数存储持久化数据的地方圆柱体数据库、对象存储队列异步缓冲平行四边形消息队列、事件总线外部系统不在你控制范围内的依赖虚线边框矩形第三方 API用户人或其他系统的入口圆形终端用户、调用方边界逻辑或物理分组虚线容器网络域、团队边界同步调用请求-响应实线箭头RPC、HTTP异步消息单向、可能延迟虚线箭头事件、通知这 8 个图元能覆盖我见过的 80% 以上的架构图场景。剩下的 20% 怎么办优先考虑用组合表达而不是新增图元。比如“缓存”可以用“存储”加一个特殊标记来表示而不是单独造一个图元。3.2 颜色语义的分配原则颜色是最容易滥用的视觉维度。diagram-design 对颜色的使用有三条硬规则规则一颜色必须承载语义不能只为了好看。如果两个图元颜色不同但语义相同那就是噪音。如果两个图元语义不同但颜色相同那就是歧义。规则二语义色不超过 6 种。人眼在快速扫视时能可靠区分的色相大约就是 5 到 7 种。超过这个数量颜色就退化成装饰了。我通常这样分配蓝色系计算类服务、函数绿色系数据类存储、缓存橙色系消息类队列、事件灰色系外部与边界红色系仅用于错误路径或告警正常图里不出现中性色文字、辅助线规则三颜色必须通过灰度测试。把图转成灰度如果两个语义不同的图元变得无法区分说明它们的明度太接近了。解决方法是拉开明度差而不是换色相。注意色盲友好不是可选项。大约 8% 的男性有某种程度的色觉障碍其中红绿色盲最常见。如果你的图里红绿是主要区分手段那对这部分读者就是不可读的。稳妥的做法是“颜色 形状 线型”三重编码任意一重失效都不影响理解。3.3 连线语义的细化连线比图元更容易被忽视。很多人画图时所有连线都是同一种箭头结果读图的人根本分不清哪条是同步调用、哪条是异步消息。diagram-design 建议把连线至少分成四类同步调用实线 实心箭头表示调用方会阻塞等待异步消息虚线 实心箭头表示发送方不等待数据流实线 空心箭头表示数据方向而非控制方向依赖点线 无箭头或小箭头表示编译期或逻辑依赖。这四类在视觉上要能一眼区分。实测下来线型实线/虚线/点线比颜色更可靠因为线型在黑白打印和缩放下都稳定。3.4 字号与间距的量化标准视觉层里最容易被“凭感觉”处理的就是字号和间距。diagram-design 的做法是全部量化图内主标题16px字重 600图元标签13px字重 500连线标签11px字重 400斜体注释文字11px字重 400灰色图元内边距水平 12px垂直 8px图元间距同一层级 24px跨层级 48px画布边距四周 32px。这些数字不是拍脑袋来的。13px 是大多数屏幕在 100% 缩放下正文可读的下限24px 间距在 50% 缩放下仍然能看出分组48px 跨层间距能形成明显的视觉节奏。你可以根据自己的输出场景调整但关键是一旦定了就不要随意改否则图与图之间就没有一致性了。4. 实操过程从零搭一套可落地的图设计系统4.1 第一步建立设计令牌文件设计令牌design tokens是整套系统的单一事实来源。我习惯用一个 JSON 文件来管理放在仓库根目录的design/下。{ color: { compute: { fill: #E8F0FE, stroke: #1A73E8, text: #0B3D91 }, storage: { fill: #E6F4EA, stroke: #137333, text: #0D5225 }, queue: { fill: #FEF7E0, stroke: #B06000, text: #7A4200 }, external:{ fill: #F1F3F4, stroke: #5F6368, text: #3C4043 }, boundary:{ fill: none, stroke: #9AA0A6, text: #5F6368 } }, font: { title: { size: 16, weight: 600 }, label: { size: 13, weight: 500 }, edge: { size: 11, weight: 400, style: italic } }, spacing: { nodePaddingX: 12, nodePaddingY: 8, siblingGap: 24, layerGap: 48, canvasMargin: 32 }, stroke: { sync: { dash: none, width: 1.5 }, async: { dash: 6 4, width: 1.5 }, data: { dash: none, width: 1.5 }, depends: { dash: 2 3, width: 1 } } }这个文件的好处是任何工具都可以读它。draw.io 可以通过插件读Figma 可以通过 Tokens Studio 读代码生成脚本可以直接读。改一处全局生效。4.2 第二步把令牌映射到绘图工具不同工具的映射方式不一样我分别说一下我实际用过的几种。draw.io / diagrams.net它支持自定义形状库custom shape library。你可以写一个 XML 文件把每个图元的样式固化进去然后作为自定义库加载。这样团队里每个人打开 draw.io 都能看到同一套图元。缺点是 XML 写起来比较繁琐但一次写好可以长期用。Figma用 Tokens Studio 插件导入上面的 JSON然后建一个组件库每个图元做成一个 component颜色和间距都绑定到 token。这样改 token 就能全局更新。Figma 的优势是协作和版本管理比较顺。代码生成Mermaid / Graphviz / PlantUML如果你走“图即代码”的路线可以写一个脚本读 JSON 令牌生成对应的主题文件。比如 Mermaid 支持%%{init: {theme:base, themeVariables: {...}}}%%你可以用脚本把令牌注入进去。提示不要试图同时维护多套工具。选一个主力工具其他工具只做导出。我见过团队里一半人用 draw.io、一半人用 Figma结果就是两套规范逐渐漂移半年后完全对不上。4.3 第三步写一份“图设计检查清单”规范要落地必须有检查手段。我通常写一份检查清单放在 PR 模板里画图的人提交前自己过一遍。[ ] 所有图元是否来自预设词汇表有没有自造图元[ ] 颜色是否只用了语义色有没有为了“好看”加的颜色[ ] 连线类型是否明确有没有“不知道算什么”的连线[ ] 灰度模式下是否仍可区分所有图元[ ] 字号是否统一有没有手动调大的文字[ ] 对齐是否遵循网格有没有肉眼可见的错位[ ] 图是否有标题和一句话说明[ ] 图内文字是否有拼写错误这份清单看起来简单但实测能拦下 70% 以上的低级问题。剩下的 30% 需要人工评审但至少评审时不用再纠结“这个颜色什么意思”了。4.4 第四步版本化与变更管理图设计系统本身也需要版本管理。我的做法是给令牌文件加一个version字段每次破坏性变更就升主版本号并在 CHANGELOG 里写清楚“改了什么、为什么改、影响哪些图”。破坏性变更的例子把“服务”的填充色从浅蓝改成浅绿。这会导致所有旧图和新图不一致。处理方式是要么批量重新导出旧图要么在 CHANGELOG 里注明“旧图沿用 v1 规范新图使用 v2”。非破坏性变更的例子新增一个“缓存”图元。这种变更不影响旧图可以直接升次版本号。注意不要频繁改规范。我见过一个团队两个月改了四次配色结果就是没人再认真遵守了。规范的权威性来自于稳定性。如果确实要改攒一批一起改不要零敲碎打。5. 常见问题与排查技巧实录5.1 图元太多记不住怎么办这是最常见的问题。团队里总有人说“我记不住哪个颜色对应哪个语义”。解决方法不是逼人背而是降低记忆负担把词汇表做成一张“速查卡”贴在绘图工具的模板里打开就能看到在绘图工具里把图元做成带标签的组件鼠标悬停显示语义把常用图元放在工具栏最前面不常用的收起来。实测下来一个人连续画三张图之后基本就能记住核心的 5 到 6 个图元。剩下的靠速查卡就够了。5.2 遇到词汇表覆盖不了的场景怎么办比如你要画一个“定时任务”词汇表里没有。这时候有三个选择用最接近的图元加标记。定时任务可以用“服务”加一个时钟图标。用组合表达。定时任务可以画成“外部触发 服务”。如果这个场景反复出现考虑新增图元但要走变更流程。我的经验是优先用前两种。新增图元的门槛要高否则词汇表会膨胀。判断标准是这个新图元在最近三个项目里出现过至少三次吗如果是才值得加。5.3 灰度测试不通过怎么调灰度测试不通过说明两个图元的明度太接近。调整顺序是先调填充色的明度拉开差距如果填充色调不动调边框色的明度如果还不行改形状或线型。不要靠调色相来解决灰度问题因为色相在灰度下本来就会丢失。形状和线型是更可靠的区分手段。5.4 团队不配合怎么办这是组织问题不是技术问题。我的经验是先做出样板。你自己用这套规范画三张图在评审时展示“这样画读起来快多少”。找一两个愿意配合的同事形成小范围共识。把检查清单放进 PR 模板让规范变成流程的一部分而不是额外的要求。不要一次推全套。先推颜色和字号再推连线类型最后推布局规则。强制推行通常会反弹渐进式渗透更有效。5.5 常见问题速查表问题现象可能原因排查方向解决建议图看起来很乱对齐不一致检查网格和对齐开启对齐辅助线统一间距读图的人问“这个什么意思”语义不明确检查图元和连线是否有歧义补充图例或改用更明确的图元黑白打印后看不清明度太接近做灰度测试拉开明度差增加形状区分图与图之间风格不一致没有统一令牌检查是否都从令牌生成统一工具链禁止手动调样式改一处要改很多图没有用令牌检查是否硬编码样式迁移到令牌驱动的工作流新人上手慢规范太复杂检查词汇表大小精简到 8 个核心图元其余用组合5.6 几个我踩过的坑坑一过早追求完美。我一开始花了大量时间调配色结果发现团队根本不用因为绘图工具里加载自定义库太麻烦。后来先把库做简单能加载就行再慢慢优化。坑二忽略导出场景。图最终要放到文档、PPT、网页里。不同场景对字号和对比度的要求不一样。我后来在令牌里加了一组“导出预设”针对不同场景调整。坑三没有版本化。早期改规范没有记录导致旧图和新图混在一起时完全不知道哪个是哪个版本。后来加了 CHANGELOG 才理清楚。坑四把规范当教条。有一次一个同事画了一个很特殊的图用标准图元表达不了我坚持让他用标准图元结果图变得很难懂。后来我意识到规范是服务于沟通的不是反过来。特殊情况允许破例但要在图里注明。6. 工具选型与自动化扩展6.1 主力工具怎么选工具选型没有绝对答案但有几个维度可以帮你决策维度draw.ioFigma代码生成Mermaid 等上手难度低中高协作能力中高低靠 Git版本管理弱中强自定义能力中高高适合场景快速画图设计协作图即代码我的建议是如果团队以工程师为主走代码生成路线如果以设计和产品为主走 Figma如果是混合团队draw.io 是折中选择。6.2 用脚本做一致性检查如果你走代码生成路线可以写一个简单的检查脚本在 CI 里跑。比如检查所有图源文件里有没有硬编码的颜色值import re import sys from pathlib import Path TOKEN_COLORS {#E8F0FE, #1A73E8, #E6F4EA, #137333, #FEF7E0, #B06000, #F1F3F4, #5F6368} def check_file(path): text Path(path).read_text(encodingutf-8) colors set(re.findall(r#[0-9A-Fa-f]{6}, text)) illegal colors - TOKEN_COLORS if illegal: print(f{path}: 发现非令牌颜色 {illegal}) return False return True if __name__ __main__: ok all(check_file(p) for p in sys.argv[1:]) sys.exit(0 if ok else 1)这个脚本很粗糙但能拦住大部分“随手调色”的情况。跑在 CI 里PR 不通过就不让合并。6.3 自动生成图例图例是图设计系统里最容易被忽略的部分。每张图都应该有图例但手动维护图例很烦。我的做法是写一个脚本从令牌文件自动生成图例的 SVG 或 PNG然后插入到图里。import json def render_legend(tokens, outputlegend.svg): items [] y 0 for name, style in tokens[color].items(): items.append( frect x0 y{y} width24 height16 ffill{style[fill]} stroke{style[stroke]}/ ftext x32 y{y13} font-size12{name}/text ) y 24 svg fsvg xmlnshttp://www.w3.org/2000/svg width200 height{y} \ .join(items) /svg open(output, w).write(svg) if __name__ __main__: tokens json.load(open(design/tokens.json)) render_legend(tokens)这样图例永远和令牌一致不会出现“图例里有的颜色图里没有”这种尴尬。6.4 和文档系统集成图最终要放到文档里。如果你的文档用 Markdown可以把图源文件和文档放在同一个仓库用 CI 自动导出 PNG 并插入。这样改图源就自动更新文档不用手动替换图片。具体做法是在 CI 里加一步# 假设用 draw.io 的 CLI 导出 drawio --export --format png --output docs/images/ diagram/*.drawio然后文档里引用docs/images/xxx.png。每次合并 PR图片自动更新。7. 从单图到体系这套方法还能怎么扩展7.1 扩展到其他图类型diagram-design 最初是为架构图设计的但这套三层框架可以扩展到其他图类型时序图语义层定义参与者、消息、激活块视觉层定义生命线样式、消息箭头工程层用 PlantUML 或 Mermaid 生成。状态机图语义层定义状态、转移、守卫条件视觉层定义圆角矩形、箭头、标签位置。流程图语义层定义开始/结束、处理、判断、输入输出视觉层定义标准形状和连线。每扩展一种图类型就新增一份令牌文件和一份词汇表但三层框架不变。7.2 扩展到非技术场景这套方法不限于技术图。我见过有人用它来规范业务流程图统一泳道、角色、活动、网关的视觉表达组织架构图统一层级、汇报线、虚线的表达用户旅程图统一阶段、触点、情绪曲线的表达。核心逻辑是一样的先定语义再定视觉最后工程化。7.3 和 AI 辅助绘图的结合现在有一些工具可以根据文字描述生成图。但生成出来的图往往不符合你的设计系统。一个可行的做法是把令牌文件和词汇表作为提示词的一部分让生成工具按你的规范输出。比如在提示词里写“使用以下颜色语义计算类用 #E8F0FE 填充、#1A73E8 边框……”。这样生成出来的图至少颜色是对的剩下的布局再手动调。7.4 我个人在实际操作中的体会这套东西我断断续续做了两年多最大的体会是图设计系统的价值不在于图变好看了而在于沟通成本降下来了。以前评审一张架构图前十分钟都在问“这个框什么意思”“这条线什么意思”现在这些基础问题基本消失了评审直接进入“这个设计合不合理”的层面。另一个体会是不要追求一步到位。我一开始想设计一套覆盖所有场景的完美系统结果做了三个月还没落地。后来改成“先解决最痛的三个问题”——颜色混乱、连线歧义、字号不一——两周就上线了然后在用的过程中慢慢补。最后一个建议把规范写进工具里而不是写进文档里。文档没人看工具天天用。你能让工具自动做的事就不要指望人自觉去做。这是我从多次推行失败里学到的最实在的一条。
阅读完成 · 觉得有帮助？
