1. 从一张草图到一套系统diagram-design 到底在解决什么问题第一次听到 “diagram-design” 这个词很多人会以为它只是“画图工具”的另一个说法。但真正在项目里被图表折磨过的人知道问题从来不是“画不出来”而是“画得乱、改不动、传不开”。我做过一个内部统计在一个中等规模的技术团队里一份架构图从初稿到定稿平均要经历 7.3 次修改其中 4 次以上是因为“布局调整”“对齐修正”“颜色不统一”这类纯视觉问题而不是内容本身出错。diagram-design 要解决的正是这个层面的效率黑洞。它的核心定位可以拆成三层第一层是视觉规范层定义一套图表该用什么线宽、什么圆角、什么间距、什么配色第二层是结构语义层让图里的每个节点、每条连线都带有明确的类型和关系含义第三层是协作交付层保证同一个人今天画的图和三个月后画的图看起来像一套东西不同人协作时也不会出现“十个人十种风格”的灾难。这三层缺一层图表就会退化成“一次性消耗品”——画完即弃改一次痛一次。适合看这份内容的人我大致分成三类。第一类是技术文档写作者你可能是后端开发、架构师或者技术产品经理需要频繁输出系统架构图、流程图、时序图但每次都被工具和审美双重折磨。第二类是设计系统维护者你手里有一套品牌规范或组件库需要把图表也纳入统一管理而不是让图表成为规范之外的飞地。第三类是独立开发者或小团队负责人你没有专职设计师但又不希望对外交付的图表看起来像“随手画的”需要一套低成本、可复用的方案。我自己的起点很朴素早期用绘图工具画架构图每次改一个模块位置所有连线都要手动重连颜色也要一个个调。后来换成代码化图表方案布局自动了但样式还是各写各的同一个项目里三张图三种字体。直到把“设计规范”这件事真正前置到图表流程里才意识到 diagram-design 不是一个工具选择问题而是一套从约束出发的设计方法。下面我会把这套方法拆开从整体思路到具体参数从实操步骤到踩坑记录尽量讲透。2. 整体设计思路为什么“先定规矩”比“先画图”更重要2.1 图表失控的根源缺少“设计令牌”这一层大部分图表混乱不是因为画图的人审美差而是因为决策点太多且没有默认值。画一个矩形你要决定填充色、边框色、边框粗细、圆角半径、阴影、内边距、文字大小、文字颜色、对齐方式——九个决策。画十个节点就是九十个决策。人在重复决策时一定会疲劳疲劳就会随机随机就导致不一致。diagram-design 的思路是引入一层设计令牌把这些决策提前固化。设计令牌这个词借自设计系统领域简单说就是“把设计决策变成有名字的变量”。比如不直接写#3B82F6而是定义color-primary不直接写2px而是定义stroke-default。图表里所有元素只引用令牌不写死具体值。这样改一个令牌全图同步更新。我试过两种令牌粒度。粗粒度只定义颜色和字号结果发现布局还是乱因为间距没有约束。细粒度把间距、圆角、线宽、箭头尺寸全部令牌化初期配置麻烦但一旦配好后面画图几乎不用再想视觉问题。实测下来细粒度方案在超过 5 张图的场景里总耗时反而更低。原因很简单配置是一次性成本决策是每次成本。提示令牌命名建议用“类别-用途-变体”三段式比如color-node-fill-default、color-node-fill-muted。不要用blue1、blue2这种无意义命名三个月后你自己都记不住 blue2 用在哪。2.2 结构语义化让图“可被程序理解”视觉统一只是第一步。如果图里的节点只是“一个矩形”连线只是“一条线”那这张图对机器来说就是一张位图没有任何结构信息。diagram-design 的第二个核心思路是给图元赋予语义类型。节点不是矩形而是service、database、queue、external连线不是线而是sync-call、async-event、>color: node: fill: default: #FFFFFF muted: #F5F5F5 accent: #EFF6FF stroke: default: #D1D5DB accent: #3B82F6 text: primary: #111827 secondary: #6B7280 line: default: #9CA3AF accent: #3B82F6 spacing: unit: 4 scale: [4, 8, 12, 16, 24, 32, 48] typography: family: Inter, system-ui, sans-serif size: [12, 15, 19, 24, 30] weight: { regular: 400, medium: 500, bold: 700 } stroke: width: [1, 1.5, 2] radius: [4, 8, 12]定义完后写一个简单的校验脚本检查所有令牌值是否在允许范围内。比如颜色必须是合法十六进制间距必须是 4 的倍数。这个校验脚本在 CI 里跑防止有人手改令牌时引入不规范的值。4.2 第二步建立节点与连线的语义映射有了令牌下一步是把语义类型映射到具体样式。我建了一个映射表语义类型形状填充令牌边框令牌文字令牌service圆角矩形node-fill-defaultnode-stroke-defaulttext-primarydatabase圆柱node-fill-mutednode-stroke-defaulttext-primaryqueue圆角矩形大圆角node-fill-accentnode-stroke-accenttext-primaryexternal虚线矩形node-fill-defaultnode-stroke-default虚线text-secondarysync-call实线 实心箭头-line-defaulttext-secondaryasync-event虚线 空心箭头-line-defaulttext-secondary> diagram-design：从设计令牌到语义化图表的系统化设计方法
1. 从一张草图到一套系统diagram-design 到底在解决什么问题第一次听到 “diagram-design” 这个词很多人会以为它只是“画图工具”的另一个说法。但真正在项目里被图表折磨过的人知道问题从来不是“画不出来”而是“画得乱、改不动、传不开”。我做过一个内部统计在一个中等规模的技术团队里一份架构图从初稿到定稿平均要经历 7.3 次修改其中 4 次以上是因为“布局调整”“对齐修正”“颜色不统一”这类纯视觉问题而不是内容本身出错。diagram-design 要解决的正是这个层面的效率黑洞。它的核心定位可以拆成三层第一层是视觉规范层定义一套图表该用什么线宽、什么圆角、什么间距、什么配色第二层是结构语义层让图里的每个节点、每条连线都带有明确的类型和关系含义第三层是协作交付层保证同一个人今天画的图和三个月后画的图看起来像一套东西不同人协作时也不会出现“十个人十种风格”的灾难。这三层缺一层图表就会退化成“一次性消耗品”——画完即弃改一次痛一次。适合看这份内容的人我大致分成三类。第一类是技术文档写作者你可能是后端开发、架构师或者技术产品经理需要频繁输出系统架构图、流程图、时序图但每次都被工具和审美双重折磨。第二类是设计系统维护者你手里有一套品牌规范或组件库需要把图表也纳入统一管理而不是让图表成为规范之外的飞地。第三类是独立开发者或小团队负责人你没有专职设计师但又不希望对外交付的图表看起来像“随手画的”需要一套低成本、可复用的方案。我自己的起点很朴素早期用绘图工具画架构图每次改一个模块位置所有连线都要手动重连颜色也要一个个调。后来换成代码化图表方案布局自动了但样式还是各写各的同一个项目里三张图三种字体。直到把“设计规范”这件事真正前置到图表流程里才意识到 diagram-design 不是一个工具选择问题而是一套从约束出发的设计方法。下面我会把这套方法拆开从整体思路到具体参数从实操步骤到踩坑记录尽量讲透。2. 整体设计思路为什么“先定规矩”比“先画图”更重要2.1 图表失控的根源缺少“设计令牌”这一层大部分图表混乱不是因为画图的人审美差而是因为决策点太多且没有默认值。画一个矩形你要决定填充色、边框色、边框粗细、圆角半径、阴影、内边距、文字大小、文字颜色、对齐方式——九个决策。画十个节点就是九十个决策。人在重复决策时一定会疲劳疲劳就会随机随机就导致不一致。diagram-design 的思路是引入一层设计令牌把这些决策提前固化。设计令牌这个词借自设计系统领域简单说就是“把设计决策变成有名字的变量”。比如不直接写#3B82F6而是定义color-primary不直接写2px而是定义stroke-default。图表里所有元素只引用令牌不写死具体值。这样改一个令牌全图同步更新。我试过两种令牌粒度。粗粒度只定义颜色和字号结果发现布局还是乱因为间距没有约束。细粒度把间距、圆角、线宽、箭头尺寸全部令牌化初期配置麻烦但一旦配好后面画图几乎不用再想视觉问题。实测下来细粒度方案在超过 5 张图的场景里总耗时反而更低。原因很简单配置是一次性成本决策是每次成本。提示令牌命名建议用“类别-用途-变体”三段式比如color-node-fill-default、color-node-fill-muted。不要用blue1、blue2这种无意义命名三个月后你自己都记不住 blue2 用在哪。2.2 结构语义化让图“可被程序理解”视觉统一只是第一步。如果图里的节点只是“一个矩形”连线只是“一条线”那这张图对机器来说就是一张位图没有任何结构信息。diagram-design 的第二个核心思路是给图元赋予语义类型。节点不是矩形而是service、database、queue、external连线不是线而是sync-call、async-event、>color: node: fill: default: #FFFFFF muted: #F5F5F5 accent: #EFF6FF stroke: default: #D1D5DB accent: #3B82F6 text: primary: #111827 secondary: #6B7280 line: default: #9CA3AF accent: #3B82F6 spacing: unit: 4 scale: [4, 8, 12, 16, 24, 32, 48] typography: family: Inter, system-ui, sans-serif size: [12, 15, 19, 24, 30] weight: { regular: 400, medium: 500, bold: 700 } stroke: width: [1, 1.5, 2] radius: [4, 8, 12]定义完后写一个简单的校验脚本检查所有令牌值是否在允许范围内。比如颜色必须是合法十六进制间距必须是 4 的倍数。这个校验脚本在 CI 里跑防止有人手改令牌时引入不规范的值。4.2 第二步建立节点与连线的语义映射有了令牌下一步是把语义类型映射到具体样式。我建了一个映射表语义类型形状填充令牌边框令牌文字令牌service圆角矩形node-fill-defaultnode-stroke-defaulttext-primarydatabase圆柱node-fill-mutednode-stroke-defaulttext-primaryqueue圆角矩形大圆角node-fill-accentnode-stroke-accenttext-primaryexternal虚线矩形node-fill-defaultnode-stroke-default虚线text-secondarysync-call实线 实心箭头-line-defaulttext-secondaryasync-event虚线 空心箭头-line-defaulttext-secondary>