企业官网建设流程全解析

1. 当"impeccable"成为前端交付的硬指标，我们到底在讨论什么

第一次看到"impeccable"这个词被拿来形容前端代码，我脑子里冒出来的不是"完美"这种虚词，而是一个很具体的画面：设计师把 Figma 稿甩过来，说"就按这个来，一个像素都别差"，然后你打开浏览器，发现间距差了 3px，圆角半径对不上，hover 状态的过渡曲线跟设计稿里写的 cubic-bezier 完全不是一回事。这种时候，代码能不能被称为 impeccable，不是靠感觉，是靠能不能经得起逐项比对。

这个词在当下的语境里，已经不只是形容词了。它背后对应的是一整套前端交付的质量标准——视觉还原度、交互一致性、响应式断点处理、无障碍语义、性能预算控制。而最近围绕它冒出来的热搜词，像 AI coding agents、frontend design、CLI、browser extension，其实指向的是同一件事：我们正在尝试用工具链把"impeccable"从主观判断变成可执行、可验证的流程。

我写这篇东西的出发点很简单。过去大半年我一直在折腾怎么让 AI 编码代理真正参与到前端开发里，不是那种"帮我写个按钮"的玩具级用法，而是让它理解设计意图、生成符合规范的代码、并且能在浏览器里被验证。踩过的坑不少，有些是工具本身的限制，有些是我自己一开始思路就错了。把这些整理出来，给同样在摸索这条路的人一个参考。

这篇文章适合几类人看：一是前端工程师，尤其是那种既要写业务代码又要跟设计稿死磕的；二是对 AI coding agents 感兴趣但还没找到落地场景的；三是团队里负责制定前端规范、想让交付质量更稳定的技术负责人。我不打算讲太多概念，重点放在"我实际怎么做的"和"为什么这么做"上。

2. 拆解 impeccable 在前端语境下的四层含义

2.1 视觉层：像素级还原不是强迫症，是信任基础

很多人觉得像素级还原是设计师的执念，工程师没必要跟着较劲。我一开始也这么想，直到有一次做 B 端后台，表格的行高设计稿写的是 48px，我图省事用了 46px，结果客户那边用 1366×768 的笔记本一看，说"感觉有点挤"。后来改回 48px，同样的内容，观感完全不一样。这件事让我意识到，设计稿里的数值不是随便定的，它背后有视觉节奏的考量。

impeccable 在视觉层的第一个要求，就是所有间距、尺寸、颜色值必须能从设计系统里找到出处。我现在的做法是，项目里维护一份 design tokens 的 JSON 文件，所有颜色、字号、间距、圆角、阴影都从这里取。AI 代理生成代码的时候，我要求它只能引用 token，不能写魔法数字。比如padding: 16px这种写法，必须写成padding: var(--spacing-md)。这样做的好处是，改设计规范的时候只需要改一处，而且 AI 也不会因为"猜"数值而跑偏。

颜色这块特别容易出问题。设计稿里一个灰色，可能是 #6B7280，也可能是 #6b7280，大小写不一致在代码里就是两个值。更麻烦的是透明度，设计工具里显示 60% 不透明度，导出的时候可能是 rgba(107,114,128,0.6)，也可能是 #6B728099。我现在的处理方式是，在 tokens 文件里把透明度也定义成变量，AI 生成的时候统一用color-mix或者预定义的 rgba 值，避免它自己算。

2.2 交互层：状态覆盖比主流程更能体现功力

一个按钮，默认状态谁都会写。但 impeccable 的要求是，hover、active、focus、disabled、loading 这五个状态一个都不能少，而且每个状态的视觉变化要有逻辑。我见过太多项目，按钮点下去没反馈，或者 focus 的时候只有一个默认的蓝色 outline，跟整体设计风格完全不搭。

这里有个很实际的坑：AI 代理生成组件的时候，如果你不明确要求，它默认只给默认态和 hover 态。focus 态它可能会加，但用的是浏览器默认样式。disabled 态经常被忽略。loading 态更是想不起来。我的做法是，在给 AI 的 prompt 里直接列一个状态清单，要求它逐个实现，并且每个状态都要有对应的 CSS 变量或者类名。

