企业官网建设流程全解析

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

第一次看到“artcraft”这个标题，我脑子里蹦出来的第一反应是“艺术”加“手艺”，一个把创意和动手能力揉在一起的东西。后来跟几个做独立开发的朋友聊，发现大家对这个词的理解出奇地一致：它不是一个具体的框架或者库，而更像是一种项目组织思路——把偏艺术化的视觉表达，和偏工程化的代码实现，用一套轻量、可复用的方式串起来。说白了，就是让那些“看起来很美但写起来很痛”的创意项目，能有一个不那么折腾的落地路径。

我自己接过不少类似的需求：给一个小型工作室做作品集站点、给独立游戏做一套可配置的视觉主题、给线下展览做交互装置的前端界面。这些项目的共同点是，视觉要求高、迭代频繁、但团队规模小，没有专门的设计系统团队来维护一套庞大的组件库。每次从零搭一套样式体系，或者硬套一个重型UI框架，结果都是前期爽、后期改到崩溃。artcraft这个思路吸引我的地方，就在于它试图用约定优于配置的方式，把视觉层的可变部分收敛到几个明确的入口，让创意人员能改、工程人员能控。

这篇文章我打算按自己实际落地过的一个模拟项目来拆，把artcraft这套思路从设计动机、核心结构、实操步骤到踩坑记录完整走一遍。适合谁看？如果你正在做偏视觉导向的前端项目，团队里设计和开发的边界比较模糊，或者你一个人要同时兼顾“好看”和“好维护”，那这篇应该能给你一些可以直接抄的作业。如果你只是想要一个开箱即用的UI库，那artcraft可能不是你的菜，它更像是一套方法论加轻量工具集，需要你理解它的取舍逻辑。

2. 整体设计思路拆解：为什么是“分层”而不是“大一统”

2.1 核心矛盾：视觉自由度与工程可维护性的拉扯

做创意类项目最头疼的就是这个矛盾。设计同学想要的是“这个圆角再大2px”“这个渐变角度调15度”“这个动效再慢0.1秒”，这些需求本身没有错，但落到代码里，如果每个视觉参数都散落在各个组件里硬编码，改一次就要全局搜索替换，迟早出事。反过来，如果为了可维护性把所有视觉参数都抽成设计令牌（design token），又会发现创意项目里大量的一次性样式根本不适合令牌化，强行抽象反而增加了认知负担。

artcraft的思路是分层治理：把视觉表达分成“稳定层”和“流动层”。稳定层是那些跨页面、跨组件复用的基础视觉规则，比如主色板、字号阶梯、间距基数、圆角体系，这些用令牌管理，改一处全局生效。流动层是那些一次性的、实验性的、跟具体内容强绑定的视觉处理，比如某个hero区域的特殊渐变、某张插画的滤镜组合，这些允许就地写，但必须放在一个明确的“作用域”里，不能污染全局。

这个分层逻辑听起来简单，但实操中最大的坑是边界模糊。我见过太多项目，一开始说好了“只有这几个是令牌”，做着做着发现某个“一次性”样式在三个地方都用了，于是又抽成令牌，抽完发现另外两个地方其实只是长得像但语义不同，又拆回去。来回折腾几次，团队就放弃了。所以artcraft在落地时，我建议加一条硬规则：任何视觉参数，如果在两个以上不同语义的上下文中出现，才考虑令牌化；否则一律留在流动层。这条规则帮我省了很多纠结时间。

2.2 为什么选“约定式目录结构”而不是“配置式”

很多类似思路的项目会提供一个配置文件，让你在里面声明各种视觉参数。artcraft反其道而行，它更倾向于用目录结构和文件命名约定来承载这些信息。比如，所有基础令牌放在tokens/目录下，按color、type、space、radius、motion分文件；所有流动层的样式放在跟组件同级的*.craft.css文件里，构建时自动识别并做作用域隔离。

这个选择背后的逻辑是：配置文件适合“少量、稳定、需要程序化读取”的参数，而创意项目里的视觉规则往往是“大量、多变、需要人眼快速定位”的。你让一个设计同学去改JSON配置文件里的某个色值，他得先理解整个配置结构；但你让他改tokens/color.css里的一个变量，他打开文件就能看懂。降低非工程角色的参与门槛，这是artcraft在团队协作场景下的核心优势。

