企业官网建设流程全解析

1. 从一张草图到一套系统：diagram-design 到底在解决什么问题

第一次看到 diagram-design 这个词，很多人会以为它只是“画图”的另一种说法。但真正在项目里被图表折磨过的人知道，画图本身从来不是最痛的部分。最痛的是：图画完了，需求变了；图改完了，风格不统一；风格统一了，换个人接手又全部推倒重来。diagram-design 要处理的，正是这一连串连锁反应。

我把它理解成一套“图表设计系统”，而不是一个单纯的绘图工具。它的核心目标是把图表的视觉语言、结构规则、复用组件、输出流程四件事绑在一起，让一张图从“一次性消耗品”变成“可维护资产”。这件事听起来抽象，落到实际场景里非常具体：技术方案评审要架构图，产品迭代要流程图，数据分析要可视化看板，市场汇报要信息图，这些图如果各自为战，团队就会陷入无休止的返工。

diagram-design 适合谁？如果你是一个人做项目的独立开发者，它能帮你把零散的图整理成一套自己的模板库，下次直接改内容不改结构；如果你是团队里的设计或技术负责人，它能帮你建立一套大家都能遵守的图表规范，减少“每个人画出来都不一样”的沟通成本；如果你只是偶尔需要出图，它也能让你用最小的学习成本，产出看起来足够专业的图表。

我见过太多项目在图表上翻车，不是因为不会用工具，而是因为一开始就没有把“设计”当成系统来对待。diagram-design 的价值，就是把这个容易被忽略的环节前置，让图表从“事后补”变成“事前设计”。

2. 核心思路拆解：为什么图表也需要设计系统

2.1 图表失控的三个典型信号

在深入 diagram-design 的具体做法之前，先看看图表失控时会出现什么。我总结下来有三个信号特别明显。

第一个信号是风格漂移。同一个项目里，架构图用的是圆角矩形加阴影，流程图用的是直角矩形加粗边框，数据图又换了一套配色。单看每一张都还行，放在一起就像三个人做的。这种问题在多人协作里几乎必然出现，因为每个人对“好看”的理解不一样，又没有统一约束。

第二个信号是结构重复。每次画新图都要重新摆一遍图例、重新调一遍间距、重新对齐一遍节点。这些动作本身不产生任何业务价值，却消耗了大量时间。更麻烦的是，重复劳动往往伴随不一致，这次图例在左上，下次跑到右下，读者每次都要重新适应。

第三个信号是维护断裂。图发出去之后，需求变了，但原图找不到，或者找到了也不敢改，因为一改就全乱。最后只能重画一张，旧图变成孤儿文件。这个问题在快速迭代的项目里尤其致命。

diagram-design 的思路，就是针对这三个信号分别给出约束：用设计令牌解决风格漂移，用组件复用解决结构重复，用源文件管理解决维护断裂。

2.2 把图表当成代码来管理

diagram-design 最核心的一个理念，是“图表即代码”。这句话不是说要你手写 SVG，而是说图表的定义应该像代码一样具备可版本控制、可复用、可参数化的特性。

传统画图是“所见即所得”，你拖一个框，它就存在那里，改起来靠鼠标。diagram-design 更倾向于“所写即所得”，你用结构化的描述定义节点和连线，渲染引擎负责把它变成图。这样做的好处非常直接：改一个颜色，所有用到这个颜色的图同步更新；改一个节点，所有引用这个节点的图自动同步。

我刚开始接触这个思路时也觉得别扭，觉得不如直接拖拽来得快。但做过几个需要反复迭代的项目之后，我发现真正省时间的地方不在第一次画，而在第十次改。拖拽式工具改十次，每次都要手动调；结构化定义改十次，可能只需要改一行配置。

2.3 设计令牌：让颜色和间距有名字

diagram-design 里有一个很关键的概念叫设计令牌，英文是 design token。简单说，就是把颜色、字号、间距、圆角这些视觉属性抽出来，给它们起名字，而不是每次写具体数值。

比如你不写#2F6FED，而是写color-primary；不写16px，而是写spacing-md。这样做的好处是，当品牌色调整时，你只需要改color-primary的定义，所有引用它的图表自动更新。间距体系同理，如果你觉得整体太挤，把spacing-md从 16 调到 20，所有中等间距的地方一起变。

