1. 从一张草图到一套系统diagram-design 到底在解决什么问题第一次看到 “diagram-design” 这个标题很多人会以为它只是教你怎么画图——选个模板、拖几个框、连几条线导出 PNG 就完事了。但真正在项目里被图表折磨过的人都知道画图从来不是最难的难的是让图表在三个月后还能被看懂、被修改、被复用。我见过太多团队的项目文档里躺着几十张风格各异的架构图有的用圆角矩形有的用直角有的箭头是实心三角有的是开口线颜色更是五花八门。等到要做对外汇报时光是统一视觉就得花掉一整天。diagram-design 要解决的就是这个问题。它不是一个具体的绘图工具而是一套图表设计的方法论加可落地的规范体系。核心思路是把图表当作代码来管理定义好一套设计令牌颜色、字体、间距、线宽、圆角然后用这套令牌去约束每一张图的生成过程。最终产出的图表不管是谁画的、什么时候画的放在一起都像同一个人做的。这套东西适合谁如果你是技术团队的架构师、技术文档工程师、产品经理或者任何需要频繁输出架构图、流程图、时序图、状态机图的人diagram-design 能帮你省下大量重复调整格式的时间。如果你只是偶尔画一张示意图发在聊天窗口里那可能用不上这么重的方案。但只要你的图表数量超过十张或者需要多人协作维护这套方法的价值就会立刻显现出来。我最初接触这个方向是因为一个跨平台系统的文档项目。当时团队里三个人各自用不同的工具画图合并文档时发现光是箭头样式就有五种客户看了直接问“你们是不是三个公司拼起来的”。从那以后我开始系统性地研究图表设计的规范化问题diagram-design 就是在这个过程中沉淀下来的实践总结。2. 核心设计思路拆解为什么是“令牌驱动”而不是“模板驱动”2.1 模板驱动的三个致命伤大多数人刚开始规范图表时第一反应是做模板。比如在绘图工具里存一个“标准架构图模板”下次直接复制修改。这个方法在初期看起来有效但很快就会暴露问题。第一个问题是模板会漂移。你存了模板但每次用的时候总会有人微调一下——这个框拉宽一点那个颜色换成品牌色箭头改成虚线表示异步。改完之后如果忘了存回模板下次又从头开始。三个月后你打开模板库会发现里面有十几个“标准模板”每个都略有不同根本分不清哪个才是最新的。第二个问题是模板无法跨工具。你用某款在线工具做的模板换到另一款工具里就打不开。团队里有人习惯用桌面端有人习惯用网页端有人直接写代码生成图表模板根本覆盖不了所有场景。第三个问题是模板不携带语义。一个矩形框在模板里只是一个矩形框它不知道自己是“服务”还是“数据库”还是“外部系统”。当你想批量修改所有“数据库”节点的颜色时只能一个个手动选因为模板没有告诉工具这个框代表什么。2.2 令牌驱动的核心逻辑diagram-design 的做法是把图表的视觉属性抽象成一套设计令牌类似前端开发里的 design tokens。这套令牌定义了颜色令牌主色、辅助色、强调色、背景色、边框色、文字色每种颜色都有明确的语义标签比如color-service、color-database、color-external。形状令牌圆角半径、边框宽度、阴影参数、填充样式区分“服务节点”“数据节点”“外部节点”等。连线令牌线宽、线型实线/虚线、箭头样式、颜色区分“同步调用”“异步消息”“数据流”等。排版令牌字体族、字号层级、字重、行高确保所有图表里的文字风格一致。间距令牌节点内边距、节点间距、画布边距用一套栅格系统来约束布局。这些令牌不依赖于任何具体工具。你可以把它们写进绘图工具的样式面板也可以写进代码生成图表的配置里甚至可以做成一套 CSS 变量用在网页版图表中。关键是令牌是唯一真相来源任何图表都必须从令牌取值不允许硬编码颜色或尺寸。2.3 为什么这套逻辑更抗漂移令牌驱动最大的好处是修改成本极低且全局一致。假设品牌色从蓝色换成了绿色你只需要改一个令牌值所有引用这个令牌的图表全部自动更新。这在模板驱动下是不可想象的——你得打开每一张图找到每一个用了旧颜色的元素一个个改。另一个好处是语义清晰。当一张图里出现一个红色节点时你知道它代表“外部系统”或“告警状态”因为令牌定义里写清楚了。新人接手时看一眼令牌表就能理解整张图的视觉语言不需要口头解释。还有一个容易被忽略的好处是可编程性。令牌本质上是结构化数据可以被脚本读取和处理。你可以写一个校验脚本自动检查所有图表是否使用了未定义的令牌值或者检查对比度是否满足可访问性要求。这种自动化能力在图表数量多了之后非常关键。3. 令牌体系的具体设计与参数计算3.1 颜色令牌的语义分层颜色令牌不能随便定必须按照语义分层。我通常分成四层第一层是基础色板就是一组原始颜色值比如blue-500、gray-100、red-600。这一层不直接用在图表里只是作为调色原料。第二层是语义色把基础色映射到具体用途比如color-primary指向blue-500color-danger指向red-600。这一层开始有业务含义了。第三层是图表角色色把语义色进一步映射到图表中的具体角色比如color-service-fill指向color-primary的浅色变体color-service-border指向color-primary的深色变体。第四层是状态色用于表示节点的运行状态比如color-status-ok、color-status-warning、color-status-error。这样分层的好处是当你要调整整体色调时只需要改第二层的映射关系第三层和第四层自动跟着变。比如把color-primary从蓝色改成紫色所有服务节点的填充和边框都会同步更新。关于对比度我建议所有文字色和背景色的对比度至少达到 4.5:1这是可访问性的一般要求。计算方法是把两个颜色的相对亮度代入公式具体来说相对亮度 L 的计算是把每个通道值除以 255如果大于 0.03928 就做幂运算((value0.055)/1.055)^2.4否则除以 12.92然后按 R×0.2126 G×0.7152 B×0.0722 加权求和。对比度就是(L10.05)/(L20.05)。这个计算看起来麻烦但很多工具可以自动检查你只需要在定义令牌时跑一遍就行。3.2 形状令牌的尺寸推导形状令牌的核心是圆角半径和边框宽度。圆角半径不能拍脑袋定要和节点尺寸成比例。我的经验是小节点宽度小于 120px用 4px 圆角中节点120-240px用 6px大节点大于 240px用 8px。这样视觉上圆角不会显得过大或过小。边框宽度通常用 1px 或 2px。1px 适合信息密度高的图2px 适合需要强调的节点。但要注意如果图表会被缩放显示1px 边框在高分屏上可能显示为 0.5px 导致模糊所以建议用 1.5px 或 2px 作为默认值。阴影参数我一般用0 2px 4px rgba(0,0,0,0.1)这个强度足够区分层次但不会太抢眼。如果图表要打印阴影可能显示不出来所以不能只靠阴影来区分节点类型必须同时用颜色或形状差异。3.3 连线令牌的语义映射连线是图表里最容易被忽视的部分但恰恰是信息量最大的部分。我通常定义以下几种连线类型连线类型线型箭头颜色语义同步调用实线实心三角主色深色请求-响应模式异步消息虚线开口箭头辅助色消息队列、事件数据流实线实心三角数据色数据流向依赖关系点线无箭头灰色编译期依赖回退路径虚线实心三角警告色异常处理这套映射一旦定下来所有人画图时都必须遵守。新人入职时第一件事就是看这张表而不是自己发明新的连线样式。3.4 排版令牌的层级控制排版令牌要控制三个维度字号、字重、行高。我建议图表内文字不超过三个层级节点标题14px字重 600行高 1.4节点描述12px字重 400行高 1.5标注文字10px字重 400行高 1.3字号不要用奇数因为很多渲染引擎对奇数字号的处理不一致可能导致文字模糊。行高用倍数而不是固定值这样换字体时不会出问题。字体族要选系统默认的无衬线字体比如-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif。不要用需要额外安装的字体否则在别人电脑上打开时可能回退到衬线字体整个图表的观感就崩了。4. 实操过程从零搭建一套 diagram-design 体系4.1 第一步盘点现有图表提取共性在定义令牌之前先把你手头所有图表过一遍。不用细看内容只看视觉属性用了哪些颜色、哪些形状、哪些线型、哪些字号。我通常用表格来记录图表名称主色节点形状连线样式字号系统架构图#3B82F6圆角矩形实线实心箭头14/12部署流程图#2563EB直角矩形虚线开口箭头16/12数据流图#1D4ED8圆形实线无箭头12/10盘点完之后你会发现很多重复和冲突。比如三种蓝色其实可以统一成一个主色两种矩形可以统一成一种圆角规格。这个过程就是收敛把发散的选择收敛成一套有限的令牌。4.2 第二步定义令牌表并写入配置文件令牌表可以用 YAML 或 JSON 来写方便被脚本读取。下面是一个简化版的示例tokens: color: primary: base: #3B82F6 light: #DBEAFE dark: #1E40AF secondary: base: #8B5CF6 light: #EDE9FE dark: #5B21B6 neutral: base: #6B7280 light: #F3F4F6 dark: #374151 status: ok: #10B981 warning: #F59E0B error: #EF4444 shape: radius: small: 4 medium: 6 large: 8 border: thin: 1 thick: 2 shadow: 0 2px 4px rgba(0,0,0,0.1) line: sync: style: solid arrow: filled color: {color.primary.dark} async: style: dashed arrow: open color: {color.secondary.base} data: style: solid arrow: filled color: {color.neutral.dark} typography: title: size: 14 weight: 600 lineHeight: 1.4 body: size: 12 weight: 400 lineHeight: 1.5 caption: size: 10 weight: 400 lineHeight: 1.3这个文件就是你的唯一真相来源。所有图表生成脚本、绘图工具样式面板、文档模板都从这里取值。4.3 第三步把令牌注入绘图工具如果你用的是支持样式变量的绘图工具直接把令牌值填进去就行。如果工具不支持变量那就手动创建对应的样式预设。比如在 draw.io 里你可以创建一个自定义样式库把每种节点类型和连线类型都存成预设命名和令牌表保持一致。这里有个小技巧在工具里创建样式时把令牌名称写在样式描述里。比如创建一个“服务节点”样式描述写color-service-fill: primary.light; border: primary.dark; radius: medium。这样别人用这个样式时能直接看到它对应哪些令牌方便排查问题。4.4 第四步用代码生成图表时的令牌注入如果你用代码生成图表比如用 Mermaid、PlantUML 或 D3.js令牌注入就更直接了。以 Mermaid 为例你可以用%%{init}%%指令来设置主题变量%%{init: { theme: base, themeVariables: { primaryColor: #DBEAFE, primaryBorderColor: #1E40AF, primaryTextColor: #1E40AF, lineColor: #374151, secondaryColor: #EDE9FE, tertiaryColor: #F3F4F6 } }}%% graph TD A[服务A] -- B[服务B] B -- C[(数据库)]但 Mermaid 的主题变量有限不能完全覆盖所有令牌。更彻底的做法是写一个预处理脚本读取 YAML 令牌表生成 Mermaid 的初始化指令或者直接生成 SVG。这样令牌表一改所有图表重新生成一遍就全部更新了。4.5 第五步建立校验机制令牌体系建好之后最大的风险是有人不遵守。所以需要一套校验机制。我通常写一个简单的脚本做三件事第一扫描所有图表源文件检查是否出现了未在令牌表中定义的颜色值。如果发现硬编码的#FF0000这种就报错。第二检查所有文字和背景的对比度是否达标。这个可以用前面提到的相对亮度公式来计算。第三检查节点命名是否规范。比如所有服务节点是否都以“服务”结尾所有数据库节点是否都以“库”结尾。这个不是视觉问题但影响图表的一致性。校验脚本可以集成到 CI 流程里每次提交图表变更时自动跑一遍。这样问题在合并前就能发现不会等到文档发布后才被客户指出来。5. 常见问题与排查技巧实录5.1 令牌值改了但图表没更新这是最常见的问题。原因通常有三种一是图表里硬编码了旧值没有引用令牌二是缓存没清工具还在用旧的样式三是令牌表有多个副本你改了一个但工具读的是另一个。排查顺序先检查图表源文件里有没有硬编码的颜色值用搜索功能找#开头的十六进制码。如果有改成令牌引用。然后检查工具的缓存设置强制刷新一次。最后确认令牌表的位置确保所有工具都指向同一个文件。注意如果你用的是在线绘图工具有些工具会把样式存在云端本地改令牌表不会影响云端已保存的图表。这种情况下需要手动重新应用样式或者导出再导入一次。5.2 不同工具渲染出来的效果不一致这个问题很头疼但原因通常出在字体和阴影上。不同操作系统对字体的渲染有差异Windows 和 macOS 上同一个字号看起来可能差 1-2px。阴影的模糊半径在不同渲染引擎里也有偏差。我的应对策略是放弃对像素级一致的追求转而追求语义一致。只要颜色、形状、线型的语义是对的细微的渲染差异可以接受。如果确实需要完全一致那就统一用同一种工具或者统一导出成 SVG 再嵌入文档。SVG 是矢量格式在不同设备上缩放不会失真比 PNG 靠谱得多。5.3 节点太多导致图表拥挤当一张图里的节点超过 15 个时视觉上就会开始拥挤。这时候不要硬塞而是考虑分层。把一张大图拆成几张子图每张图聚焦一个层次。比如一张系统架构图可以拆成“接入层”“服务层”“数据层”三张图每张图里的节点控制在 10 个以内。如果确实需要在一张图里展示所有节点那就用分组框来组织。把相关节点放进一个带标题的矩形框里框的边框用浅灰色填充透明。这样视觉上有了层次但所有信息还在同一张图里。5.4 连线交叉太多看不清连线交叉是图表可读性的头号杀手。减少交叉的方法有几个一是调整节点位置把关联紧密的节点放在一起二是用正交连线而不是直线正交连线会沿着水平或垂直方向走交叉时更容易追踪三是用连线跳线在交叉处画一个小弧线表示“跳过”这样能看清哪条线连到哪里。如果交叉实在太多那就说明这张图的信息密度过高应该拆图。不要试图用一张图解决所有问题读者的注意力是有限的。5.5 令牌表越来越臃肿令牌表刚开始很精简但随着项目推进总会有人想加新令牌。加着加着就失控了最后变成几百个令牌没人记得住哪个是哪个。控制令牌数量的方法是定期审计。每个季度过一遍令牌表看看哪些令牌从来没被用过哪些令牌的用途重叠了。没用的删掉重叠的合并。我一般把令牌总数控制在 50 个以内超过这个数就说明抽象层次出了问题需要重新设计。5.6 常见问题速查表问题现象可能原因排查方法解决方案图表颜色不一致硬编码旧值搜索十六进制码改为令牌引用文字模糊奇数字号检查字号设置改用偶数字号连线看不清线宽太细检查线宽令牌改用 2px 线宽节点拥挤信息密度过高统计节点数量拆图或分组导出后失真用了位图格式检查导出格式改用 SVG令牌不生效缓存未清强制刷新清除工具缓存对比度不足颜色搭配不当计算对比度调整颜色值6. 工具选型与协作流程的配合6.1 绘图工具的选型考量选工具不能只看功能还要看它是否支持令牌体系。我评估过几类工具在线拖拽式工具如 draw.io、Excalidraw上手快但令牌支持弱。draw.io 有样式面板可以存预设但没法做全局变量。Excalidraw 的手绘风格不适合正式文档。代码生成式工具如 Mermaid、PlantUML、Graphviz令牌支持好因为配置本身就是代码。缺点是布局控制弱复杂图表的自动布局经常不理想。专业绘图工具如 Figma、Sketch令牌支持最好有完整的 design tokens 功能。但学习成本高而且不是专门为技术图表设计的画架构图时效率不如专用工具。我的建议是混合使用日常快速画图用 Mermaid需要精细控制时用 Figma最终导出统一用 SVG。令牌表独立于工具存在每个工具都从令牌表取值。6.2 多人协作时的令牌管理多人协作时令牌表必须放在版本控制里和代码一起管理。每次修改令牌都要走合并请求有人审核。审核的重点是新令牌是否必要命名是否规范是否和现有令牌重叠。图表源文件也要进版本控制。这样每次变更都有记录出问题了可以回滚。我见过团队把图表放在共享网盘里结果两个人同时编辑同一张图保存时互相覆盖最后谁也不知道哪个版本是对的。6.3 令牌变更的影响评估改令牌不是小事可能影响几十张图。所以在改之前要做影响评估。具体做法是在令牌表里搜索这个令牌被哪些图表引用列出受影响的范围。如果影响面太大就考虑加一个新令牌而不是改旧的然后逐步迁移。迁移的时候不要一次性全改而是分批改。先改新图表再改旧图表。每改一批就检查一次确保没有视觉回归。7. 从图表设计延伸到文档系统的一致性diagram-design 的价值不止于图表本身。当你的图表有了统一的视觉语言后它会倒逼整个文档系统的一致性。因为图表和正文放在一起时如果图表很规范但正文排版混乱对比会非常刺眼。我后来把令牌体系扩展到了文档排版上正文的字体、字号、行高、段落间距、标题层级全部用同一套令牌来定义。这样图表和正文的视觉风格是统一的整份文档看起来像一个整体而不是拼凑出来的。具体做法是写一个文档生成脚本读取令牌表生成 CSS 变量然后应用到 Markdown 渲染或 PDF 导出流程里。这样令牌表一改图表和正文同步更新不需要分别调整。这个扩展带来的最大好处是维护成本骤降。以前改一次品牌色要改图表、改正文、改页眉页脚至少花半天。现在改一个令牌值重新生成一遍五分钟搞定。8. 我踩过的坑和最后分享的几个技巧第一个坑是令牌命名太抽象。我一开始用color-1、color-2这种命名结果过了两周自己都忘了哪个是哪个。后来改成color-service-fill这种语义化命名虽然名字长了点但一眼就能看懂用途。命名这件事宁可长而清楚不要短而模糊。第二个坑是过早追求完美。我一开始想定义一套覆盖所有场景的令牌结果定义了 200 多个实际用到的不到 30 个。后来学乖了先定义最常用的 20 个用起来之后再按需增加。令牌体系是长出来的不是设计出来的。第三个坑是忽略了导出环节。令牌在绘图工具里显示正常但导出成 PNG 后颜色变了。原因是导出时用了不同的色彩配置文件。后来统一用 SVG 导出这个问题就消失了。如果你的文档必须用 PNG那就在导出设置里关掉色彩管理用 sRGB 直接输出。最后分享一个小技巧在令牌表里加一个deprecated字段标记哪些令牌已经废弃但还没删。这样迁移期间新旧令牌可以共存不会因为删得太快导致旧图表报错。等所有图表都迁移完了再把废弃令牌清理掉。这个字段看起来不起眼但在大规模迁移时能省很多事。还有一个技巧是给令牌表写变更日志。每次改令牌都记一笔什么时候改的、改了什么、为什么改、影响了哪些图表。这样半年后回头看能快速理解当时的决策背景不会因为换了个人维护就断档。变更日志不用很正式一个 Markdown 文件按时间倒序记录就行。