企业官网建设流程全解析

1. 从“artcraft”这个名字说起：它到底想解决什么问题

第一次看到“artcraft”这个标题，我脑子里蹦出来的不是某个具体工具，而是一种很典型的需求信号：把“art”和“craft”这两个词拼在一起，本身就说明了一件事——有人想把偏艺术化的表达，和偏工程化的手艺，塞进同一个流程里。这不是简单的“做个好看的东西”，而是要让好看的东西能被稳定地、可重复地做出来。

我在实际项目里见过太多类似的场景：设计师出了一版视觉稿，开发照着做，做出来差了三成；或者反过来，开发自己搭了个能跑的原型，但视觉上完全没法交付。artcraft 这类项目要处理的，恰恰是这条裂缝。它适合谁看？如果你是从设计转前端、从后端转全栈、或者一个人要同时扛视觉和实现的小团队，那这个标题背后的东西值得你花时间。

核心关键词其实就三个：视觉表达、工程实现、可复现流程。这三个词决定了 artcraft 不是纯艺术项目，也不是纯技术项目，而是一个“把审美意图翻译成可执行结构”的中间层。我接下来会从整体设计思路、核心细节、实操过程、问题排查四个大块来拆，每一块都会给出我实际踩过的坑和能直接抄的配置。

2. 整体设计与思路拆解：为什么不能“先做出来再说”

2.1 核心矛盾：艺术意图的模糊性与工程实现的确定性

artcraft 这类项目最要命的地方在于，艺术侧的输入往往是模糊的。“我想要一种通透但有重量感的感觉”——这句话对设计师是有效的，对代码是无效的。工程侧需要的是确定性的参数：透明度 0.72、模糊半径 12px、阴影偏移 0 4px。artcraft 的设计思路，本质上是在这两者之间建一层“翻译层”。

我试过两种极端做法。第一种是让工程侧完全自由发挥，结果就是每次改版都像重新做一遍，视觉一致性全靠人肉记忆。第二种是把所有视觉参数写死成配置文件，结果设计师想调一个渐变角度都要提工单。artcraft 的合理路径是中间态：把可枚举的视觉维度抽成 token，把不可枚举的艺术判断留给人工决策点。

具体来说，颜色、间距、圆角、阴影、字体层级这些可以枚举的，全部进 token 体系；而“这个留白够不够呼吸感”“这个动效节奏对不对”这类判断，保留为人工 review 环节。这个划分不是拍脑袋定的，是我在三个项目里反复调整后得出的比例：大约 70% 的视觉决策可以 token 化，剩下 30% 必须留给人。

2.2 方案选型：为什么我最终放弃了“全自动生成”

市面上有一类思路是“输入一张设计稿，自动生成代码”。我早期也试过这条路，结论是：在 artcraft 这种强调 craft 的场景下，全自动生成会丢掉太多东西。自动生成的代码往往结构冗余、命名混乱，而且一旦设计稿有细微调整，生成结果会整体漂移，review 成本反而更高。

我最终采用的方案是“半自动 + 强约束”。具体分三层：

• 第一层：token 层。用一份 JSON 或 YAML 定义所有基础视觉变量，这是唯一的数据源。
• 第二层：组件层。每个组件只允许引用 token，不允许写魔法数字。这一层用 lint 规则强制约束。
• 第三层：组合层。页面由组件拼装，拼装过程中允许人工微调，但微调必须回写到 token 或组件，不允许在页面里写一次性样式。

这个三层结构的好处是，任何一次视觉调整都能追溯到具体层级。改一个主色，token 层改一处，全站生效；改一个组件的圆角逻辑，组件层改一处，所有引用该组件的地方同步。实测下来，改版效率比“到处改样式”的做法提升了大概三到四倍。

2.3 影响范围：不只是前端的事

artcraft 的影响范围经常被低估。很多人以为它只跟前端样式有关，但实际上它会波及：

我踩过最深的坑是测试环节。早期没有视觉回归，改了一个 token 之后，某个边缘页面的对比度掉到了不可读的程度，上线后才发现。后来加了基线截图对比，每次 token 变更自动跑一遍，问题在合并前就能拦住。

3. 核心细节解析与实操要点：token 体系怎么搭才不塌

3.1 token 的命名规范：别用“蓝色”“大号”这种词

token 命名是 artcraft 里最容易被忽视、但影响最深远的一环。我见过太多项目用blue-500、font-large这种命名，结果设计师说“这个蓝再冷一点”，你根本不知道改哪个。正确的做法是按语义命名，不按外观命名。

我实际用的命名结构是三层：类别-角色-变体。比如：

• color-brand-primary：品牌主色
• color-text-secondary：次要文字色
• space-section-gap：区块间距
• radius-card-default：卡片默认圆角

这样命名的好处是，当品牌色从蓝变绿时，你改的是color-brand-primary的值，而不是去全局搜索blue-500。我做过统计，按外观命名的项目，一次主色变更平均要改 40 多处；按语义命名的，改 1 处。

