企业官网建设流程全解析

1. 从"impeccable"说起：一个让前端设计不再"差不多就行"的工具

第一次看到"impeccable"这个词，是在一个前端开发者的聊天群里。有人甩了张截图，说"这玩意儿审我的UI跟审代码一样狠"。截图里是一个命令行界面，正在逐条列出某个页面上的设计问题：间距不一致、颜色对比度不达标、字体层级混乱、按钮圆角不统一。底下有人回了一句："这不就是给前端配了个设计总监吗。"

这个评价很准确。impeccable 本质上是一个面向 AI coding agents 的前端设计质量审查工具，它同时提供了 CLI 和 browser extension 两种使用形态。你可以在终端里跑它，也可以在浏览器里直接对当前页面做检查。它的核心能力是：把那些"看起来差不多但就是不对劲"的设计问题，变成一条条可量化、可定位、可修复的具体条目。

为什么这个东西值得单独拿出来讲？因为现在用 AI coding agents 写前端代码的人越来越多了。你用 codex cli 或者 zcode cli 生成一个页面，代码能跑，布局也大致对，但出来的东西总有一种说不清道不明的"AI味"——间距忽大忽小、颜色搭配说不上丑但就是不舒服、组件之间的视觉节奏完全乱套。impeccable 解决的就是这个问题：它不帮你写代码，它帮你审设计。

适合谁来用？三类人最需要。第一类是经常用 AI 生成前端代码但自己设计功底一般的开发者，你需要一个自动化的"设计检查"环节。第二类是有一定设计 sense 但缺乏系统化审查方法的前端工程师，你想把"感觉不对"变成"具体哪里不对"。第三类是做 side project 的独立开发者，你没有设计师资源，但你又不想让产品看起来像半成品。

我花了大概两周时间把 impeccable 的 CLI 和 browser extension 都摸了一遍，在各种项目上跑了不下几十次，踩了一些坑，也总结出了一些真正实用的配置和流程。下面把这些东西完整地分享出来。

2. 核心机制拆解：impeccable 到底在检查什么

2.1 设计规则的量化逻辑

impeccable 的工作方式，用一句话概括就是：把设计规范翻译成可执行的检查规则，然后逐条比对。

它内部维护了一套设计质量规则集，覆盖的维度包括但不限于：间距系统的一致性（比如你是否在用 4px 或 8px 的倍数）、颜色对比度是否符合可访问性标准、字体大小和行高是否形成合理的层级关系、组件的视觉权重是否与功能重要性匹配、布局的呼吸感是否足够。

这些规则不是拍脑袋定的。间距系统背后是栅格理论，颜色对比度背后是 WCAG 标准，字体层级背后是模块化比例（modular scale）的数学逻辑。impeccable 把这些东西固化成了检查项，你跑一次就能看到所有偏离规范的地方。

我实测下来，它最擅长抓的是这几类问题：

• 间距不一致：同一个页面里，卡片内边距有的地方是 16px，有的地方是 15px，有的地方是 18px。人眼不一定能立刻看出来，但整体感觉就是"不整齐"。impeccable 会直接把这些值列出来，告诉你哪些地方偏离了主导的间距系统。
• 颜色对比度不足：浅灰色文字放在白色背景上，看起来"高级"，但对比度只有 2.8:1，远低于 WCAG AA 标准的 4.5:1。impeccable 会标出具体元素和当前对比度值。
• 字体层级断裂：标题用 24px，副标题用 22px，正文用 16px。24 和 22 之间的差距太小，视觉上分不出层级。impeccable 会提示层级比例不合理。
• 组件状态缺失：按钮只有默认态，没有 hover、focus、active、disabled 状态的定义。这在 AI 生成的代码里极其常见。

2.2 CLI 与 browser extension 的分工

impeccable 的两个使用形态不是简单的"二选一"，它们有明确的分工。

CLI 的定位是"批量审查和 CI 集成"。你可以在项目根目录跑一条命令，它会扫描你指定的文件或目录，输出一份完整的审查报告。这份报告可以输出为 JSON、Markdown 或纯文本格式，方便你接入自动化流程。比如你可以在 CI 里加一步，如果 impeccable 的评分低于某个阈值，就直接 fail 掉这次构建。

