企业官网建设流程全解析

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

第一次听到 diagram-design 这个词，很多人会下意识觉得它只是“画图”的另一种说法。但真正在项目里被图表折磨过的人都知道，画一张图不难，难的是让一百张图看起来像同一个人画的，难的是改一个节点颜色不用把整张图重画，难的是让前端、后端、产品、运营四个角色拿到同一份图之后都能看懂、都能改、都不会改乱。diagram-design 要处理的，恰恰是后面这些事。

我把它理解成一套“图表设计系统”，而不是一个画图工具。工具解决的是“能不能画出来”，系统解决的是“画出来之后能不能维护、能不能复用、能不能规模化”。这两者的差别，就像你随手用画板画个流程图，和用一套带组件库、带样式变量、带布局约束的工程化方案去产出图表，完全是两个量级的事情。

这套东西适合谁？如果你只是偶尔画一张架构图发群里，那确实用不上，随便找个在线工具十分钟搞定。但如果你处在下面这几种场景里，diagram-design 的思路就非常值得参考：一是团队里多人协作产出图表，风格总是对不齐；二是图表需要跟着代码或数据自动更新，手工改图改到崩溃；三是同一套图要在文档、PPT、网页、打印稿里反复出现，每次都要重新适配；四是图表数量上了几十上百张之后，命名、分类、检索全乱套。

核心关键词其实就几个：图表设计系统、组件化、样式令牌、布局约束、可维护性。这几个词串起来，就是 diagram-design 的完整价值链。它不是在教你“怎么画得好看”，而是在教你“怎么让图表这件事变得可控”。可控意味着可预测、可复用、可批量修改、可交接。一个团队如果能把图表当成代码一样去管理，那省下来的时间是以人天计算的。

我见过太多项目，前期图随便画，后期需求一变，几十张图全部返工，因为每张图的颜色、间距、字体都是手调的，没有任何统一规则。diagram-design 的价值就在于，它把这些“手调”的部分提前抽象成了规则和组件，让变化只发生在一个地方，而不是散落在每一张图里。这就是为什么我说它不是工具，是系统。

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

2.1 图表失控的根源：样式和结构混在一起

大部分图表出问题，不是因为画得丑，而是因为样式信息和结构信息搅在一起。什么叫结构信息？就是“A 节点连到 B 节点，B 节点属于 C 分组”。什么叫样式信息？就是“A 节点是蓝色圆角矩形，边框两像素”。在随手画的图里，这两类信息是绑死的：你改一个节点的颜色，实际上是在改这个节点本身，而不是在改“所有同类节点”的规则。

这就导致一个致命问题：改一处，动全身。你想把所有“数据库”类型的节点从蓝色改成绿色，如果当初没有抽象出“数据库节点”这个组件，你就得一张图一张图去找、去改。十张图还能忍，一百张图就是灾难。

diagram-design 的第一个核心思路，就是把样式从结构里剥出来。节点只负责表达“我是什么类型、我连到谁”，至于“我长什么样”，交给外部的样式规则去决定。这个思路和前端开发里“结构、样式、行为分离”是一模一样的，只不过对象从网页换成了图表。

2.2 组件化：把重复出现的图形抽象成“零件”

剥出样式之后，下一步就是组件化。你会发现，不管什么图，总有一些图形是反复出现的：矩形节点、圆形节点、菱形判断、圆柱数据库、云朵服务、箭头连线、分组框。这些就是图表的“零件”。

把零件抽象出来之后，画图就变成了“搭积木”。你不再关心每个矩形具体多宽多高、什么颜色，你只关心“这里需要一个服务节点”“那里需要一个判断节点”。具体长什么样，由组件定义说了算。

这样做的好处非常直接。第一，一致性有了保障，所有服务节点长得一模一样，不会出现这张图圆角四像素、那张图圆角八像素的尴尬。第二，批量修改成为可能，改一次组件定义，所有用到它的图全部更新。第三，新人上手成本骤降，他不需要知道怎么调样式，只需要知道有哪些组件、分别用在什么场景。

我个人的经验是，组件粒度不要太细也不要太粗。太细了，组件数量爆炸，选组件比画图还累；太粗了，一个组件承担太多变体，内部又是一堆条件判断。比较舒服的粒度是：按语义划分，比如“服务”“数据库”“队列”“外部系统”“用户”，每个语义一个组件，变体控制在三到五种以内。

2.3 样式令牌：让颜色和间距变成“变量”

组件化解决了“形状复用”，但颜色、字体、间距这些还没解决。这时候就需要样式令牌，也就是把具体的值抽象成有名字的变量。

比如，不要直接写“#3B82F6”，而是定义color-primary；不要直接写“16px”，而是定义spacing-md。图里所有地方都引用令牌，而不是引用具体值。这样当品牌色变了，你只需要改color-primary这一个地方，所有图自动跟着变。