这个机制在单张图上体现不出优势，但在一个包含几十张图的系统里，它就是救命稻草。我经历过一次品牌升级，主色从蓝变绿，如果没有令牌体系，几十张图要一张张改；有了令牌，改一个变量，半小时内全部同步。

提示：设计令牌的命名要有语义，不要用blue-500这种描述性命名，而要用color-primary、color-danger这种功能性命名。因为颜色可能会变，但功能语义相对稳定。

2.4 组件化：把常用图形封装成积木

除了令牌，diagram-design 还强调组件化。图表里有很多重复出现的元素，比如数据库图标、服务节点、用户角色、决策菱形。这些元素如果每次都从头画，既慢又不一致。

组件化的做法是，把这些元素定义成可复用的组件，每个组件有自己的属性接口。比如一个“服务节点”组件，可以接收名称、状态、版本三个参数，渲染出来就是统一风格的节点。下次要用，直接引用组件，传不同参数就行。

这样做还有一个隐藏好处：当你想调整所有服务节点的样式时，只需要改组件定义，所有实例同步更新。这在维护大型架构图时特别有用，因为架构图里往往有几十个同类节点。

2.5 为什么不用现成的绘图工具

看到这里你可能会问，现成的绘图工具不也有模板和样式吗，为什么还要搞一套 diagram-design。我的体会是，现成工具的模板往往是“死”的，你套用之后还是可以随意改，改着改着就偏离了。而 diagram-design 的约束是“活”的，它通过令牌和组件把一致性固化下来，你想偏离反而要费点劲。

另外，现成工具的输出格式往往是私有的，迁移成本高。diagram-design 更倾向于用开放格式，比如 SVG、JSON、Markdown 这类，方便和其他系统集成。这一点在需要把图表嵌入文档、网页、演示文稿时特别重要。

3. 核心细节解析与实操要点

3.1 建立令牌体系的具体步骤

建立令牌体系是 diagram-design 的第一步，也是最容易被跳过的一步。很多人觉得“我先画图，回头再整理”，结果回头永远不会来。我的建议是一开始就花半小时把令牌定下来，后面会省几十倍的时间。

具体怎么做？先确定你要管理哪些类别的令牌。通常包括颜色、字体、间距、边框、阴影、圆角这几类。颜色里再分主色、辅助色、中性色、语义色（成功、警告、错误）。字体里分字号、字重、行高。间距里分小、中、大、超大几档。

然后给每一类定义具体的值。这里有个经验：不要定义太多档位。颜色主色一到两个就够，间距四到五档就够。档位太多会导致选择困难，反而破坏一致性。我见过一个项目定义了十二档间距，结果大家还是随便选，因为记不住。

定义好之后，把这些令牌写成一个独立的配置文件，比如 JSON 或 YAML。所有图表定义都引用这个文件，而不是写死数值。这样改一处，全局生效。

# tokens.yaml 示例 color: primary: "#2F6FED" secondary: "#6C5CE7" success: "#00B894" warning: "#FDCB6E" danger: "#E17055" text-primary: "#2D3436" text-secondary: "#636E72" background: "#FFFFFF" border: "#DFE6E9" spacing: xs: 4 sm: 8 md: 16 lg: 24 xl: 32 radius: sm: 4 md: 8 lg: 16 font: size-sm: 12 size-md: 14 size-lg: 18 size-xl: 24 weight-normal: 400 weight-bold: 600

这个文件就是整个图表系统的“宪法”，所有视觉决策都以它为准。

3.2 组件定义的粒度怎么把握

组件粒度是另一个容易踩坑的地方。粒度太粗，组件不够灵活，稍微变个需求就要新做一个；粒度太细，组件太多，管理成本高，用起来也麻烦。

我的经验是按“语义”来划分，而不是按“形状”。比如“服务节点”是一个语义组件，它可能渲染成圆角矩形，也可能渲染成六边形，但语义不变。而“圆角矩形”是一个形状组件，它不承载业务含义。diagram-design 更推荐语义组件，因为业务含义相对稳定，形状可以随设计调整。