当然，约定式也有代价。最大的问题是隐式知识多，新人进来如果不看文档，可能不知道*.craft.css会被特殊处理。我的做法是在项目根目录放一个ARTCRAFT.md，用最简短的篇幅把三条核心约定写清楚：令牌在哪、流动层在哪、构建时发生了什么。这三条写明白，基本就能自助上手了。

2.3 构建流程的取舍：为什么不做运行时方案

市面上有些方案是在运行时动态注入样式，好处是灵活，坏处是性能不可控、调试困难。artcraft选择在构建时完成大部分工作：令牌编译成CSS自定义属性，流动层样式做作用域哈希，最终输出的是静态CSS。这样做的好处是运行时零开销，产物可预测，而且可以直接用浏览器DevTools调试，不需要额外的运行时面板。

代价是动态主题切换会麻烦一些。如果你的项目需要用户实时切换主题，纯构建时方案就不够用了。我的处理方式是：构建时生成多套令牌的CSS自定义属性，运行时只切换根元素上的一个类名或属性，这样既保留了构建时的静态优势，又支持了有限度的动态切换。这个折中方案在实际项目里覆盖了90%以上的主题需求，剩下10%的极端动态场景，就老老实实走运行时注入，但把它隔离在一个明确的模块里，不让它扩散。

3. 核心细节解析：令牌体系与流动层的具体设计

3.1 令牌体系怎么定：从“原子”到“语义”的两级结构

artcraft的令牌体系我建议分两级：原子令牌和语义令牌。原子令牌是纯粹的值，比如--craft-blue-500: #3b82f6、--craft-space-4: 16px。语义令牌是对原子令牌的引用，比如--craft-color-primary: var(--craft-blue-500)、--craft-space-card-padding: var(--craft-space-4)。

为什么要分两级？因为直接改原子令牌风险大，你不知道有多少地方在用这个蓝色。改语义令牌就安全得多，--craft-color-primary改成另一个蓝色，所有引用主色的地方自动更新，而且语义清晰。这个模式不是artcraft独创，但在创意项目里特别有用，因为创意项目的视觉调整往往是“这个主色再暖一点”这种语义级需求，而不是“把blue-500改成另一个蓝”。

具体到文件组织，我是这样分的：