样式令牌分几层比较合理：最底层是原始值（比如blue-500），中间层是语义令牌（比如color-primary、color-danger），最上层是组件令牌（比如node-service-bg）。原始值几乎不变，语义令牌偶尔变，组件令牌跟着组件走。分层的好处是，改动的传播路径清晰，不会一改就牵动全局。

提示：样式令牌的命名一定要用“用途”而不是“外观”。叫color-primary比叫color-blue好，因为哪天主色从蓝变紫，color-blue这个名字就成了谎言，而color-primary依然成立。

2.4 布局约束：让图自己“站整齐”

手工画图最烦的就是对齐。这个节点比那个节点高了三个像素，这条线歪了一点点，肉眼看着别扭但就是找不到问题。diagram-design 的第四个思路是布局约束，也就是用规则来保证图自动对齐。

常见的约束包括：网格对齐（所有节点吸附到八像素网格）、等间距分布（同级节点之间距离相等）、层级对齐（同一层的节点顶部对齐）、连线正交（连线只走横竖两个方向，拐直角）。这些约束一旦设定好，画图的时候就不需要手动微调，系统会自动帮你摆正。

布局约束的价值在于，它把“审美”变成了“规则”。审美是主观的、不可复制的，规则是客观的、可复制的。一个团队只要有统一的布局规则，哪怕每个人审美不同，产出的图也能保持整齐一致。

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

3.1 组件库怎么建：从盘点现有图形开始

建组件库不要凭空想象，最靠谱的做法是先盘点你手头已有的图。把过去半年到一年里团队产出的所有图表翻出来，统计哪些图形出现频率最高。你会发现，真正高频的图形其实就那么十几种，剩下的都是长尾。

盘点的维度包括：图形类型（矩形、圆形、菱形、圆柱等）、语义角色（服务、数据库、用户、判断等）、出现频次、变体数量。统计完之后，按频次从高到低排序，先做前二十个组件，覆盖百分之八十的场景，剩下的边用边补。

每个组件需要定义的东西包括：默认尺寸、形状、填充色令牌、边框色令牌、文字样式令牌、内边距、可接受的变体。这些定义最好写在一个配置文件里，而不是散落在各个图里。配置文件用 YAML 或 JSON 都行，关键是单一数据源，所有图都从这里读。

# 组件定义示例（YAML 格式） components: service: shape: rounded-rectangle defaultSize: { width: 160, height: 64 } fill: token:node-service-bg border: token:node-service-border text: token:node-label padding: token:spacing-sm variants: - name: primary fill: token:node-service-primary-bg - name: disabled fill: token:node-disabled-bg

注意：组件定义里不要出现任何硬编码的颜色值或像素值，全部走令牌。这是保证后续可维护性的底线，一旦破例，后面就会有无数的破例。

3.2 样式令牌怎么定：三层结构加命名规范

样式令牌的三层结构前面提过，这里说具体怎么落地。最底层原始值，建议用一套成熟的色阶体系，比如从五十到九百，每个色相十个梯度。中间层语义令牌，按用途命名，比如color-primary、color-success、color-warning、color-danger、color-neutral。最上层组件令牌，按组件加属性命名，比如node-service-bg、edge-default-stroke。

命名规范要统一，我习惯用短横线连接的小写，层级之间用短横线分隔。比如node-service-primary-bg表示“节点-服务-主要-背景”。这样命名虽然长，但可读性极强，看到名字就知道用途，不需要去查定义。

令牌的数量要控制。我见过有的项目定义了上千个令牌，结果没人记得住，最后还是硬编码。比较合理的规模是：原始值几十个，语义令牌二三十个，组件令牌一百个以内。超过这个量级，就要考虑是不是抽象过度了。

3.3 布局约束怎么配：网格、间距、对齐三件套

布局约束的核心就三样：网格、间距、对齐。网格决定节点吸附的最小单位，一般用八像素，因为八能被二、四整除，缩放的时候不容易出现半像素。间距决定同级节点之间的距离，建议用令牌控制，比如spacing-sm是八像素、spacing-md是十六像素、spacing-lg是二十四像素。对齐决定同一层节点的对齐方式，一般顶部对齐或中心对齐，看图的类型。

配置的时候要注意，约束是建议不是强制。有些特殊图确实需要打破网格，这时候要允许手动覆盖，但覆盖要有记录，方便后续审查。我的做法是，默认全部走约束，需要覆盖的地方加一个标记，定期回顾这些标记，看能不能通过调整组件或令牌来消除。