一个服务节点组件通常包含这些属性：名称、类型、状态、版本、描述。类型决定图标，状态决定颜色，版本和描述决定附加信息。这样定义之后，同一个组件可以覆盖大部分服务节点的展示需求。

组件定义好之后，要写清楚使用说明。包括每个属性的含义、可选值、默认值。这份说明最好和组件定义放在一起，方便查阅。我见过团队把组件和说明分开管理，结果说明很快过时，大家还是靠猜。

3.3 图表结构的组织方式

diagram-design 里，一张图通常由三部分组成：画布配置、节点列表、连线列表。画布配置决定整体尺寸、背景、边距；节点列表定义每个节点的位置、类型、属性；连线列表定义节点之间的连接关系。

这种结构的好处是，节点和连线分离，改连线不影响节点，改节点不影响连线。而且节点可以用相对定位，比如“在节点 A 右侧 100px”，这样当节点 A 移动时，相关节点自动跟随。

组织方式上，我建议按“图层”来分。底层是背景和分组框，中层是节点，上层是连线和标注。这样在调整时可以有选择地显示或隐藏某一层，避免误操作。

另外，节点命名要有规律。不要用node1、node2这种无意义命名，而要用service-user、service-order这种语义命名。这样在连线列表里引用时一目了然，排查问题也方便。

3.4 输出格式的选择与取舍

diagram-design 的输出格式通常有几种选择：SVG、PNG、PDF、以及嵌入网页的 HTML。每种格式有各自的适用场景。

SVG 是首选，因为它是矢量格式，放大不失真，而且可以用代码编辑。嵌入网页时，SVG 还能响应式缩放，适配不同屏幕。缺点是文件可能比较大，复杂图表渲染性能一般。

PNG 适合需要位图的场景，比如插入不支持 SVG 的文档工具。缺点是放大后会模糊，不适合高分辨率输出。如果一定要用 PNG，建议导出两倍或三倍尺寸，保证清晰度。

PDF 适合打印和正式文档，矢量输出，兼容性好。缺点是编辑不如 SVG 方便。

HTML 嵌入适合需要交互的场景，比如点击节点展开详情。缺点是依赖浏览器环境，离线查看不方便。

我的建议是，源文件用结构化格式保存，输出时按需转换。不要只保存输出文件，否则后续修改会很痛苦。

3.5 版本控制与协作规范

图表源文件一定要纳入版本控制。这一点很多人忽略，觉得图不是代码，不需要 Git。但实际上，图表源文件是纯文本，非常适合版本控制。每次修改都有记录，可以对比差异，可以回滚。

协作规范上，建议约定几个规则。第一，谁改谁提交，提交信息写清楚改了什么。第二，重大改动先开分支，评审后再合并。第三，令牌和组件的修改要单独提交，方便追溯。第四，定期检查是否有未使用的令牌和组件，及时清理。

这些规则看起来繁琐，但真正执行起来成本很低，收益却很大。我经历过一次图表源文件丢失，因为没有版本控制，只能凭记忆重画，那种痛苦不想再经历第二次。

4. 实操过程与核心环节实现

4.1 从零搭建一套图表系统的完整流程

假设你现在要从零开始搭建一套 diagram-design 系统，我会按这个顺序推进。

第一步，梳理需求。列出你当前和未来可能需要的图表类型，比如架构图、流程图、时序图、数据看板。不同类型的图表对组件和布局的要求不一样，提前梳理可以避免后期大改。

第二步，定义令牌。按前面说的类别，把颜色、间距、字体、圆角这些定下来。这一步不需要很精确，先有个初版，后面可以迭代。关键是先有，再优化。

第三步，设计基础组件。从最常用的开始，比如矩形节点、圆形节点、菱形决策、箭头连线。每个组件定义好属性接口和默认样式。

第四步，搭建第一张样板图。选一个典型场景，用令牌和组件完整画一张图。这张图的作用是验证整套系统是否好用，哪里别扭就调整哪里。

第五步，沉淀模板。把样板图抽象成模板，保留结构，替换内容。下次遇到类似场景，直接套模板改内容。

第六步，编写使用文档。把令牌含义、组件用法、模板说明写清楚，方便团队其他人上手。

这个流程走下来，大概需要一到两天。看起来投入不小，但后续每张图的产出时间会大幅缩短，而且质量稳定。