Browser extension 的定位是"实时反馈和交互式调试"。你在浏览器里打开一个页面，点一下扩展图标，它就会对当前渲染出来的页面做检查。这个方式的好处是能看到真实渲染结果——有些问题在源码层面看不出来，但渲染出来就暴露了。比如 CSS 继承导致的意外样式覆盖、响应式断点下的布局塌陷、动态内容加载后的间距错乱。

我的建议是：开发阶段用 browser extension 做即时检查，提交代码前用 CLI 做一次完整扫描，CI 里用 CLI 做质量门禁。三个环节配合起来，基本不会漏掉问题。

2.3 与 AI coding agents 的配合逻辑

这是 impeccable 最有意思的地方。它不是要替代 AI coding agents，而是要成为 AI coding agents 的"设计审查层"。

你想想这个流程：你用 codex cli 生成一个组件，代码逻辑没问题，但设计质量参差不齐。这时候你跑一下 impeccable，它给你列出一堆问题。你把这些问题反馈给 AI agent，让它按条目修复。修复完再跑一遍 impeccable，确认问题解决。这个循环跑几轮，出来的东西质量会明显不一样。

我试过把这个流程固化成一个脚本：生成代码 → 跑 impeccable → 把报告喂回给 AI → 让它修复 → 再跑 impeccable。大概三轮之后，设计问题的数量会下降 70% 以上。当然，最后一轮还是需要人工判断，因为有些"问题"其实是设计意图，不是真的错误。

注意：impeccable 的检查结果是建议性的，不是强制性的。有些偏离规范的地方可能是你有意为之的设计决策。不要盲目追求 100% 合规，那会让设计变得死板。

3. 实操环境搭建：从安装到第一次跑通

3.1 CLI 安装与初始化

impeccable 的 CLI 安装方式取决于你的运行环境。最常见的方式是通过包管理器安装。如果你用的是 Node.js 生态，可以直接通过 npm 全局安装：

npm install -g impeccable-cli

安装完成后，验证一下是否成功：

impeccable --version

如果输出了版本号，说明安装成功。接下来在你的项目根目录初始化配置文件：

impeccable init

这个命令会在项目根目录生成一个impeccable.config.json文件。这个文件是你后续所有检查行为的控制中心。默认配置长这样：

{ "rules": { "spacing": { "enabled": true, "baseUnit": 4 }, "colorContrast": { "enabled": true, "level": "AA" }, "typography": { "enabled": true, "scaleRatio": 1.25 }, "componentStates": { "enabled": true } }, "ignore": ["node_modules/**", "dist/**", "*.min.css"], "output": { "format": "markdown", "path": "./impeccable-report.md" } }

这里有几个关键参数需要根据你的项目实际情况调整。baseUnit是你项目的间距基数，大多数设计系统用 4px 或 8px。level是颜色对比度标准，AA 是基础要求，AAA 更严格。scaleRatio是字体层级的比例，1.25 是比较常见的值，如果你想要更强烈的层级对比，可以调到 1.333 或 1.5。

3.2 Browser Extension 安装与配置

Browser extension 的安装方式取决于你用的浏览器。以 Chrome 为例，你可以在扩展商店里搜索 "impeccable" 找到它，或者如果你拿到了 .crx 文件，可以通过开发者模式手动加载。

安装完成后，你会在浏览器工具栏看到 impeccable 的图标。点击图标，它会弹出一个面板，上面有一个"检查当前页面"的按钮。点一下，它就会开始扫描当前页面。

第一次使用的时候，建议先在一个你熟悉的页面上跑一遍，看看它报出来的问题是否符合你的预期。如果报出来的问题太多太杂，可以在扩展的设置里调整检查规则的严格程度。我一般会把"间距检查"的容差调到 1px，这样不会因为 0.5px 的偏差就报警。

提示：browser extension 检查的是渲染后的页面，所以如果你的页面有动态加载的内容，确保内容加载完成后再点检查。否则会漏掉一部分元素。

3.3 与 codex cli / zcode cli 的集成方式

如果你日常用 codex cli 或 zcode cli 来生成前端代码，可以把 impeccable 嵌入到你的工作流里。具体做法是：在 AI 生成代码之后，自动触发一次 impeccable 检查，然后把检查结果作为上下文喂回给 AI。