连线也有约束。正交连线（只走横竖）比斜线更容易对齐，也更符合工程图的习惯。连线拐角用圆角还是直角，看团队偏好，但一旦定了就统一。连线上的标签位置也要约束，一般放在线的中点偏上，避免压住线。

3.4 文件组织：一张图一个文件还是一个大文件

这个问题没有标准答案，取决于图的规模和协作方式。我的经验是：按主题分目录，按图分文件。比如一个系统架构项目，目录结构可以是architecture/下面放overview.diagram、># 简化版渲染思路（Python 伪代码） import yaml def load_tokens(path): with open(path) as f: return yaml.safe_load(f) def resolve_token(value, tokens): # 把 token:xxx 解析成具体值 if isinstance(value, str) and value.startswith("token:"): key = value.split(":")[1] return tokens[key] return value def render_node(node, components, tokens): comp = components[node["type"]] fill = resolve_token(comp["fill"], tokens) width = comp["defaultSize"]["width"] height = comp["defaultSize"]["height"] # 生成 SVG rect 和 text return f'<rect width="{width}" height="{height}" fill="{fill}" />'

这个脚本的关键点是令牌解析和组件查找。令牌解析负责把token:node-service-bg变成#3B82F6，组件查找负责根据节点类型找到对应的组件定义。实际项目里还要处理连线、分组、文字换行、自动布局，但核心逻辑就是这个。

提示：渲染脚本不要一开始就追求功能完整，先支持最基本的节点和连线，跑通之后再逐步加功能。我见过有人一上来就想做全功能渲染器，结果三个月没产出可用东西，团队信心全没了。

4.3 参数计算：间距和对齐的数学

布局约束里涉及一些简单的计算，这里说清楚。假设网格是八像素，节点宽度是一百六十像素，那么节点宽度正好是二十个网格，对齐没问题。如果节点宽度是一百五十像素，那就不是网格整数倍，缩放或对齐时会出现半像素，所以节点尺寸尽量取网格的整数倍。

同级节点之间的间距，如果定spacing-md为十六像素，那么两个节点中心之间的距离就是节点宽度加十六。假设节点宽一百六十，中心距就是一百七十六。这个值不需要手动算，布局引擎会自动处理，但你要理解背后的逻辑，才能在出问题时排查。

连线拐角的圆角半径，一般取间距的一半比较协调。比如间距十六，圆角半径八。这个不是硬规则，但视觉上比较舒服。连线标签的位置，一般放在线段中点，垂直偏移负八像素，避免压线。

4.4 实操现场：一次批量改色的完整记录

说一个我实际做过的操作。当时团队要把所有“数据库”节点的颜色从蓝色改成绿色，涉及三十多张图。如果手工改，至少两天。用 diagram-design 的方式，操作如下。

首先，找到组件定义里数据库节点的填充令牌，假设是node-database-bg。然后，找到令牌定义里这个令牌引用的语义令牌，假设是color-primary。接着，把color-primary的值从蓝色改成绿色。最后，重新渲染所有图。

整个过程不到十分钟，三十多张图全部更新，而且颜色完全一致，没有任何遗漏。这就是把样式抽象出来的威力。如果当初没有抽象，这三十多张图里每张的数据库节点颜色都是硬编码的，改起来就是噩梦。

这个操作也暴露了一个问题：color-primary被数据库节点引用了，但可能还被别的地方引用。改它会影响所有引用处。所以更稳妥的做法是，数据库节点引用一个专门的node-database-bg，这个令牌再引用color-primary。这样改color-primary影响全局，改node-database-bg只影响数据库节点。分层的好处就在这里。

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

5.1 组件粒度失控：太多或太少都不行

最常见的问题就是组件粒度没把握好。太少了，一个组件承担太多变体，内部一堆条件判断，改起来容易出错。太多了，组件列表长得看不到头，选组件比画图还慢。

判断粒度是否合适的标准是：一个组件是否对应一个清晰的语义。如果两个图形语义相同但外观略有差异，应该合并成一个组件的两个变体；如果语义不同，哪怕外观一样，也应该拆成两个组件。比如“服务”和“数据库”外观可能都是矩形，但语义不同，应该分开。

排查技巧：定期统计组件的使用频次，低频组件考虑合并或删除，高频组件考虑是否需要拆分变体。我一般每个季度做一次组件审计，把使用次数少于三次的组件清理掉。

5.2 令牌命名混乱：改一个地方影响一片

令牌命名不规范是另一个高频问题。比如有人用color1、color2这种无意义命名，过两天自己都不记得color1是什么颜色。或者用color-blue这种外观命名，主色一换名字就失效。

排查技巧：定期检查令牌命名，确保全部用用途命名，且层级清晰。发现外观命名的，改成用途命名。发现无意义命名的，补上语义。这个工作枯燥但必要，令牌命名一旦乱掉，整个系统的可维护性就崩了。