focus 态特别值得单独说。现在无障碍要求越来越高，键盘导航的用户依赖 focus 指示器来知道自己在哪。但默认的 outline 往往很丑，设计师会要求去掉。去掉之后如果不补一个自定义的 focus 样式，键盘用户就抓瞎了。我现在的标准做法是，用:focus-visible伪类，只在键盘操作时显示 focus 环，鼠标点击时不显示。这样既满足设计观感，又不牺牲无障碍。

2.3 响应式层：断点不是越多越好，是要有依据

响应式设计做了这么多年，还是有很多项目在断点设置上拍脑袋。我见过一个项目设了 12 个断点，从 320px 到 2560px 每 160px 一个，结果维护起来简直是灾难。impeccable 在响应式上的要求是，断点数量要克制，每个断点都要有明确的设备或场景对应。

我现在的习惯是只设三个核心断点：移动端（<768px）、平板（768px-1024px）、桌面（>1024px）。如果项目有特殊需求，比如大屏展示，再加一个 1440px 以上的。关键是，每个断点下的布局变化要有逻辑，不是简单地"窄了就堆叠"。比如一个卡片列表，移动端是单列，平板是两列，桌面是三列，这个变化要跟内容密度和可读性挂钩，而不是随便定的。

AI 代理在处理响应式的时候，容易犯的错误是只改宽度不改布局逻辑。比如它会把一个三列布局在移动端直接变成三行，但每个卡片的内部布局还是桌面端的那套，导致文字挤在一起。我的应对方式是，在 prompt 里明确描述每个断点下布局应该怎么变，甚至给出具体的 flex-direction 或者 grid-template-columns 的值。

2.4 性能层：impeccable 的代码不该让浏览器喘不过气

视觉和交互都到位了，如果页面加载要 5 秒，那也谈不上 impeccable。性能这块我关注三个指标：首屏渲染时间、布局偏移（CLS）、以及交互响应延迟。前端代码层面的优化，主要是减少不必要的重排重绘、合理使用 CSS containment、避免过大的图片和字体文件。

AI 代理生成代码时，一个常见问题是它喜欢用 JavaScript 动态计算样式，比如根据窗口宽度设置元素高度。这种写法在窗口 resize 的时候会触发大量重排。更好的做法是用 CSS 的aspect-ratio或者min-height配合clamp()来实现响应式尺寸，把计算交给浏览器引擎。

还有一个容易被忽略的点是字体加载。设计稿里用的自定义字体，如果直接@font-face引入而不做font-display: swap，页面在字体加载完成前会有一段空白期，文字不可见。我现在的做法是，关键字体用swap，非关键字体用optional，并且给字体文件做子集化，只保留项目实际用到的字符。

3. AI coding agents 介入前端工作流后，我的实际配置

3.1 为什么我最终选择了 CLI 而不是纯浏览器插件

一开始我是从 browser extension 入手的。理由很直观：在浏览器里直接看到效果，改完就能预览，反馈闭环最短。但用了一段时间之后，我发现几个绕不过去的问题。

第一是上下文丢失。浏览器插件通常只能看到当前页面的 DOM 和样式，它不知道这个组件在项目里的其他用法，也不知道设计 token 的定义。结果就是它生成的代码跟项目整体风格脱节。第二是版本管理困难。插件里改的东西，要同步回代码仓库，中间多了一道手动复制粘贴的工序，容易出错。第三是批量处理能力弱。一个项目几十个组件，靠插件一个个改，效率还不如自己写。

转向 CLI 之后，情况完全不一样了。CLI 工具可以直接读取项目文件，理解目录结构，知道哪些是组件、哪些是样式、哪些是配置文件。它生成的代码可以直接写入文件，纳入 git 管理。而且 CLI 可以脚本化，批量处理组件的时候，写个循环就能跑。

我现在的工作流是这样的：项目根目录放一个.impeccable配置文件，里面定义设计 token 的路径、组件目录、样式规范（比如用 BEM 还是 CSS Modules）、以及 AI 代理的行为约束。然后通过 CLI 命令触发代码生成或审查。比如impeccable check src/components/Button会扫描这个组件的代码，对照设计规范给出修改建议，甚至直接生成 patch。