注意：语义命名不要过度抽象。我见过有人用color-emphasis-level-3这种命名，结果没人记得住 level 3 到底是什么。语义要具体到“这个 token 用在哪”，而不是“这个 token 有多重要”。

3.2 数值计算：间距和字号的数学关系

artcraft 里最需要计算的其实是间距和字号。很多人凭感觉给值，结果页面节奏忽松忽紧。我用的是一套基于基准值的倍数体系：

• 基准间距space-unit = 4px
• 常用间距：4, 8, 12, 16, 24, 32, 48, 64
• 字号基准font-unit = 4px，但字号用另一套比例

字号我用的是 1.25 的模数比例（也叫大三度）：

这个比例不是随便定的。1.25 的好处是相邻层级差异明显但不突兀，1.2 太接近，1.333 又跳得太厉害。我实测下来，正文 15px、标题 24px 这个组合在大多数屏幕上阅读舒适度最好。

间距的倍数体系也有讲究。为什么用 4 而不是 5 或 8？因为 4 能被 2 整除，在二倍屏、三倍屏上都能对齐到物理像素。8 虽然更省事，但 8 和 12 之间的过渡太粗，做紧凑布局时不够用。4 的粒度刚好。

3.3 组件层的约束：lint 规则怎么写

token 体系搭好之后，最大的风险是有人绕过 token 直接写值。我用的 lint 规则核心就三条：

1. 样式文件中禁止出现裸数值（px、rem、hex 颜色），除非在 token 定义文件里。
2. 组件必须从 token 模块导入，不允许跨层引用。
3. 新增 token 必须走 review，不允许在业务代码里临时定义。

具体实现上，我用的是 stylelint 的自定义规则加上一个 pre-commit hook。配置大概长这样：

{ "rules": { "declaration-property-value-disallowed-list": { "/^color/": ["/^#/", "/^rgb/", "/^hsl/"], "/^margin/": ["/^\\d+px/"], "/^padding/": ["/^\\d+px/"] } } }

这个规则会在提交时拦住裸值。刚开始团队会抱怨“太严了”，但两周之后就习惯了，因为改 token 比改散落的样式快得多。

提示：lint 规则要给出清晰的错误信息。我一开始只报“disallowed value”，没人知道该改成什么。后来改成“请使用 token: color-text-primary 替代 #333”，修复率立刻上去了。

3.4 多端映射：一套 token 怎么适配不同端

artcraft 如果只做一端，token 体系相对简单。但一旦涉及多端（比如 Web 和移动端），就需要做映射层。我的做法是：token 定义只存语义，具体值按端映射。

比如space-section-gap在 Web 上是 32px，在移动端可能是 24px。映射关系放在单独的配置文件里：

const platformMap = { web: { 'space-section-gap': '32px' }, mobile: { 'space-section-gap': '24px' } };

这样做的好处是，组件代码里只写space-section-gap，具体值由构建时注入。我试过在组件里写条件判断，代码很快就变得不可维护。映射层虽然多了一层配置，但长期看省事得多。

4. 实操过程与核心环节实现：从零搭一套 artcraft 流程

4.1 第一步：定义 token 源文件

我用的格式是 YAML，因为可读性好，而且支持注释。文件结构按类别分：

color: brand: primary: "#2F6FED" secondary: "#7A5AF8" text: primary: "#1A1A1A" secondary: "#5C5C5C" disabled: "#A0A0A0" space: unit: 4 section: gap: 32 padding: 24 radius: card: default: 8 large: 16

这个文件是唯一数据源。所有其他格式（CSS 变量、JS 对象、设计工具 token）都从这里生成。我写了一个小脚本做转换，大概 80 行代码，跑一次生成所有产物。

注意：token 文件一定要进版本控制，而且每次变更要有 commit message 说明原因。我见过有人改了 token 不写原因，三个月后没人知道为什么color-brand-primary从蓝变成了紫。

4.2 第二步：生成 CSS 变量和 JS 常量

生成脚本的核心逻辑是遍历 YAML，输出两种格式。CSS 变量用于样式层，JS 常量用于逻辑层（比如根据 token 计算动画时长）。

// 生成 CSS 变量的核心逻辑 function generateCSS(tokens) { let output = ':root {\n'; for (const [category, values] of Object.entries(tokens)) { for (const [key, value] of flatten(values)) { output += ` --${category}-${key}: ${value};\n`; } } output += '}\n'; return output; }

生成出来的 CSS 变量长这样：