4.2 一个架构图的完整实现示例

下面用一个简化架构图为例，展示 diagram-design 的实际写法。假设我们要画一个包含用户、网关、服务、数据库的架构图。

先定义节点：

nodes: - id: user type: actor label: "用户" position: { x: 100, y: 200 } - id: gateway type: service label: "API 网关" status: active position: { x: 300, y: 200 } - id: order-service type: service label: "订单服务" status: active position: { x: 550, y: 120 } - id: user-service type: service label: "用户服务" status: active position: { x: 550, y: 280 } - id: order-db type: database label: "订单库" position: { x: 800, y: 120 } - id: user-db type: database label: "用户库" position: { x: 800, y: 280 }

再定义连线：

edges: - from: user to: gateway label: "HTTPS" - from: gateway to: order-service label: "路由" - from: gateway to: user-service label: "路由" - from: order-service to: order-db label: "读写" - from: user-service to: user-db label: "读写"

渲染引擎读取这份定义，结合令牌和组件，输出一张风格统一的架构图。如果要把主色从蓝改成绿，只需要改tokens.yaml里的color.primary，所有服务节点同步变色。

这个例子里，节点位置是绝对坐标。实际项目中，我更推荐用相对定位或自动布局，这样增删节点时不用手动调位置。自动布局可以用 dagre 这类算法，按连线关系自动排列节点。

4.3 参数计算：间距和对齐的量化方法

图表看起来专不专业，很大程度上取决于间距和对齐。这两件事不能靠感觉，要有量化方法。

间距方面，我通常用 8 的倍数作为基准。为什么是 8？因为 8 在大多数屏幕和分辨率下都能整除，不会出现半像素模糊。具体档位：4 是紧凑，8 是常规，16 是宽松，24 是分组，32 是区块。节点内部 padding 用 8 或 16，节点之间间距用 24 或 32，分组之间用 48 或 64。

对齐方面，同一层级的节点要顶部对齐或中心对齐，不要混用。连线尽量走直线或直角，避免斜线交叉。如果必须交叉，用“跳线”标记，让读者知道这里没有连接。

这些规则写进文档，团队执行时就有据可依。我见过一个项目因为没定间距规则，每张图的疏密程度都不一样，放在一起非常杂乱。

4.4 实操现场：一次图表重构的记录

分享一次我主导的图表重构经历。当时项目里有三十多张图，风格各异，维护困难。我们决定用 diagram-design 的思路统一重构。

第一步是盘点。把所有图列出来，按类型分组，统计每类图的出现频率。发现架构图最多，流程图次之，数据图最少。

第二步是提取共性。把架构图里重复出现的元素找出来，发现服务节点、数据库、网关、用户这四类占了八成。于是优先为这四类做组件。

第三步是定义令牌。参考现有图的配色，提炼出一套主色和辅助色。间距按 8 的倍数重新定档。

第四步是逐张重构。先做一张样板，确认效果后批量推进。重构过程中发现有些图的结构其实可以合并，于是顺手做了精简。

第五步是建立规范。把重构后的组件、令牌、模板整理成文档，纳入新项目流程。

整个过程花了大约一周，但后续新图的产出效率提升了三倍以上，而且风格统一，评审时很少再因为图表问题返工。

5. 常见问题与排查技巧实录

5.1 图表渲染错位的排查思路

渲染错位是常见问题，表现是节点位置和预期不符，或者连线连到了错误的位置。排查时按这个顺序来。

先检查坐标单位。有些渲染引擎用像素，有些用相对单位，混用会导致错位。确认所有坐标单位一致。

再检查层级关系。如果节点有父子关系，父节点移动时子节点是否跟随。有些引擎默认不跟随，需要显式配置。

然后检查连线锚点。连线连接的是节点的中心还是边缘，不同引擎默认值不同。如果锚点不对，连线会看起来歪。

最后检查是否有重叠节点。两个节点坐标太近会重叠，视觉上像错位。用自动布局可以避免这个问题。

注意：排查时先把图简化，只保留出问题的两个节点和一条连线，排除其他干扰。定位到具体问题后再恢复完整图。

5.2 样式不生效的常见原因

