1. 从一张草图到一套系统diagram-design 到底在解决什么问题第一次听到 “diagram-design” 这个词很多人会下意识觉得它只是“画图”的另一种说法。但真正在项目里被图表折磨过的人知道画图本身从来不是最痛的部分。最痛的是图画完了需求变了图改完了风格不统一风格统一了换个人接手又得从头再来。diagram-design 要处理的正是这一连串“画完之后”的问题。我把它理解成一套面向图表的设计系统而不是一个单纯的绘图工具。它关心的不只是“这条线怎么连”而是“这套图用什么栅格、什么间距、什么颜色语义、什么命名规则才能让十个人画出来的图看起来像一个人画的”。这个定位非常关键因为它决定了你学它的时候重点不在某个软件的按钮在哪而在于一套可复用的规则怎么建立起来。这套东西适合谁如果你只是偶尔画一张流程图发群里那确实用不上这么重的思路。但只要你符合下面任意一条diagram-design 的价值就会立刻显现你需要长期维护一套架构图、流程文档你的团队里有多个人同时产出图表你要把图表嵌进文档、PPT、代码仓库并且保持一致性你希望图表能像代码一样被版本管理、被复用、被审查。这些场景下靠手工拖拽迟早会失控。我见过太多项目前期几张图随手画后期文档里几十张图风格各异箭头粗细不一颜色含义互相打架新人看图像猜谜。diagram-design 的核心主张就是把这些“隐性约定”变成“显性规范”让图表从一次性产物变成可积累的资产。接下来我会从设计思路、核心细节、实操落地、问题排查几个层面把我在实际项目里踩过的路完整讲一遍。2. 整体设计思路拆解为什么图表也需要一套设计系统2.1 图表失控的三个根源在动手搭任何规范之前得先搞清楚图表为什么会乱。我复盘过好几个项目发现失控基本逃不出三个根源。第一个根源是缺乏统一的视觉语言。每个人对“重要”的理解不同有人用红色表示重点有人用红色表示警告还有人用红色只是因为它好看。颜色一旦没有语义绑定读者就得靠猜。第二个根源是缺乏结构约束。节点该多大、间距该多少、连线该走直角还是曲线全靠手感结果就是每张图都“差不多但不一样”拼在一起格外刺眼。第三个根源是缺乏复用机制。同一个服务在十张图里出现十次每次都要重画改一次名字要改十个地方漏一个就产生不一致。这三个根源对应 diagram-design 的三个设计目标语义化、结构化、可复用。理解了这三点后面所有的具体操作都有了判断标准——任何规范只要它让语义更清晰、结构更稳定、复用更容易就值得保留反之就是过度设计。2.2 为什么选择“规范先行”而不是“工具先行”很多人上手第一反应是找工具用什么画其实工具是最不重要的一环。我试过先用工具再补规范结果就是工具里存了一堆风格各异的图回头统一规范时几乎等于重画。后来我改成规范先行先定好颜色、字号、间距、命名再选工具去落地效率完全不一样。规范先行的另一个好处是工具无关。规范是描述性的它规定“主流程用 2px 实线、异常分支用 1.5px 虚线”至于你用哪款软件实现不影响规范本身。这样团队换工具时规范资产不会跟着报废。这也是 diagram-design 思路里我最认可的一点把易变的东西工具和稳定的东西规范解耦。2.3 分层设计把图表拆成四层来管我在实践里把 diagram-design 拆成四层来管理从下往上依次是基础层、语义层、组件层、场景层。基础层管的是最底层的视觉常量比如间距基数、字号阶梯、线宽档位、圆角半径。语义层管的是颜色和形状的含义比如蓝色代表外部系统、绿色代表数据存储、圆角矩形代表服务、圆柱代表数据库。组件层是把常用的图形组合封装成可复用的“积木”比如“一个带数据库的服务节点”。场景层则是针对具体图类型架构图、时序图、状态机的排版规则。分层的意义在于改动的影响范围可控。改基础层的间距基数所有图自动跟着变改语义层的颜色所有用到该语义的图统一更新。如果不分层所有规则混在一起改一处就不知道会波及哪里。这个思路和前端设计系统里的 design token 是一脉相承的只是对象从 UI 换成了图表。3. 核心细节解析与实操要点把规范落到每一个像素3.1 视觉常量怎么定从 8px 栅格说起基础层里最重要的是间距基数。我强烈建议用8px 作为基数所有间距取 8 的倍数8、16、24、32、48。为什么是 8 而不是 10因为 8 能被 2、4 整除缩放时不容易出现半像素模糊而且主流设计工具默认栅格就是 8。字号阶梯我一般定四档标题 20px、节点主文字 14px、注释 12px、极小标注 10px。线宽定三档主流程 2px、次要流程 1.5px、辅助线 1px。这些数字不是拍脑袋来的。字号阶梯的比值大约在 1.4 左右接近黄金比例视觉上层次分明又不突兀。线宽三档之间保持 0.5px 的差距是因为再小就分不出来再大就显得笨重。圆角半径我统一用 4px小到不抢眼又能让节点看起来不那么生硬。注意间距基数一旦定下全项目必须严格执行。我见过有人主流程用 16px 间距注释用 12px结果整张图看起来“哪里不对又说不上来”其实就是栅格被破坏了。3.2 颜色语义绑定让颜色替你说话颜色是图表里信息密度最高的元素也是最容易被滥用的。我的做法是先定义语义再分配颜色而不是反过来。具体来说先列出图里会出现哪些“角色”外部系统、内部服务、数据存储、消息队列、用户、第三方依赖。然后给每个角色分配一个固定色相并规定这个色相只用于这个角色。配色上我推荐用低饱和度的色板。高饱和度的红绿蓝放在一起非常刺眼而且打印出来容易糊成一团。低饱和度色相搭配深色文字可读性最好。每个语义色我还会配一个浅色填充版本用于大面积色块深色版本用于边框和文字这样同一语义在不同场景下都有对应表达。语义角色主色相填充色边框色使用场景外部系统蓝浅蓝深蓝第三方接口、外部依赖内部服务绿浅绿深绿自研服务、核心模块数据存储紫浅紫深紫数据库、缓存、对象存储消息中间件橙浅橙深橙队列、事件总线用户/角色灰浅灰深灰参与者、操作者这张表一旦定下来就贴在团队文档最显眼的位置。新人画图第一件事就是对照这张表选色而不是凭感觉。实测下来光是这一张表就能消掉八成的风格争议。3.3 形状与连线的约定形状承载的是“这是什么类型的东西”。我的约定是圆角矩形代表服务或处理单元直角矩形代表外部系统圆柱代表数据存储菱形代表判断圆形代表起点终点。这套约定和大多数人的直觉一致学习成本低。连线比形状更容易乱。我规定实线代表同步调用虚线代表异步消息带箭头的线代表数据流向不带箭头的线代表关联关系。线的走法上优先走直角折线避免斜线和交叉。如果两条线必须交叉交叉处用“跳线”符号表示不连接。这些细节看起来琐碎但正是它们决定了图是“专业”还是“业余”。实操心得连线交叉是图表可读性的头号杀手。我的经验是如果一张图里交叉超过三处就该考虑拆图了而不是硬画。3.4 命名与标注规范节点里的文字也有讲究。我要求节点名称用名词短语比如“订单服务”“用户数据库”不要用“处理订单”“查询用户”这种动词短语因为动词短语描述的是动作而节点描述的是实体。动作应该体现在连线的标注上。连线标注用动词短语比如“调用”“写入”“订阅”。标注的位置也有规范连线标注放在线的中点偏上字号比节点文字小一档颜色用中性灰。这样标注不会喧宾夺主但需要时又能看清。命名上我还会统一大小写风格要么全用中文要么全用英文绝不中英混排混排是廉价感的主要来源之一。4. 实操过程与核心环节实现从零搭一套可用的图表系统4.1 第一步盘点现有图表提取共性别急着定规范先盘点。把项目里现有的图表全找出来按类型分类架构图、流程图、时序图、状态图、ER 图。然后逐张看记录下它们用了哪些颜色、哪些形状、哪些字号。这一步的目的是找出已经存在的隐性约定而不是凭空发明一套。我做过一次盘点发现团队其实已经在无意中形成了“蓝色表示外部”的默契只是没人写下来。这种情况下把已有的默契显性化比强行推一套新规范阻力小得多。盘点完你会得到一张“现状表”它是你制定规范的起点。4.2 第二步定义 token 并落地成配置文件规范定好后要把它变成可执行的配置。如果你们用代码生成图表比如用文本描述生成图形的方案可以把颜色、间距、字号写成一份配置文件所有图表引用这份配置。这样改一处全局生效。# diagram-tokens.yaml spacing: base: 8 scale: [8, 16, 24, 32, 48] typography: title: 20 node: 14 annotation: 12 micro: 10 stroke: primary: 2 secondary: 1.5 auxiliary: 1 color: external: fill: #E8F0FE border: #1A73E8 service: fill: #E6F4EA border: #137333 storage: fill: #F3E8FD border: #8430CE这份配置就是整个系统的“单一事实来源”。任何人画图前先读这份配置画完后对照检查。如果团队用图形工具而非代码就把这份配置转成工具里的样式库或主题文件效果一样。4.3 第三步封装可复用组件组件层是提效的关键。把高频出现的图形组合封装成“积木”比如“带数据库的服务节点”“带队列的异步处理单元”。封装时要注意组件只封装结构和样式不封装具体文字文字留作参数传入。这样同一个组件能复用到不同场景。我一般会封装这几类组件基础节点服务、存储、外部系统、复合节点服务数据库、连线样式同步、异步、数据流、容器分组框、边界框。封装完之后画一张新图的成本从“从零拖十个图形”降到“拖三个组件改改文字”效率提升非常明显。4.4 第四步建立审查清单规范落地最难的是执行。我的做法是建一份图表审查清单每次提交图表前对照打勾。清单不用长控制在十条以内否则没人看。我的清单是这样的颜色是否符合语义表有没有用语义外的颜色间距是否都是 8 的倍数字号是否只用四档线宽是否只用三档节点命名是否为名词短语连线标注是否为动词短语交叉是否超过三处是否有未对齐的节点中英文是否统一图例是否完整这份清单我用了大半年图表一致性肉眼可见地提升。关键是它把“审美”变成了“检查项”不再依赖个人品味。4.5 第五步版本管理与变更记录图表也要版本管理。我建议图表和代码放同一个仓库用同样的提交规范。每次改图写清楚改了什么、为什么改。这样当有人问“这张图为什么和上个月不一样”时能直接查到变更记录。变更记录还有一个隐性好处它能暴露规范的不足。如果某条规范频繁被绕过说明它可能不合理该调整了。规范不是刻在石头上的它应该随着项目演进而迭代。我一般每季度回顾一次规范把高频例外情况吸收进规范里。5. 常见问题与排查技巧实录5.1 图表风格不统一的排查思路风格不统一是最常见的问题。排查时我按这个顺序看先看颜色是不是有人用了语义外的颜色再看间距是不是有人没按 8px 栅格再看字号是不是有人用了五档六档最后看对齐是不是节点没有对齐到栅格。这四步走下来九成的不统一都能定位到。定位到之后不要直接改图要先问“为什么”。如果是因为规范没写清楚就补规范如果是因为工具不支持就换工具或做模板如果纯粹是疏忽就加强审查。治标更要治本否则同样的问题会反复出现。5.2 图表过大导致可读性下降怎么办图太大、信息太密是另一个高频问题。我的判断标准是如果一张图需要放大到 150% 才能看清文字那它就太大了。解决办法是拆图按层次拆、按模块拆、按流程阶段拆。拆完之后用一张“总览图”串起来总览图只画模块间关系细节放到子图里。拆图时要注意保持命名一致子图里的节点名和总览图里的模块名要能对上否则读者会在图之间迷路。我一般会在总览图的每个模块上标注“详见子图 X”形成导航。5.3 团队协作中的规范冲突多人协作时规范冲突几乎不可避免。有人觉得线该粗一点有人觉得该细一点。我的处理原则是规范内的问题按规范办规范外的问题开讨论。如果规范已经规定了线宽三档那就按规范来个人偏好不构成修改理由。如果规范没覆盖到比如“渐变填充能不能用”那就开个短会定下来然后写进规范。这个原则的关键是把争论从“审美”拉回到“规则”。审美争论没有终点规则争论有明确结论。我见过团队为了一张图的配色吵一下午其实只要问一句“语义表里这个角色是什么颜色”争论立刻结束。5.4 常见问题速查表问题现象可能原因排查动作解决方式整体看起来“哪里不对”栅格被破坏检查间距是否为 8 的倍数对齐到栅格颜色刺眼用了高饱和度色检查是否偏离语义色板换回低饱和语义色读者看不懂重点颜色语义混乱检查同色是否表达多种含义一色一义图太挤信息密度过高放大到 150% 能否看清拆图连线像蜘蛛网交叉过多数交叉点数量超过三处就重排或拆图新人上手慢规范未文档化检查是否有规范文档补文档并配示例改一处要改十处缺乏复用组件检查是否有重复图形封装组件中英混排显廉价命名未统一检查节点文字语言统一为一种语言5.5 几个我踩过的坑第一个坑是规范定得太细。我一开始把圆角半径精确到 3.5px结果没人记得住反而被无视。后来改成 4px 这种整数执行率立刻上去了。规范要的是“好记好用”不是“精确”。第二个坑是只定规范不给模板。规范写在文档里但画图时还得从零开始大家自然懒得遵守。后来我把规范做成模板文件新建图直接套模板遵守规范变成默认行为阻力小了很多。第三个坑是忽视图例。早期我觉得图例多余颜色含义大家都懂。结果新人来了完全看不懂每个颜色都要问。后来每张图都加图例虽然占点空间但省下了大量沟通成本。第四个坑是规范更新不同步。规范改了但旧图没更新导致新旧图风格打架。后来我规定规范变更时必须同步更新所有活跃图表虽然一次性工作量大但避免了长期的不一致。6. 图表系统的扩展方向与个人体会规范跑顺之后可以往几个方向扩展。一个是自动化校验写个脚本扫描图表文件自动检查间距、颜色、字号是否符合规范把人工审查变成机器审查。另一个是从图表反推文档让图表里的节点和连线自动生成文字描述减少文档和图表不同步的问题。还有一个是跨项目复用把成熟的规范沉淀成组织级资产新项目直接继承不用从零开始。我个人在实际操作中的体会是diagram-design 最难的不是定规范而是让规范活下来。规范定完就锁进抽屉等于没定。它需要有人维护、有人审查、有人迭代。我见过太多团队兴冲冲定了一套规范三个月后没人记得。能活下来的规范往往不是最完美的而是最容易被执行的——规则少、模板全、审查轻。最后再分享一个小技巧把规范里最重要的三条做成一张“速查卡”贴在团队文档首页。三条就够比如“颜色按语义表、间距按 8 倍数、命名用名词短语”。人记不住十条但能记住三条。等这三条变成肌肉记忆再慢慢加新的。规范是长出来的不是一次性设计出来的。