注意：令牌改名是个破坏性操作，所有引用处都要同步更新。所以最好在项目早期就把命名规范定好，后期改名成本很高。如果非要改，用脚本批量替换，改完跑一遍渲染验证。

5.3 布局约束失效：手动覆盖太多

布局约束失效的表现是，图里到处都是手动调整的痕迹，网格对不齐、间距不一致、连线歪斜。原因通常是约束太严，正常操作经常触发约束冲突，大家就习惯性手动覆盖，久而久之约束就形同虚设。

排查技巧：统计手动覆盖的次数和位置，如果某个约束频繁被覆盖，说明这个约束设置不合理，需要调整。比如网格定得太细，节点尺寸经常不是整数倍，那就把网格调粗一点。约束的目的是服务画图，不是给画图添堵。

5.4 常见问题速查表

5.5 独家避坑技巧：三个我踩过的坑

第一个坑，过早追求完美。我一开始想把所有组件和令牌都定义得尽善尽美，结果花了大量时间在设计上，实际画图没画几张。后来想通了，先定一版能用的，边用边改，迭代速度反而快。设计系统是长出来的，不是设计出来的。

第二个坑，忽略文档。组件和令牌定义好了，但没写文档，新人不知道怎么用，还是按老办法硬编码。后来补了文档，每个组件配一个使用示例，新人上手快多了。文档不用很正式，一个 Markdown 文件，每个组件一段说明加一个示例，就够了。

第三个坑，没有自动化验证。有次改令牌，漏改了一个引用，导致部分图渲染出错，但没人发现，直到客户看到才暴露。后来加了一个验证脚本，每次改完自动检查所有引用是否有效，问题就再没出现过。自动化验证是设计系统能长期维护的关键。

6. 图表设计系统的扩展方向

6.1 从静态图到动态图：接数据源

diagram-design 搭好之后，一个自然的扩展方向是接数据源。比如架构图里的服务节点，可以从服务注册中心拉取实时状态，正常显示绿色，异常显示红色。这样图就不只是文档，而是监控面板。

实现思路是，在节点定义里加一个数据绑定字段，渲染时根据数据源的值决定样式。数据源可以是 API、数据库、配置文件，看场景。这个扩展的价值在于，图从“死”的变成“活”的，信息实时性大幅提升。

6.2 从手工画到自动生成：代码即图

更进一步，可以让图从代码自动生成。比如从代码的模块依赖关系生成架构图，从数据库 schema 生成 ER 图，从配置文件生成部署图。这样图永远和代码同步，不会出现文档过时的问题。

实现思路是写一个转换器，读代码或配置，输出 diagram-design 的中间格式，再渲染成图。这个转换器可以集成到 CI 里，每次代码提交自动更新图。这个方向技术含量高，但价值也大，适合对文档同步要求高的团队。

6.3 从单机到协作：版本控制与评审

图表进版本控制之后，就可以像代码一样做评审。每次改图提一个合并请求，团队成员评审，通过后合并。这样图的变更有了记录，谁改的、为什么改、改了什么，一目了然。

评审的重点不是审美，而是语义正确性和规范符合性。语义正确性指图是否准确反映了系统结构，规范符合性指是否用了正确的组件和令牌。这两点比图好不好看重要得多。

6.4 从团队到组织：设计系统的推广

如果这套东西在团队里跑通了，可以考虑推广到整个组织。推广的关键是降低使用门槛和展示价值。降低门槛靠文档、模板、培训；展示价值靠实际案例，比如“用了这套系统，改色从两天变成十分钟”。

推广过程中会遇到阻力，有人觉得麻烦，有人觉得没必要。我的经验是，不要强推，先找愿意尝试的团队做试点，做出成绩再自然扩散。设计系统的价值是显性的，只要有人尝到甜头，传播是很快的。

7. 我个人的一些实操体会

这套东西我断断续续用了两年多，最大的体会是：图表设计系统的核心不是技术，是纪律。技术方案再漂亮，如果团队不遵守规范，照样乱套。所以推行的时候，纪律比工具重要，习惯比功能重要。

另一个体会是，不要为了系统而系统。如果团队就两三个人，图就十几张，那确实没必要搞这么重。系统的价值随规模增长，规模不到的时候，轻量方案更合适。判断标准很简单：如果你觉得手工维护图表的成本已经影响到正常工作了，那就是时候上系统了。

最后分享一个小技巧：从一张图开始。不要一上来就全面铺开，选一张最复杂、最常改的图，用这套方法重做一遍，感受一下效果。如果效果好，再推广到其他图。这样风险最小，见效最快。我自己就是这么起步的，第一张图做完，团队里其他人看到效果，主动来问怎么做的，推广就水到渠成了。