以 codex cli 为例，你可以在它的配置文件里加一个 post-generation hook：

# 在 codex cli 的配置中 post_generation: - command: "impeccable check --path ./src/components --format json" output: "./impeccable-latest.json"

然后在你的 prompt 模板里加一句："请参考 impeccable-latest.json 中的设计问题列表，逐条修复。"

zcode cli 的集成方式类似，具体取决于它的插件机制。核心思路是一样的：让 AI 生成代码，让 impeccable 审查设计，让 AI 根据审查结果修复。这个循环跑起来之后，你的人工干预会越来越少。

4. 完整实操流程：从零跑通一次设计审查

4.1 准备一个测试页面

为了把流程讲清楚，我准备了一个典型的"AI 生成风格"的页面。这个页面用 codex cli 生成，功能上没问题，但设计上有一堆小毛病。页面结构大概是：一个导航栏、一个 hero 区域、三张卡片、一个页脚。

先把页面跑起来，然后在浏览器里打开。接下来我们分别用 browser extension 和 CLI 做检查，看看它们各自能发现什么问题。

4.2 Browser Extension 实时检查

打开页面后，点击 impeccable 的扩展图标，然后点"检查当前页面"。大概两秒钟后，面板上会列出所有检测到的问题。

我第一次跑的时候，报出来 23 个问题。其中最多的是间距问题，有 11 个。具体包括：导航栏的左右内边距是 20px，但卡片的内边距是 24px，页脚的内边距是 16px。三个值都不在 4px 的倍数上（20 是 4 的倍数，但 24 和 16 跟 20 不构成统一系统）。impeccable 的建议是统一用 24px 或 16px。

颜色对比度问题有 5 个。最严重的是卡片描述文字，用了 #999999 的颜色，在白色背景上的对比度只有 2.85:1，远低于 AA 标准的 4.5:1。impeccable 建议改成 #767676 或更深。

字体层级问题有 4 个。h1 是 32px，h2 是 28px，h3 是 24px。32 到 28 的差距太小，视觉上几乎分不出来。impeccable 建议把比例调整到至少 1.25 倍，也就是 h1 用 32px，h2 用 25.6px（取整 26px），h3 用 20.8px（取整 21px）。

组件状态问题有 3 个。按钮只有默认态，没有 hover 和 focus 状态。链接没有 visited 状态。输入框没有 error 状态。

这些问题的详细列表可以在扩展面板里逐条查看，每条都附带了具体的元素选择器和当前值。你可以直接复制选择器，到代码里定位修改。

4.3 CLI 批量扫描与报告生成

Browser extension 适合看单个页面，CLI 适合扫整个项目。在项目根目录跑：

impeccable check --path ./src --format markdown --output ./design-audit.md

这个命令会扫描./src目录下的所有前端文件，生成一份 Markdown 格式的审查报告。报告的结构大概是：

# Impeccable Design Audit Report ## Summary - Total issues: 47 - Spacing: 21 - Color Contrast: 12 - Typography: 8 - Component States: 6 ## Details ### Spacing Issues | File | Element | Current | Expected | Severity | |------|---------|---------|----------|----------| | src/components/Card.tsx | .card-body | 15px | 16px | Medium | | src/components/Nav.tsx | .nav-container | 20px | 24px | Low | ... ### Color Contrast Issues | File | Element | Foreground | Background | Ratio | Required | |------|---------|------------|------------|-------|----------| | src/components/Card.tsx | .card-desc | #999999 | #FFFFFF | 2.85:1 | 4.5:1 | ...

这份报告可以直接作为修复清单来用。我一般会把它贴到 issue tracker 里，逐条分配和修复。

4.4 修复循环与验证

修复的过程就不展开讲了，无非是改 CSS 或 Tailwind 类名。重点讲一下验证环节。

每修复一批问题，就重新跑一次 impeccable。我建议用--diff参数，这样它只会显示跟上次相比的变化：

impeccable check --path ./src --diff --baseline ./design-audit.md

这个命令会对比当前状态和基线报告，告诉你哪些问题已经修复，哪些是新出现的。这个功能在团队协作里特别有用，你可以把基线报告提交到仓库里，每次 PR 都跑一次 diff，确保没有引入新的设计问题。

