1. 从一张草图到一套系统：diagram-design 到底在解决什么问题
第一次听到 “diagram-design” 这个词，很多人会下意识觉得它只是“画图”的另一种说法。但真正在项目里被图表折磨过的人知道，画图本身从来不是最痛的部分——最痛的是图表的可维护性、一致性和协作效率。你辛辛苦苦用某个工具拖拽出一张架构图，两周后系统加了一个模块，你打开源文件发现所有连线都是手动对齐的，挪一个节点整张图就散了；团队里三个人画出来的流程图风格迥异，放到同一份文档里像三个不同公司出的；更别提把图表嵌进代码仓库后，每次改动都要重新导出图片、手动替换、再提交。
diagram-design 要解决的，正是这一整套围绕“图表”的工程化问题。它不是某一个具体软件的名字，而是一类以“设计系统”思维来管理图表的方法论与实践集合：把图表当作代码来对待，把样式当作设计令牌来管理，把布局当作可复用的组件来组织。核心目标只有一个——让图表从“一次性消耗品”变成“可持续演进的资产”。
这套东西适合谁？如果你只是偶尔画一张 PPT 里的示意图，那用现成工具拖一拖就够了，没必要上这套。但如果你符合下面任意一条，diagram-design 的思路就值得你认真研究：你维护的系统架构图超过五张且经常变动；你的团队有多个角色需要共同产出图表；你希望图表能跟着代码一起做版本管理；你厌倦了每次改图都要重新调格式。换句话说，这是给把图表当工程产物而非美术作品的人准备的。
我接触这套思路的契机，是几年前参与一个跨平台系统的文档重构。当时仓库里散落着几十张图，格式从手绘截图到某在线工具导出的 PNG 都有，改一处逻辑要翻遍三个目录找源文件。那次之后我开始系统性地研究“图表即代码”的落地方式，踩了不少坑，也攒了一些真正能复用的经验。下面就把这套东西拆开讲透。
2. 核心思路拆解：为什么图表要当成代码来管
2.1 图表的三层结构：内容、布局、样式必须分离
传统画图工具最大的问题，是把内容、布局、样式三者揉在一个画布里。你拖动一个框，位置信息（布局）和这个框代表什么（内容）以及它长什么样（样式）是混在一起的。这在图少的时候没问题，一旦要批量调整就灾难了。
diagram-design 的第一个核心原则就是三层分离。内容层只描述“有什么”：哪些节点、哪些连线、节点之间的逻辑关系。布局层描述“怎么摆”：是自上而下还是从左到右，是分层还是网状。样式层描述“长什么样”：颜色、字体、线宽、圆角。这三层各自独立，改一层不影响另外两层。
为什么这个分离如此关键？举个实际场景。产品要出一版对外材料，需要把所有图表的配色从“工程蓝”换成“品牌橙”。如果三层混在一起，你得一张张图手动改颜色。但如果样式独立成一层，你只需要改一个样式定义文件，所有引用它的图表自动变色。这就是设计令牌（Design Token）思路在图表上的应用——把颜色、间距、字号这些原子化的设计决策抽出来，集中管理。
我自己的做法是维护一个tokens文件，里面定义好primary-color、node-padding、edge-width这类变量，图表源文件里只引用变量名，不写具体值。换主题时改一处，全局生效。这个习惯帮我省下的时间，保守估计每年几十个小时。
2.2 为什么选“文本描述”而不是“可视化拖拽”
这是最多人纠结的点。可视化拖拽所见即所得，上手快，为什么要退回去写文本？答案在于可维护性和可协作性。
文本描述图表（无论是用某种 DSL 还是结构化数据）有几个拖拽工具给不了的好处。第一是版本对比友好。两个版本的文本 diff 出来，你能清楚看到“加了一个节点、改了一条连线”，而二进制图片文件的 diff 毫无意义。第二是批量操作能力强。要给二十个节点统一加前缀，文本里一个查找替换搞定，拖拽工具里你得点二十次。第三是可编程。你可以写脚本从代码里自动提取模块依赖，生成架构图，人不用手动维护。
当然，文本方式有学习成本，画复杂布局时不如拖拽直观。所以我的建议是混合使用：逻辑结构用文本定义，最终微调可以用工具渲染后再手动调整，但源文件始终以文本为准。这样既保留了工程化的好处，又不至于在细节对齐上死磕。
2.3 渲染管线的设计：从源文件到最终图片
一套完整的 diagram-design 流程，本质是一条渲染管线：源文件 → 解析 → 布局计算 → 样式应用 → 渲染输出。理解这条管线，你才能知道出问题时该在哪一环排查。
源文件通常是某种结构化文本，可能是自定义 DSL，也可能是 YAML/JSON，甚至直接用代码（比如某些库支持用 Python 或 JavaScript 描述图）。解析环节把文本转成内存里的图数据结构。布局计算是最复杂的一环，自动布局算法（如分层布局、力导向布局）在这里决定每个节点的坐标。样式应用把设计令牌套上去。最后渲染成 SVG、PNG 或其他格式。
这条管线里，布局计算是最容易出问题的地方。自动布局算法再聪明，也理解不了“这个节点应该放在那个节点旁边因为业务上它们关系近”这种语义。所以成熟的实践里，通常允许在自动布局基础上做局部手动覆盖——大部分节点自动摆，关键节点手动钉死坐标。这个平衡点需要根据图的复杂度来调。
3. 核心细节解析：把图表工程化落地的关键环节
3.1 节点与连线的数据建模
一切从数据模型开始。一个图表在内存里无非是节点集合加连线集合，但怎么定义这两者，直接决定了后续能力的天花板。
节点至少要包含：唯一标识符、显示文本、类型（用于套用不同样式）、可选的元数据（比如所属模块、负责人）。连线至少要包含：起点节点 ID、终点节点 ID、可选标签、连线类型（实线虚线、箭头方向）。这些字段看起来简单，但每一个都有讲究。
唯一标识符千万别用显示文本代替。我见过太多项目用节点名字当 ID，结果改个名字所有连线全断。ID 应该是稳定的、与显示内容解耦的，比如svc-auth这种语义化短名，或者干脆用 UUID。显示文本可以随时改，ID 不动。
节点类型这个字段是样式复用的关键。你可以定义service、database、queue、external几种类型，每种类型对应一套样式。新增节点时只填类型，样式自动套用。这样整张图的视觉一致性有了保障，不会出现“这个数据库是蓝色那个数据库是绿色”的混乱。
连线的方向性也要在数据层明确。有向图和无向图在布局算法里的处理完全不同。如果业务上连线是有方向的（比如数据流向），一定要在数据里标出来，别指望渲染时靠箭头样式去暗示。
3.2 布局策略的选择与参数调优
布局是图表好不好看的决定性因素，也是最需要经验的部分。常见的布局策略有几种，各有适用场景。
分层布局（Layered/Hierarchical）适合有明确层级关系的图，比如调用链、组织架构、依赖关系。它把节点按层级排布，连线主要在同层或相邻层之间。这种布局的关键参数是层间距和同层节点间距。层间距太小图会挤，太大又显得松散。我的经验值是：层间距设为节点高度的 1.5 到 2 倍，同层间距设为节点宽度的 0.8 到 1.2 倍，具体看节点文字长度。
力导向布局（Force-directed）适合关系复杂、没有明显层级的网络图。它模拟物理系统，节点之间有斥力、连线有引力，最终达到平衡。这种布局好看但不稳定——同样的数据每次渲染可能位置略有不同，这对需要版本对比的场景是灾难。解决办法是固定随机种子，保证可复现。
网格布局（Grid）适合节点大小相近、关系简单的场景，比如功能矩阵。它规整但呆板，适合对整齐度要求高的场合。
实际项目里，我通常先用分层布局打底，因为大部分工程图都有层级。然后对个别不合理的节点做手动位置覆盖。这里有个技巧：不要试图让自动布局一次到位，把它当成初稿生成器，人工微调是正常流程，不是失败。
3.3 样式系统与设计令牌的落地
样式系统的核心是抽象层次。最底层是原子令牌：具体颜色值、字号、间距数值。往上一层是语义令牌：node-background、edge-color、highlight-border，它们引用原子令牌。再往上是组件样式：service-node、database-node，它们组合语义令牌。
为什么要这么多层？因为变化发生的频率不同。原子令牌几乎不变（品牌色定了就定了），语义令牌偶尔变（比如调整对比度），组件样式经常变（比如给数据库节点加个图标）。分层之后，改动的波及范围可控。
落地时，我建议把令牌定义成独立文件，格式用 YAML 或 JSON 都行，关键是图表源文件里绝不出现硬编码的颜色值。这条纪律执行到位，后面换主题、做暗色模式都是顺手的事。
提示：设计令牌的命名要有语义，别用
blue-500这种描述外观的名字，用primary、danger、muted这种描述用途的名字。外观会变，用途相对稳定。
3.4 版本管理与协作流程
图表源文件进了代码仓库，就要遵守代码仓库的规矩。这意味着：每次改动有 commit message，重要变更走 review，冲突要解决。
文本格式的图表在这里优势尽显。两个人同时改一张图，如果改的是不同节点，Git 能自动合并。如果是同一个节点，冲突也能通过文本对比清楚看到。这在二进制图片格式下完全不可能。
协作流程上，我推荐图表源文件与它描述的代码放在同一个仓库。比如某个服务的架构图，就放在这个服务的代码目录下。这样代码改动和图表更新在同一个 PR 里完成，review 的人能同时看到逻辑变化和图表变化，不容易脱节。我见过太多项目图表和代码分仓管理，结果图表永远滞后于代码，最后没人信图。
4. 实操过程：从零搭一套可复用的图表工作流
4.1 环境准备与工具选型
工具选型没有标准答案，取决于你的技术栈和团队习惯。但有几个维度必须考虑：是否支持文本源文件、是否支持设计令牌、是否支持自动布局、输出格式是否满足需求、社区是否活跃。
如果团队以 JavaScript 为主，可以选基于 JS 的图表库，好处是能和前端构建流程打通。如果偏好 Python，也有对应的库，适合和数据脚本结合。如果追求极简，甚至可以用纯文本格式配合命令行工具渲染。
我自己的选型原则是优先选能输出 SVG 的方案。SVG 是矢量格式，放大不糊，能被浏览器直接渲染，还能用 CSS 进一步控制样式。PNG 只在必须嵌入不支持 SVG 的场合才用。
环境准备上，通常需要：运行时环境（Node 或 Python）、图表库、一个渲染命令或脚本、可选的编辑器插件（提供语法高亮和预览）。编辑器插件能大幅提升体验，强烈建议装。
4.2 定义你的第一套设计令牌
动手画第一张图之前，先把令牌定下来。这一步花二十分钟，后面省几十小时。
我通常从这几个类别开始定义。颜色类：主色、辅色、背景色、边框色、文字色、强调色。尺寸类：节点内边距、节点最小宽度、节点圆角、连线宽度、箭头大小。字体类：字号（分标题、正文、注释三档）、字重、行高。间距类：层间距、同层间距、画布边距。
定义时用具体数值，别用“大中小”这种模糊描述。比如node-padding: 12px、layer-gap: 60px。数值怎么定？先凭经验给一版，渲染出来看效果再调。第一版不用追求完美，能跑起来最重要。
# tokens.yaml 示例 color: primary: "#2b6cb0" secondary: "#718096" background: "#ffffff" border: "#cbd5e0" text: "#1a202c" highlight: "#e53e3e" size: node-padding: 12 node-min-width: 120 node-radius: 6 edge-width: 1.5 arrow-size: 8 font: size-title: 16 size-body: 13 size-note: 11 spacing: layer-gap: 60 sibling-gap: 30 canvas-margin: 404.3 描述第一张图：从简单到复杂
第一张图别挑最复杂的画，选一个中等复杂度的，比如一个三层的小系统。先用文本把节点和连线列出来，不关心样式和位置。
# diagram.yaml 示例 nodes: - id: client label: "客户端" type: external - id: gateway label: "网关" type: service - id: auth label: "认证服务" type: service - id: db label: "用户库" type: database edges: - from: client to: gateway label: "请求" - from: gateway to: auth - from: auth to: db label: "读写"写完先渲染一版，看自动布局的效果。大概率不完美，但能看出结构对不对。然后逐步调整：给节点加类型对应的样式，调整布局参数，对关键节点做位置微调。
这个过程要迭代，别指望一次写好。我的习惯是先让结构正确，再让布局合理，最后让样式美观。三个阶段分开做，每次只关注一个维度，效率更高。
4.4 渲染输出与集成到文档
渲染命令通常很简单，一行命令输出 SVG 或 PNG。关键是把它集成到你的构建流程里。如果是文档项目，可以在构建文档时自动渲染所有图表。如果是代码仓库，可以加个脚本，图表源文件变动时自动重新渲染。
集成时有个细节要注意：渲染产物要不要进版本库。我的做法是 SVG 进版本库（因为它是文本，diff 友好），PNG 不进（二进制，且能从 SVG 重新生成）。这样仓库里既有可对比的源文件，又有可直接用的矢量图。
如果图表要嵌入网页，直接用 SVG 内联或引用都行。内联的好处是能用 CSS 控制样式，实现暗色模式自动切换。引用的好处是缓存友好。看具体场景选。
5. 常见问题与排查技巧实录
5.1 布局错乱：节点重叠、连线穿越
这是最高频的问题。节点重叠通常是间距参数太小，或者节点实际尺寸超出了预估。排查时先把所有节点渲染出来量一下实际宽高，再回头调间距参数。连线穿越节点则往往是布局算法没考虑避让，解决办法是换布局策略，或者手动调整关键节点位置。
有个经验：当自动布局怎么调都不满意时，别死磕算法，手动钉几个关键节点坐标。自动布局负责大部分，人工负责关键部分，这个组合最实用。
5.2 样式不生效：令牌引用错误
样式不生效，九成是令牌引用路径写错了，或者令牌文件没被正确加载。排查顺序：先确认令牌文件被读取，再确认引用名拼写正确，最后确认样式应用顺序没有覆盖。我踩过的坑是令牌文件里定义了但图表里引用了另一个名字，渲染时静默失败，图能出来但样式是默认的。所以渲染后一定要肉眼检查样式是否符合预期，别只看图出来了就以为对了。
5.3 版本冲突：多人改同一张图
文本格式虽然 diff 友好，但冲突还是要手动解决。减少冲突的办法是拆分图表粒度：别把所有图塞一个文件，按模块拆开，各人改各自的文件，冲突概率大降。如果确实要改同一张图，约定好谁先提交谁后合并，后合并的人负责解决冲突。
5.4 渲染性能：大图卡顿
节点超过几百个时，渲染可能变慢。优化方向有几个：减少不必要的样式计算、缓存布局结果、按需渲染（只渲染可视区域）。但说实话，如果一张图有几百个节点，图本身可能就该拆了。人脑能理解的图，节点数通常控制在几十个以内。与其优化渲染，不如优化图的粒度。
| 问题现象 | 最可能原因 | 排查动作 | 解决方向 |
|---|---|---|---|
| 节点重叠 | 间距参数过小 | 量实际节点尺寸 | 调大间距或缩小节点 |
| 连线穿越 | 布局算法局限 | 观察穿越位置规律 | 换布局或手动钉坐标 |
| 样式失效 | 令牌引用错误 | 检查令牌加载与拼写 | 修正引用名 |
| 版本冲突 | 多人改同一文件 | 看冲突具体位置 | 拆分文件粒度 |
| 渲染卡顿 | 节点数过多 | 统计节点数量 | 拆分图表 |
注意：排查问题时，永远从最简单的可能性开始。我见过有人花两小时调布局算法，最后发现是令牌文件路径写错导致样式全丢，视觉上看起来像布局问题。先确认基础环节没问题，再往深处查。
6. 进阶玩法：让图表自己“长”出来
6.1 从代码自动生成架构图
图表工程化的终极形态，是图表不再手动维护，而是从代码里自动提取生成。比如从模块的 import 关系生成依赖图，从服务的配置文件生成部署图，从数据库 schema 生成 ER 图。
实现思路是写一个提取脚本，扫描代码或配置，输出成图表源文件格式，再走正常渲染流程。这样代码一变，重新跑脚本，图自动更新。人只需要维护提取逻辑，不用手动改图。
当然这有局限：自动提取的图往往太“全”，缺少人工筛选的重点。所以实践中通常是自动生成打底，人工标注重点。自动部分保证不漏，人工部分保证有重点。
6.2 交互式图表的可能性
SVG 格式的图表可以加交互：鼠标悬停高亮相关节点、点击展开详情、搜索定位节点。这些在静态图片里做不到，但在 SVG 里通过 JavaScript 都能实现。
交互式图表适合放在文档站点或内部工具里。读者不用在一张大图里找半天，输入关键词直接定位。实现成本不高，但体验提升明显。如果你们的图表是给很多人看的，值得投入做一下。
6.3 多主题与暗色模式
有了设计令牌，多主题就是换一套令牌的事。定义light和dark两套令牌，渲染时指定用哪套。暗色模式下注意对比度，别直接把亮色模式的颜色反转，那样往往难看。暗色模式的颜色要单独调，保证文字可读、连线清晰。
我在实际项目里把主题切换做成了构建时参数，同一份图表源文件能输出亮色和暗色两个版本，文档站点根据用户系统设置自动切换。这个体验做出来之后，反馈相当好。
7. 我踩过的坑与几条实在建议
先说几个我真实踩过的坑。第一个是过早追求自动化。刚上手就想从代码自动生成所有图，结果提取逻辑写了一堆，生成的图没法看，最后还是手动画。后来明白，自动化是第二步，第一步是先把手动流程跑顺，知道什么样的图是好图，再去想怎么自动生成。
第二个坑是令牌定义过度。一开始定义了几十个令牌，结果大部分用不上，维护起来还累。后来精简到十几个核心令牌，覆盖八成场景，剩下的特殊情况直接写值。令牌不是越多越好，够用就行。
第三个坑是忽视渲染产物的检查。有次令牌文件改错了，渲染出来的图样式全丢，但因为我只看图“出来了”就提交了，结果文档上线后被人指出配色全乱。从那以后我养成了习惯：每次渲染后必看样式，关键图还要在最终文档环境里预览一遍。
几条实在建议。先把一张图做到极致，把节点、连线、布局、样式、版本管理全流程走一遍，再复制到其他图。建立图表模板，新图从模板开始，省去重复配置。定期回顾图表，过时的图及时删或更新，别让仓库里堆满没人看的僵尸图。文档化你的约定，令牌命名规则、文件组织方式、提交流程，写下来，新人来了能快速上手。
这套 diagram-design 的思路，说到底就是把软件工程里那些成熟的做法——分层、抽象、版本管理、自动化——搬到图表这个 traditionally 靠手工艺的领域。刚开始会觉得麻烦，但一旦跑顺，你会发现图表终于不再是负担，而是真正跟着系统一起演进的资产。这个转变，值得每个被图表折磨过的人花时间走一遍。