:root { --color-brand-primary: #2F6FED; --color-text-primary: #1A1A1A; --space-section-gap: 32px; --radius-card-default: 8px; }

组件里直接用var(--color-brand-primary)，不写任何裸值。这样改 token 文件，重新生成，全站生效。

4.3 第三步：组件实现与 review 流程

组件实现阶段，我强制要求每个组件附带一个“token 使用清单”。比如一个卡片组件，清单里要写明它用了哪些 token：

• 背景：color-surface-default
• 圆角：radius-card-default
• 内边距：space-card-padding
• 阴影：shadow-card-default

这个清单的作用是 review 时快速判断组件是否合规。我试过不写清单，review 时全靠肉眼扫代码，漏检率很高。有了清单，review 时间从平均 15 分钟降到 5 分钟。

review 流程我设了两个检查点：

1. 自动检查：lint 规则跑一遍，裸值直接拦。
2. 人工检查：看 token 使用清单，判断语义是否合理。

人工检查这一步不能省。我遇到过组件用了color-text-primary但实际场景应该是color-text-secondary的情况，lint 查不出来，只有人看才能发现。

4.4 第四步：视觉回归测试的落地

视觉回归是 artcraft 流程里最容易被跳过、但最不该跳过的一环。我的做法是用截图对比工具，每次 token 变更后自动跑一遍关键页面。

具体配置：

# 截图对比的核心命令 npx visual-regression \ --baseline ./baseline \ --current ./current \ --threshold 0.1 \ --output ./diff

threshold 0.1表示允许 10% 的像素差异。这个值我调过几次，0.05 太严，正常渲染差异都会报错；0.2 太松，明显的视觉问题会漏掉。0.1 是实测下来误报和漏报比较平衡的点。

基线截图要定期更新，但不能随便更新。我的规则是：只有确认视觉变更是预期的，才更新基线。我见过有人为了“让测试通过”直接覆盖基线，结果把真正的视觉 bug 也覆盖掉了。

5. 常见问题与排查技巧实录：那些文档里不会写的事

5.1 token 改了但页面没变：缓存和构建顺序问题

这是最高频的问题。改了 token 文件，重新生成，页面还是旧样式。原因通常有三个：

我踩过最坑的一次是生成脚本跑了，但输出目录配错了，生成到了旧目录。排查方法是直接看生成的 CSS 文件时间戳，如果时间戳没变，说明生成没生效。

提示：在构建流程里加一个校验步骤，检查生成的 CSS 文件是否包含最新的 token 值。我写了一个简单的 grep 检查，构建时跑一遍，能拦住 90% 的这类问题。

5.2 设计师说“感觉不对”但说不出哪里不对

这是 artcraft 里最难的场景。设计师的直觉往往是对的，但表达不出来。我的处理流程是：

1. 先对比 token 值，看是否有明显偏差。
2. 如果 token 值一致，做并排截图对比。
3. 如果截图也看不出，用取色器逐像素对比。

我遇到过一次，设计师说“按钮感觉轻了”，token 值完全一致。最后逐像素对比发现，是阴影的模糊半径差了 2px。这种差异肉眼很难定位，但取色器一测就出来了。

所以我的经验是：不要跟设计师争论“感觉”，直接用工具量化。量化之后，要么是 token 问题，要么是渲染问题，都能定位。

5.3 多端 token 映射错乱

多端项目里，token 映射错乱是常见问题。典型表现是移动端用了 Web 的间距值，页面挤成一团。排查方法：

• 检查映射配置文件的键名是否和 token 定义一致。
• 检查构建时是否注入了正确的端标识。
• 检查组件是否硬编码了端判断。

我用的排查顺序是：先看构建产物里的 CSS 变量值，确认注入是否正确；再看组件代码，确认没有硬编码。这两步能解决大部分映射问题。

5.4 视觉回归误报太多怎么办

视觉回归刚上线时，误报率很高，团队很快就没人看了。我做了三件事把误报降下来：

1. 排除动态内容：时间戳、随机数、动画中间态，全部在截图前屏蔽。
2. 设置合理的 threshold：0.1 是起点，按项目实际情况微调。
3. 分区域对比：整页对比改成关键区域对比，减少无关区域的干扰。

调整之后，误报率从大概 40% 降到了 5% 以下，团队才真正开始用这个测试。

5.5 常见问题速查表

6. 我实际用下来的一些体会

artcraft 这套东西，说到底不是技术问题，是流程问题。技术上的 token 体系、lint 规则、视觉回归，都是手段；真正的核心是让“视觉决策”和“工程实现”之间有据可查、有迹可循。

我最大的体会是：不要追求一步到位。我第一个项目想一次性把 token 体系搭完整，结果定义了 200 多个 token，团队根本记不住，最后废弃了一半。第二个项目我只定义了 30 个核心 token，用起来反而顺。token 数量不是越多越好，够用就行，不够再加。

另一个体会是：视觉回归测试要早做。我早期项目没做，改版时全靠人肉检查，漏掉过好几次对比度问题。后来加了自动截图对比，虽然初期配置麻烦，但长期看省下的排查时间远超投入。

最后分享一个小技巧：token 变更时，在 commit message 里写清楚“为什么改”和“影响范围”。我现在的格式是token: 改 color-brand-primary 从 #2F6FED 到 #1F5FDD，原因：品牌色调整，影响：所有主按钮和链接。这样三个月后回头看，还能知道当时为什么改。这个习惯看起来小，但实际用起来能省很多沟通成本。