3.2 配置文件的字段设计：约束比自由更重要

给 AI 代理太多自由，它就会放飞自我。我的配置文件里，约束性字段占了大部分。举几个关键字段：

{ "designTokens": "./src/styles/tokens.json", "componentDir": "./src/components", "styleStrategy": "css-modules", "forbiddenPatterns": [ "px(?!.*var\\()", "#[0-9a-fA-F]{3,8}(?!.*var\\()", "!important" ], "requiredStates": ["default", "hover", "focus-visible", "active", "disabled"], "responsiveBreakpoints": [768, 1024, 1440], "accessibility": { "minContrastRatio": 4.5, "requireAriaLabels": true } }

forbiddenPatterns这个字段特别有用。它用正则表达式匹配代码里不应该出现的模式。比如上面这条px(?!.*var\\()的意思是，禁止出现没有用 CSS 变量包裹的 px 值。AI 生成代码后，CLI 会自动扫描，发现违规就报错或者自动修正。!important也是我明令禁止的，因为它会破坏样式的可维护性。

requiredStates强制 AI 为每个交互组件实现所有状态。如果它漏了 disabled 态，CLI 会提示补全。accessibility里的对比度检查也很实用，AI 选的颜色如果对比度不够，会被拦下来。

3.3 从 prompt 到代码：我如何描述一个组件的需求

跟 AI 代理沟通，prompt 的写法直接决定输出质量。我总结了一个模板，包含五个部分：组件用途、视觉规格、交互行为、响应式规则、无障碍要求。

举个例子，我要生成一个通知横幅组件。我的 prompt 大概是这样：

生成一个 NotificationBanner 组件，用于在页面顶部展示系统通知。视觉上，背景色使用 token 里的--color-info-bg，文字颜色用--color-info-text，左侧有一个图标区域，右侧有关闭按钮。内边距用--spacing-md，圆角用--radius-sm。交互上，关闭按钮 hover 时背景变深，focus-visible 时显示 2px 的 focus 环，点击后横幅淡出并移除。响应式方面，移动端文字换行，关闭按钮固定在右上角；桌面端文字和按钮在同一行。无障碍要求：横幅容器加role="status"，关闭按钮加aria-label="关闭通知"。

这个 prompt 里，每个数值都指向 token，每个状态都有描述，响应式和无障碍也覆盖了。AI 拿到这样的输入，生成的代码基本一次就能用。如果我只说"生成一个通知横幅"，它大概率会给我一个用内联样式、没有状态处理、没有无障碍属性的半成品。

4. 用 CLI 把设计规范变成可执行的检查项

4.1 安装与初始化：那些文档里不会写的细节

CLI 工具的安装本身不复杂，但初始化配置的时候有几个坑。第一个是 Node 版本。我用的这个工具要求 Node 18 以上，但项目里如果有老依赖，可能还锁在 Node 16。我的建议是，用.nvmrc或者volta把项目 Node 版本固定下来，避免团队里有人用错版本导致 CLI 行为不一致。

第二个是配置文件的位置。有些工具默认在项目根目录找配置，有些支持在package.json里写。我倾向于单独放一个配置文件，因为字段多，写在package.json里太乱。而且单独文件可以加注释（用 JSONC 格式），方便团队新人理解每个字段的含义。

第三个是 token 文件的同步。设计 token 如果是从 Figma 导出的，格式可能跟 CLI 期望的不一样。我写了一个小的转换脚本，把 Figma 导出的 JSON 转成 CLI 能识别的扁平结构。这个脚本放在scripts/目录下，每次设计更新后跑一次。

# 转换设计 token node scripts/transform-tokens.js ./design/export.json ./src/styles/tokens.json # 初始化 impeccable 配置 npx impeccable init --tokens ./src/styles/tokens.json --style css-modules

4.2 检查规则的自定义：默认规则不够用怎么办

CLI 自带的检查规则覆盖了通用场景，但每个团队都有自己的规范。比如我们团队要求所有组件的 props 必须有 TypeScript 类型定义，而且类型名要以Props结尾。这个默认规则里没有，需要自己写。

自定义规则的写法通常是写一个 JavaScript 模块，导出一个函数，接收文件路径和内容，返回检查结果。我写过一个规则，检查组件文件里是否有export interface XxxProps或者export type XxxProps。如果没有，就报 warning。

// rules/require-props-type.js module.exports = { name: 'require-props-type', check(filePath, content) { if (!filePath.endsWith('.tsx')) return []; const hasPropsType = /export\s+(interface|type)\s+\w+Props/.test(content); if (!hasPropsType) { return [{ line: 1, message: '组件文件缺少 Props 类型定义', severity: 'warning' }]; } return []; } };

这个规则跑起来之后，团队里再也没人忘记写 Props 类型了。而且 AI 代理生成代码时，如果漏了类型定义，CLI 会直接报出来，它下一轮就会补上。

4.3 与 git hooks 集成：让检查在提交前发生

检查规则如果只在手动跑的时候生效，那迟早会被遗忘。我的做法是把它挂到 git 的 pre-commit hook 上。用husky或者simple-git-hooks都行，我用的后者，配置更简单。

// package.json { "simple-git-hooks": { "pre-commit": "npx impeccable check --staged" } }

--staged参数让 CLI 只检查暂存区里的文件，这样提交速度不会太慢。如果检查不通过，提交会被阻止，开发者需要先修复问题。这个机制刚上的时候，团队里有人抱怨"太严了"，但两周之后大家都习惯了，因为提前发现问题比上线后返工成本低得多。

注意：pre-commit hook 里不要跑太重的检查，比如全量扫描或者跑测试套件，否则每次提交都要等很久，大家会想办法绕过。只检查改动的文件就够了。

5. 浏览器扩展在验证环节的不可替代性

5.1 视觉回归测试：截图对比的精度控制

CLI 能检查代码规范，但代码规范不等于视觉正确。一个按钮的 padding 值写对了，但如果父容器的 flex 布局有问题，实际渲染出来还是歪的。这时候就需要浏览器扩展来做视觉验证。

我用的浏览器扩展支持截图对比。工作流程是：先在基准版本上截一张图，存为 baseline；然后改代码，再截一张图，跟 baseline 做像素级对比。差异超过阈值就报警。这个阈值我一般设 0.1%，因为字体渲染的细微差异是不可避免的，设 0 会导致大量误报。

截图对比有几个参数需要调。一个是视口尺寸，我通常测三个：375×812（移动端）、768×1024（平板）、1440×900（桌面）。另一个是等待时间，页面加载完到截图之间要留够时间，让字体和图片都渲染完。我一般设 2000ms，如果页面有动画，还要等动画结束。

// 浏览器扩展的配置示例 { "viewports": [ { "name": "mobile", "width": 375, "height": 812 }, { "name": "tablet", "width": 768, "height": 1024 }, { "name": "desktop", "width": 1440, "height": 900 } ], "waitForTimeout": 2000, "threshold": 0.001, "ignoreSelectors": [".dynamic-timestamp", ".ad-banner"] }

ignoreSelectors这个字段很关键。页面上有些内容是动态的，比如时间戳、广告位、用户头像，这些每次截图都不一样，如果不忽略，对比永远不通过。把这些选择器排除掉，只对比稳定的 UI 部分。

5.2 交互状态捕获：hover 和 focus 怎么测

静态截图只能验证默认状态。hover 和 focus 态需要模拟用户操作。浏览器扩展通常提供 API 来触发这些状态。比如page.hover('.button')然后截图，就能看到 hover 效果。

focus 态稍微麻烦一点，因为:focus-visible只在键盘操作时生效。扩展里可以用page.keyboard.press('Tab')来模拟键盘导航，让焦点落到目标元素上，然后再截图。这样测出来的 focus 样式才是真实的。

我遇到过一个问题：某些组件在 focus 时会有过渡动画，截图的时候动画还没结束，截到的是中间状态。解决办法是在触发 focus 之后等一段时间，或者用page.emulateMedia({ reducedMotion: 'reduce' })把动画关掉再截图。后者更稳妥，因为 reduced motion 本来就是无障碍要求的一部分，顺便也测了。

5.3 无障碍审计：自动化能查什么，不能查什么

浏览器扩展集成的无障碍审计工具，能自动检查的问题包括：图片缺少 alt 属性、表单元素缺少 label、颜色对比度不足、ARIA 角色使用错误、标题层级跳跃等。这些问题占了常见无障碍问题的六七成，自动化能覆盖。

但有些问题自动化查不了。比如 alt 文本写得对不对，机器只能判断"有没有"，不能判断"好不好"。一个装饰性图片写了 alt="图片"，技术上通过了，但实际上应该用 alt="" 并且加role="presentation"。再比如键盘导航的顺序是否合理，自动化能测出元素能不能被 Tab 到，但测不出顺序是否符合用户预期。

我的做法是，自动化审计作为第一道防线，跑在 CI 里，不通过就阻断合并。人工审计作为第二道，每个迭代抽几个关键页面，用屏幕阅读器实际走一遍。两者结合，基本能覆盖大部分无障碍问题。

6. 踩过的坑：那些让我重新思考工作流的时刻

6.1 AI 生成的代码"看起来对"但"跑起来错"

有一次我让 AI 生成一个模态框组件，代码看起来没问题，结构清晰，样式也用了 token。但实际跑起来，模态框打开后，背景滚动没有锁定，用户可以滚动后面的页面。这个问题在代码审查时很难发现，因为代码本身没有语法错误，逻辑也说得通，只是漏了一个overflow: hidden的处理。

这件事让我意识到，AI 代理缺乏"运行时直觉"。它不知道模态框打开时背景应该锁定，不知道下拉菜单展开时点击外部应该关闭，不知道表单提交时按钮应该禁用防止重复提交。这些都属于交互常识，但 AI 不会主动想到。

我的应对方式是在 prompt 里显式列出这些交互要求。现在我的模态框 prompt 模板里，固定包含这几条：打开时锁定背景滚动、按 Esc 关闭、点击遮罩关闭、焦点陷阱在模态框内、关闭后焦点返回触发元素。把这些写清楚，AI 就能生成正确的代码。

6.2 设计 token 更新后，AI 生成的代码没有同步

设计系统不是一成不变的。我们有一次把主色调从蓝色改成了紫色，token 文件更新了，但之前 AI 生成的组件代码里，有些地方直接写了旧的色值，没有引用 token。结果就是新组件是紫色，老组件还是蓝色，页面上两种颜色混在一起。

这个问题的根源是，AI 生成代码时，如果 token 文件里没有对应的变量，它可能会自己"猜"一个值写进去。要杜绝这种情况，需要在 CLI 的检查规则里加一条：禁止出现任何硬编码的颜色值。我用的正则前面提过，#[0-9a-fA-F]{3,8}(?!.*var\\()，匹配所有没有用 var() 包裹的十六进制颜色。这条规则加上之后，硬编码颜色基本绝迹了。

还有一个细节是 token 的命名。如果 token 名字起得不好，AI 找不到对应的变量，也会自己猜。比如--color-primary和--color-brand如果同时存在，AI 就不知道该用哪个。我的做法是，token 命名遵循一套严格的规则：--{category}-{property}-{variant}-{state}，比如--color-text-primary-hover。这样 AI 能根据语义找到正确的变量。

6.3 浏览器扩展和 CLI 的检查结果不一致

有一段时间，CLI 检查通过，但浏览器扩展截图对比失败。排查了半天，发现是 CLI 检查的是源码，浏览器扩展检查的是构建后的产物。构建过程中，PostCSS 插件把一些样式做了转换，比如把gap属性转成了margin，导致最终渲染效果跟源码预期有差异。

这个问题的教训是，检查工具要明确检查的是哪个阶段。源码检查关注代码规范和 token 使用，构建产物检查关注实际渲染效果。两者互补，但不能互相替代。我现在的流程是：CLI 检查在提交前跑，浏览器扩展检查在 CI 的构建后阶段跑。两个都通过，才算合格。

7. 把 impeccable 变成团队习惯，而不是个人执念

7.1 规范文档怎么写才有人看

我见过很多团队的规范文档，写得像法律条文，几十页，没人看。我的做法是，规范文档只写三部分：必须遵守的（违反会阻断合并）、建议遵守的（违反会提示但不阻断）、以及常见问题示例。每一条都配一个正例和一个反例，代码对比着看，比纯文字描述直观得多。

比如"必须使用设计 token"这一条，正例是color: var(--color-text-primary)，反例是color: #1F2937。再配一句话解释：硬编码色值会导致设计更新时无法同步。这样新人一看就懂，不用读长篇大论。

文档的维护也很重要。规范不是定完就完了，随着项目演进，有些规则会过时，有些新问题需要补充。我每个季度会 review 一次规范文档，把不再适用的规则删掉，把新踩的坑加进去。文档保持精简，大家才愿意看。

7.2 新人上手：从第一天就养成习惯

新人入职，如果第一周就让他按规范写代码，他会觉得理所当然。如果前三个月放养，后面再要求，他就会觉得你在刁难他。所以我的做法是，新人入职第一天，就把 CLI 工具和浏览器扩展装好，配置文件配好，然后给他一个简单的组件任务，让他走一遍完整流程。

任务通常是这样的：给一个按钮组件添加 loading 状态。这个任务不大，但涉及 token 使用、状态实现、无障碍属性、截图验证。新人做完之后，对整套流程就有了体感。后面再遇到复杂组件，他就知道该怎么做了。

我还会给新人一份"常见错误清单"，列出 AI 代理最容易犯的十个错误，比如漏掉 disabled 态、硬编码颜色、忘记 aria-label 等。新人审查 AI 生成的代码时，对照这个清单逐项检查，慢慢就形成条件反射了。

7.3 度量与反馈：怎么知道规范真的起作用了

规范推行一段时间后，需要有一些指标来衡量效果。我关注的指标有三个：一是代码审查中样式相关评论的数量，规范推行后应该下降；二是视觉回归测试的通过率，应该逐步上升；三是无障碍审计的违规数量，应该趋近于零。

这些指标不用搞得太复杂，从现有的工具里导出数据就行。比如视觉回归测试的通过率，浏览器扩展的报告里直接有。代码审查评论数量，从 git 平台的 API 拉一下就能统计。每个月看一次趋势，如果指标没有改善，说明规范执行有问题，需要排查原因。

提示：指标是用来发现问题、改进流程的，不是用来考核个人的。如果把指标跟绩效挂钩，大家就会想办法刷数据，反而失去了意义。

8. 关于工具选型，我的一些个人偏好

CLI 工具我试过好几个，最后留下来的是那种配置驱动、规则可扩展的。有些工具走的是"智能"路线，号称能理解你的意图自动生成代码，但实际用下来，可控性太差，生成的东西经常需要大改。我宁愿要一个"笨"一点但听话的工具，给它明确的规则，它严格执行，这样反而效率更高。

浏览器扩展我倾向于选那种 API 开放、能脚本化的。有些扩展功能很全，但只能手动点，没法集成到 CI 里。我现在的用法是，本地开发时用扩展的交互界面快速验证，CI 里用它的 headless 模式跑自动化检查。同一个工具，两种用法，数据还能互通。

AI 代理这块，我的建议是不要迷信某一个模型。不同模型在不同任务上的表现差异很大。有的擅长写 CSS，有的擅长处理 TypeScript 类型，有的对无障碍属性记得牢。我的做法是，把任务分类，不同类型的任务用不同的代理。比如纯样式任务用一个，涉及逻辑的用另一个。CLI 配置里可以指定每个任务用哪个代理，灵活切换。

最后说一个我自己的体会：工具再好，也替代不了对设计意图的理解。AI 能帮你写出符合规范的代码，但规范本身是否合理、设计稿是否考虑了边界情况，这些还是需要人来判断。impeccable 的终极目标不是让机器写出完美的代码，而是让人从重复劳动里解放出来，把精力放在真正需要判断力的地方。