样式不生效通常有四个原因。第一，令牌引用写错了，比如color.primary写成了color.main，引擎找不到就回退到默认值。第二，组件属性覆盖了令牌，比如组件里写死了颜色，令牌就管不到。第三，样式优先级问题，后定义的覆盖了先定义的。第四，缓存问题，改了令牌但引擎没重新加载。

排查时先看控制台有没有警告，通常会有“未找到令牌”之类的提示。然后检查组件定义里有没有硬编码样式。最后清缓存重试。

我的经验是，尽量不在组件里写死样式，全部走令牌。这样虽然前期麻烦一点，但后期调整非常省心。

5.3 多人协作时的冲突处理

多人协作时，冲突主要出现在令牌文件和组件文件上。两个人同时改同一个令牌，合并时就会冲突。

处理方法是约定修改流程。令牌和组件的修改要单独提交，提交前先拉取最新版本。如果冲突，不要强行覆盖，而是对比两边的修改意图，合并成一个合理的版本。

另外，建议指定一个“令牌管理员”，负责审核令牌修改。不是限制大家，而是保证令牌体系的稳定性。令牌一乱，所有图都乱。

5.4 常见问题速查表

5.5 几个容易被忽略的避坑技巧

第一个技巧，给令牌和组件加注释。注释写清楚用途和注意事项，别人接手时不用猜。我见过没有注释的令牌文件，半年后连作者自己都不记得某个令牌是干嘛的。

第二个技巧，定期做“死代码清理”。项目推进过程中，总有一些令牌和组件不再使用。定期扫描，把没用的删掉，保持系统精简。否则令牌越来越多，选择困难又回来了。

第三个技巧，保留一个“实验区”。新想法先在实验区试，验证后再合并到主系统。这样既鼓励创新，又不破坏稳定性。

第四个技巧，图表源文件和输出文件分开存放。源文件进版本控制，输出文件按需生成。不要把输出文件也提交，否则仓库会越来越大。

第五个技巧，给重要图表加“变更日志”。在图表定义里加一个字段，记录每次修改的时间和原因。这样追溯问题时非常有用。

6. 图表系统的扩展方向与个人体会

6.1 从静态图到交互式图表

diagram-design 搭好之后，一个自然的扩展方向是交互式图表。静态图只能看，交互图可以点、可以展开、可以筛选。比如点击一个服务节点，展开它的详细信息；或者用一个下拉框切换不同环境，图表跟着变。

实现交互式图表，通常需要把图表定义和渲染逻辑分离，渲染层用前端框架处理交互。数据还是那份结构化定义，只是渲染方式变了。这样做的好处是，同一份定义可以输出静态图，也可以输出交互图，按需选择。

6.2 与文档系统的集成

另一个扩展方向是和文档系统集成。很多项目的文档里需要嵌图，如果图表能自动同步，就不用每次手动更新。

做法是把图表定义放在文档源文件旁边，构建文档时自动渲染。这样改了图表定义，文档里的图也跟着更新。技术方案文档、API 文档、运维手册都适用这个思路。

6.3 自动化检查与质量保障

图表多了之后，质量保障就成了问题。可以写一些自动化检查脚本，比如检查是否有未使用的令牌、是否有节点重叠、是否有连线悬空。这些检查可以集成到构建流程里，每次提交自动跑。

我写过一个简单的检查脚本，扫描所有图表定义，报告潜在问题。虽然不复杂，但帮我们提前发现了很多低级错误，省了不少返工时间。

6.4 我个人在实际操作中的体会

折腾 diagram-design 这套东西几年下来，最大的体会是：约束不是限制，而是效率的来源。刚开始觉得令牌和组件很麻烦，不如直接画来得快。但项目一复杂，直接画的那套就崩了，反而是有约束的系统能持续运转。

另一个体会是，不要追求一步到位。令牌和组件都可以迭代，先有初版，用起来再优化。我见过一些团队想一次性设计完美系统，结果设计了两周还没开始画图，最后不了了之。先跑起来，比什么都重要。

最后分享一个小技巧：每次做完一张图，花两分钟想想有没有可以沉淀成组件或模板的部分。日积月累，你的图表系统会越来越厚，出图速度会越来越快。这个习惯看起来不起眼，但长期收益非常大。