我自己的习惯是：每完成一个功能模块，就跑一次完整检查，把报告存档。这样项目推进过程中，设计质量的变化趋势是可见的。

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

5.1 检查结果太多怎么办

这是新手最常见的问题。第一次跑 impeccable，报出来上百个问题，直接懵了。

我的处理方式是：先按严重程度排序，只处理 High 和 Critical 级别的。impeccable 的严重程度分级大概是这样的：

先把 Critical 和 High 清掉，你会发现页面观感已经有明显提升。Medium 和 Low 可以慢慢来，不用一次做完。

5.2 误报怎么处理

impeccable 不是完美的，有些报出来的问题其实是误报。比如你故意用了一个非标准的间距值来实现某种视觉效果，它也会报出来。

处理方式是在配置文件里加 ignore 规则：

{ "ignore": [ { "file": "src/components/Hero.tsx", "rule": "spacing", "reason": "有意的非标准间距，用于实现全 bleed 效果" } ] }

加 ignore 的时候一定要写 reason，不然过几个月你自己都忘了为什么忽略这条规则。

5.3 与现有设计系统的冲突

如果你的项目已经有一套成熟的设计系统，impeccable 的默认规则可能跟你的系统不一致。比如你的设计系统用 6px 作为间距基数，但 impeccable 默认是 4px。

这时候你需要改配置：

{ "rules": { "spacing": { "baseUnit": 6 } } }

改完之后重新跑，它就会按 6px 的倍数来检查。同理，字体比例、颜色标准这些都可以按你的设计系统来调整。

5.4 在 CI 里怎么用

在 CI 里用 impeccable，核心是设置一个质量门禁。比如：

impeccable check --path ./src --format json --output ./report.json impeccable gate --report ./report.json --max-critical 0 --max-high 5

gate命令会根据报告判断是否通过。如果 Critical 问题超过 0 个，或者 High 问题超过 5 个，就返回非零退出码，CI 就会 fail。

这个阈值可以根据项目阶段调整。新项目可以严格一点，老项目可以宽松一点，逐步收紧。

5.5 性能优化

impeccable 扫描大项目的时候可能会比较慢。我试过一个有 300 多个组件的项目，完整扫描要跑将近一分钟。

优化方式有几个：一是用--path参数只扫描你正在改的目录，不要每次都扫全量。二是用--cache参数开启缓存，第二次扫描会快很多。三是把node_modules和构建产物目录加到 ignore 里，避免扫描无关文件。

提示：如果你在 CI 里跑，建议把缓存目录也缓存起来，这样每次构建能省不少时间。

6. 我踩过的坑和总结出的经验

第一个坑是过度依赖自动化检查。我一开始把 impeccable 的评分当成唯一标准，追求 100% 合规。结果做出来的页面确实"规范"，但死板得不行，完全没有设计感。后来我调整了心态：impeccable 是辅助工具，不是设计决策的替代品。它帮你发现"可能有问题"的地方，但最终判断还是要靠人。

第二个坑是忽略了 browser extension 和 CLI 的差异。有一次我用 CLI 扫了一遍，觉得没问题，但用 browser extension 一看，发现了好几个渲染层面的问题。原因是 CLI 检查的是源码，而 browser extension 检查的是渲染结果。有些问题只在渲染后才会暴露，比如 CSS 继承导致的意外覆盖。所以两个都要用，不能偏废。

第三个坑是配置没调好就开始用。默认配置是针对通用场景的，但每个项目的设计系统都不一样。我建议花半个小时把配置文件调成跟你的设计系统匹配，后面会省很多事。

最后分享一个我觉得最实用的技巧：把 impeccable 的检查报告作为 AI coding agents 的输入上下文。具体做法是，在让 AI 修复设计问题的时候，把报告里的相关条目直接贴到 prompt 里，而不是笼统地说"帮我优化一下设计"。这样 AI 的修复会精准很多，因为它知道具体要改什么、改成什么值。

这个流程跑顺了之后，我用 AI 生成前端代码的质量明显上了一个台阶。以前生成完还要手动调半天样式，现在跑两轮 impeccable 加 AI 修复，基本就能达到可用的状态。当然，关键页面还是需要人工打磨，但至少不会出现那种一眼就能看出来的低级设计问题了。