/* tokens/color.css */ :root { /* 原子层 */ --craft-blue-100: #dbeafe; --craft-blue-500: #3b82f6; --craft-blue-900: #1e3a8a; --craft-warm-500: #f97316; /* 语义层 */ --craft-color-primary: var(--craft-blue-500); --craft-color-accent: var(--craft-warm-500); --craft-color-surface: #ffffff; --craft-color-text: #1f2937; }

注意语义层的命名要跟具体色相解耦。不要叫--craft-color-blue，要叫--craft-color-primary。这样以后主色从蓝变橙，语义令牌名字不用改，引用它的地方也不用改。这个细节看起来小，但在长期维护的项目里能省很多事。

3.2 流动层的隔离机制：作用域哈希与命名约定

流动层是artcraft里最容易被误用的部分。我的经验是，必须用构建时作用域哈希来强制隔离。具体做法是：所有*.craft.css文件在构建时，其中的类名会被自动加上一个基于文件路径的哈希后缀。比如你在hero.craft.css里写了.title { ... }，构建后变成.title_a3f2 { ... }，同时HTML里的类名也会被自动替换。

这个机制的好处是物理隔离，你不可能不小心让一个流动层样式泄漏到全局。坏处是调试时类名不好看，DevTools里看到一堆哈希后缀。我的处理方式是在开发模式下关闭哈希，只在生产构建时开启。这样开发时调试体验正常，生产时隔离性有保障。

另一个细节是流动层之间的依赖。有时候一个流动层样式需要引用令牌，这没问题，直接var(--craft-color-primary)就行。但流动层之间不应该互相引用，否则就形成了隐式耦合。如果发现两个流动层需要共享某个样式，那说明这个样式应该提升到令牌层或者一个共享的中间层。这个判断规则我用了很久，基本能拦住大部分架构腐化。

3.3 响应式与状态变体的处理策略

创意项目里响应式和状态变体往往比常规项目更复杂，因为视觉要求高，不能简单用几个断点糊弄过去。artcraft的建议是把响应式也当作一种令牌维度。具体来说，在tokens/breakpoint.css里定义断点令牌，然后在流动层里用媒体查询引用这些令牌：

/* tokens/breakpoint.css */ :root { --craft-bp-sm: 640px; --craft-bp-md: 768px; --craft-bp-lg: 1024px; } /* hero.craft.css */ .title { font-size: 2rem; } @media (min-width: 768px) { .title { font-size: 3rem; } }

这里有个坑：CSS自定义属性不能直接用在媒体查询的条件里，所以断点令牌更多是文档性质的，实际写媒体查询时还是得写具体数值。我的做法是在构建时用PostCSS插件把@media (--craft-bp-md)这种写法编译成具体数值，这样源码里保持令牌引用，产物里是静态值。这个插件不复杂，几十行代码，但能显著提升源码的可读性和一致性。

状态变体（hover、focus、active、disabled）的处理，artcraft倾向于用数据属性而不是类名。比如[data-state="loading"]而不是.is-loading。原因是数据属性在HTML里更显眼，而且不容易跟样式类名混淆。这个选择见仁见智，但在多人协作的项目里，数据属性确实能减少“这个类名到底是样式还是状态”的沟通成本。

4. 实操过程：从零搭一个artcraft风格的项目

4.1 初始化与目录结构搭建

假设我们要做一个模拟项目——一个独立工作室的作品集站点，视觉要求高，需要支持深浅两套主题，页面数量不多但每个页面都有独特的视觉处理。我按artcraft思路来搭。

第一步是目录结构。我的习惯是这样：

project/ ├── ARTCRAFT.md ├── src/ │ ├── tokens/ │ │ ├── color.css │ │ ├── type.css │ │ ├── space.css │ │ ├── radius.css │ │ ├── motion.css │ │ └── breakpoint.css │ ├── components/ │ │ ├── button/ │ │ │ ├── button.html │ │ │ ├── button.craft.css │ │ │ └── button.js │ │ └── card/ │ │ ├── card.html │ │ ├── card.craft.css │ │ └── card.js │ ├── pages/ │ │ ├── home/ │ │ │ ├── home.html │ │ │ ├── home.craft.css │ │ │ └── home.js │ │ └── about/ │ │ └── ... │ └── global.css └── build/ └── ...

关键点是tokens/和*.craft.css的分离。global.css只放最基础的reset和根元素设置，不放任何具体视觉规则。所有视觉规则要么在令牌里，要么在流动层里，没有中间地带。这个纪律性很重要，一旦允许“就这一次放全局”，很快全局文件就会变成垃圾场。

4.2 令牌文件的具体编写与参数计算

令牌的数值不是拍脑袋定的，我一般按一个基数加比例的方式来算。间距基数取4px，然后按1.5倍左右递增：

/* tokens/space.css */ :root { --craft-space-1: 4px; --craft-space-2: 8px; --craft-space-3: 12px; --craft-space-4: 16px; --craft-space-5: 24px; --craft-space-6: 32px; --craft-space-7: 48px; --craft-space-8: 64px; }

为什么是4px基数？因为绝大多数屏幕的物理像素和CSS像素比例是整数或半整数，4px的倍数在缩放时不容易出现半像素模糊。为什么是1.5倍递增？因为人眼对间距的感知是非线性的，线性递增会导致小间距太密、大间距太疏。1.5倍左右是一个经验值，实际项目里可以根据视觉反馈微调。

字号阶梯我用的是模数化比例，基础字号16px，比例取1.25（大三度）：

/* tokens/type.css */ :root { --craft-font-size-xs: 0.64rem; /* 10.24px */ --craft-font-size-sm: 0.8rem; /* 12.8px */ --craft-font-size-base: 1rem; /* 16px */ --craft-font-size-lg: 1.25rem; /* 20px */ --craft-font-size-xl: 1.563rem; /* 25px */ --craft-font-size-2xl: 1.953rem; /* 31.25px */ --craft-font-size-3xl: 2.441rem; /* 39px */ }

这个比例在创意项目里比较好用，因为层级差异明显但不突兀。如果项目偏编辑类内容，可以换成1.2（小三度）；如果偏展示类，可以换成1.333（四度）。这个选择没有绝对对错，关键是全项目统一，不要这里1.25那里1.333。

4.3 流动层样式的编写与构建配置

流动层样式我以home页面的hero区域为例：

/* pages/home/home.craft.css */ .hero { position: relative; min-height: 80vh; display: flex; align-items: center; padding: var(--craft-space-8) var(--craft-space-5); background: linear-gradient( 135deg, var(--craft-color-primary) 0%, var(--craft-color-accent) 100% ); overflow: hidden; } .hero-title { font-size: var(--craft-font-size-3xl); line-height: 1.1; color: var(--craft-color-surface); max-width: 12ch; } .hero-title em { font-style: normal; display: block; font-size: var(--craft-font-size-lg); opacity: 0.8; margin-top: var(--craft-space-3); }

注意这里所有视觉参数都引用了令牌，没有硬编码的色值或间距。唯一硬编码的是135deg这个渐变角度和1.1这个行高，因为这两个是跟具体内容强绑定的，换一个hero区域可能就不适用了，所以留在流动层是合理的。

构建配置我用的是PostCSS加几个插件：postcss-import处理@import，postcss-custom-properties把令牌编译成静态值（同时保留自定义属性用于运行时主题切换），postcss-modules做作用域哈希。配置大概长这样：

// postcss.config.js module.exports = { plugins: [ require('postcss-import')(), require('postcss-custom-properties')({ preserve: true, importFrom: [ 'src/tokens/color.css', 'src/tokens/space.css', 'src/tokens/type.css' ] }), require('postcss-modules')({ generateScopedName: process.env.NODE_ENV === 'production' ? '[name]_[local]_[hash:base64:4]' : '[name]_[local]' }) ] };

preserve: true这个选项很关键，它让令牌既被编译成静态值（用于不支持自定义属性的老浏览器），又保留自定义属性（用于运行时主题切换）。代价是产物体积会大一些，但在创意项目里这个代价可以接受。

4.4 主题切换的运行时实现

深浅主题切换我按前面说的折中方案来做。在tokens/color.css里定义两套语义令牌：

:root { --craft-color-surface: #ffffff; --craft-color-text: #1f2937; --craft-color-primary: var(--craft-blue-500); } [data-theme="dark"] { --craft-color-surface: #111827; --craft-color-text: #f9fafb; --craft-color-primary: var(--craft-blue-100); }

然后运行时只需要切换根元素的>function setTheme(theme) { document.documentElement.setAttribute('data-theme', theme); localStorage.setItem('craft-theme', theme); } // 初始化 const saved = localStorage.getItem('craft-theme'); if (saved) setTheme(saved);

这个方案的好处是切换瞬间完成，不需要重新加载CSS，也不需要运行时计算。坏处是两套令牌都打包在产物里，体积翻倍。如果令牌文件很大，可以考虑按需加载，但大多数创意项目的令牌体积在几KB级别，翻倍也无所谓。

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

5.1 令牌改了但页面没变：缓存与优先级排查

这是最高频的问题。我按排查顺序列一下：

最常见的原因是开发服务器没监听tokens目录。很多构建工具的watch配置默认只监听源码目录，而tokens目录如果被排除在外，改了令牌不会触发重新构建。我的做法是在构建配置里显式把tokens目录加入watch列表，这个坑我踩过不止一次。

另一个常见原因是优先级问题。CSS自定义属性也遵循层叠规则，如果某个流动层样式里直接写了color: #333，那它就会覆盖令牌里的var(--craft-color-text)。排查时在DevTools里看computed值，如果显示的是具体色值而不是var(--craft-color-text)，说明被硬编码覆盖了。

5.2 流动层样式泄漏：作用域哈希失效的几种情况

作用域哈希失效通常有三种情况。第一种是动态类名，比如class="item-${index}"，这种类名在构建时不存在，所以不会被哈希，运行时也不会匹配到哈希后的样式。解决办法是改用数据属性，比如>/* * hero.craft.css * 意图：首页hero区域的渐变背景和标题排版 * 依赖令牌：color-primary, color-accent, space-8, font-size-3xl * 最后修改：2024-XX-XX */

这个注释头在排查问题时特别有用，能快速定位一个流动层样式依赖了哪些令牌，改令牌时也能快速评估影响范围。我现在的习惯是每个*.craft.css文件都加这个头，写起来不费事，但省下的排查时间很可观。

最后说一个我踩过的坑：不要过早优化令牌数量。一开始我总想把所有可能的视觉参数都令牌化，结果令牌文件膨胀到几百个变量，实际用到的不到一半。后来我改成“按需令牌化”，只有当一个参数在三个以上地方出现时才提升为令牌，令牌数量降下来了，可维护性反而更好。这个度需要根据项目实际情况把握，但“宁少勿多”在令牌化这件事上基本是对的。