企业官网建设流程全解析

1. 从“impeccable”说起：一个前端设计增强工具的真实定位

第一次看到“impeccable”这个词，是在几个 AI coding agent 的讨论群里。有人甩出一句“impeccable skill 装完，前端页面终于不像 AI 生成的了”，底下立刻一堆人追问怎么装、支持不支持 codex cli、claude cli 能不能直接用。我当时的反应是：又一个包装概念的工具？但架不住反复被刷屏，还是去把它拉下来跑了一遍。

结论先放这儿：impeccable 不是一个独立的设计软件，也不是一个能自动帮你写页面的 AI，它更像是一层“设计约束层”，挂在你已有的 AI coding agent 工作流上，专门治 AI 生成前端时那种“能跑但难看”的毛病。它通过 CLI 和浏览器扩展两种形态介入，把一套经过打磨的设计规范、间距体系、配色逻辑、组件结构，注入到 agent 的生成过程里，让输出结果从“功能正确”往“视觉可用”靠。

它解决的问题非常具体。用过 codex cli、claude cli 这类工具的人都知道，你让它写一个登录页、一个仪表盘、一个卡片列表，它给你的 HTML/CSS 大概率是：颜色是随手挑的蓝，间距是 16px 和 24px 混着来，圆角一会儿 4px 一会儿 8px，字体大小没有层级，hover 状态基本靠猜。功能上没毛病，但拿给设计师看，对方会沉默三秒。impeccable 要干的就是这件事——在 agent 生成之前或之后，用一套明确的规则去约束和修正这些视觉决策。

适合谁来用？三类人最对口。第一类是独立开发者和小团队，没有专职设计师，但产品又不能长得太寒碜；第二类是前端工程师，自己审美在线但不想每次都给 AI 擦屁股；第三类是产品经理和创业者，用 AI 快速做原型，希望原型能直接拿去给人看而不是只给自己看。如果你只是偶尔让 AI 写个脚本、跑个数据处理，那 impeccable 对你意义不大；但只要你频繁用 AI 生成界面，它值得花半小时研究一下。

我下面会从它的设计思路、核心机制、CLI 和浏览器扩展两条实操路径、以及我踩过的坑，完整拆一遍。内容基于我自己的使用记录和常见实践补充，不是官方文档的复述。

2. 核心设计思路拆解：为什么是“约束层”而不是“生成器”

2.1 一个关键判断：AI 不缺生成能力，缺的是决策纪律

要理解 impeccable 为什么长这样，得先理解 AI 生成前端的问题到底出在哪。很多人以为是“AI 不会写 CSS”，其实不对。你让 claude cli 写一个 flex 布局，它写得比很多工作两三年的前端还规范。真正的问题是决策不一致。

同一个页面里，AI 会在不同位置做出互相矛盾的视觉决策。标题用 20px，副标题用 18px，正文用 15px，注释用 13px——看起来有层级，但 20 和 18 差 2px，视觉上几乎分不出来，而 18 和 15 差 3px 又跳得太明显。间距也是，卡片内边距 20px，卡片之间 16px，区块之间 32px，没有一套统一的基数。颜色更典型，主色是 #3B82F6，按钮 hover 变成 #2563EB，链接又是 #60A5FA，三个蓝各说各话。

这不是能力问题，是没有约束。AI 每次做决策都是独立的，它不知道上一个决策是什么，也没有一套“必须遵守的规则”去校准。impeccable 的核心思路就是：不去增强 AI 的生成能力，而是给它一套决策纪律，让它在做视觉选择时有据可依。

这个判断很重要。市面上很多工具试图用“更好的模型”或“更多的训练数据”来解决前端美观问题，但 impeccable 走的是另一条路——用规则和约束去收窄 AI 的自由度。自由度低了，一致性自然就高了。

2.2 约束层的三个组成部分

impeccable 的约束体系我拆下来大概是三块：尺度系统、语义令牌、结构模板。

尺度系统解决的是“数值从哪来”。它定义了一套间距基数（通常是 4px 或 8px 的倍数）、一套字号阶梯（比如 12/14/16/20/24/32/48）、一套圆角档位（4/8/12/16/full）、一套阴影层级（sm/md/lg/xl）。AI 在生成时不能随便写padding: 17px，必须从这套尺度里选。这就像给一个装修队规定了“所有瓷砖只能用这五种尺寸”，出来的效果不一定惊艳，但绝对不会乱。

语义令牌解决的是“颜色和状态怎么表达”。它不直接给你#3B82F6，而是给你primary、primary-hover、primary-active、surface、surface-raised、border-subtle、text-primary、text-secondary这样的语义名。AI 写样式时引用语义名，底层色值由令牌系统统一管理。好处是换主题、调色时只改一处，而且 AI 不会在同一个页面里用出三个不同的“主色”。

结构模板解决的是“组件长什么样”。它预置了一批常见组件的结构规范——按钮的内边距和最小高度、输入框的边框和聚焦态、卡片的圆角和阴影组合、表格的行高和分隔线。AI 生成这些组件时，模板会作为参考注入，避免每次从零发明。

2.3 为什么用 CLI + 浏览器扩展双形态

这是我觉得 impeccable 设计上比较聪明的地方。它没有只做 CLI，也没有只做扩展，而是两条腿走路，因为这两种形态解决的是不同阶段的问题。

CLI 形态介入的是生成阶段。你在 codex cli 或 claude cli 里调用 impeccable skill，它会在 agent 生成代码的过程中注入约束。这时候约束是“事前”的，AI 从一开始就在规则内工作，出来的代码天然符合规范。适合的场景是：你要从零做一个页面或一个组件，希望一次成型。

浏览器扩展形态介入的是审查阶段。页面已经生成出来了，你在浏览器里打开，扩展会实时扫描 DOM，标出违反尺度系统的地方——这个 padding 不在基数上、这个字号不在阶梯里、这个颜色不在令牌中。它还能给出修正建议，甚至一键应用。适合的场景是：你手上已经有一堆 AI 生成的页面，想批量体检和修正。

两种形态共享同一套约束规则，所以 CLI 生成的东西扩展能审，扩展修正的结果也能反哺回代码。这个闭环是它区别于普通 lint 工具的关键。

3. CLI 形态实操：在 codex cli 和 claude cli 里挂载 impeccable skill

3.1 安装前的环境确认

在动手之前，先把环境理清楚。impeccable 的 CLI 形态本质是一个 skill 包，需要挂载到支持 skill 机制的 agent 上。目前主流的是 codex cli 和 claude cli 两条线，安装方式略有差异。

先确认你的 agent 版本。codex cli 建议用较新的版本，老版本可能不支持 skill 的动态加载。在终端里跑一下版本命令，确认输出正常。claude cli 同理，尤其是 Mac 环境下用 qwen key 或其他第三方 key 的配置，要确保 agent 本身能正常跑通一次对话，再考虑挂 skill。

# 确认 codex cli 可用 codex --version # 确认 claude cli 可用 claude --version

如果这两条命令报错，先解决 agent 本身的安装问题，别急着上 impeccable。我见过有人 skill 装了半天没反应，最后发现是 agent 根本没装好。

3.2 安装 impeccable skill 的两种路径

安装路径取决于你的 agent 生态。常见做法有两种：包管理器安装和手动挂载。

包管理器安装适合 codex cli 这类有插件市场的 agent。通常是一条 install 命令，指定 impeccable 的包名，agent 会自动下载并注册 skill。这种方式的优点是升级方便，缺点是版本可能滞后。

手动挂载适合 claude cli 或需要定制的情况。你需要把 impeccable 的 skill 目录克隆到 agent 的 skill 搜索路径下，然后在配置文件里注册。skill 目录里一般包含一个清单文件（描述 skill 的名称、触发词、能力）和若干规则文件（尺度系统、令牌、模板）。

# 手动挂载的典型结构 ~/.agent/skills/ impeccable/ manifest.json # skill 清单 tokens.json # 语义令牌 scale.json # 尺度系统 templates/ # 组件模板

挂载完成后，重启 agent，让它重新扫描 skill 目录。这一步很多人会忘，导致 skill 装了但 agent 不认。

3.3 触发 impeccable skill 的正确姿势

skill 装好之后，怎么让它生效？这里有个关键点：impeccable 不是自动生效的，需要显式触发。你可以在对话里用触发词唤醒它，比如提到“用 impeccable 规范生成”“按设计系统来”“遵循尺度系统”之类。不同 agent 的触发机制不一样，codex cli 可能识别特定的 skill 调用语法，claude cli 可能靠自然语言触发词。

我的习惯是在 prompt 开头就声明约束来源，比如：

使用 impeccable skill 的设计规范，生成一个用户仪表盘页面。 要求：包含侧边栏导航、顶部统计卡片区、下方数据表格。 所有间距、字号、颜色必须从 impeccable 的尺度系统和令牌中选取。

这样 agent 在生成前就知道要遵守哪套规则，而不是生成完了再让它改。事前约束的成本远低于事后修正。

注意：如果你不显式触发，agent 可能完全忽略 skill 的存在，按自己的默认习惯生成。这不是 bug，是 skill 机制的设计——它把是否启用规范的决定权留给你。

3.4 生成结果的验证方法

生成完之后别急着高兴，要验证约束是否真的生效了。最直接的方法是看代码里的数值。打开生成的 CSS 或样式文件，检查几个关键点：

• 所有padding和margin的值是否都是基数（比如 4 或 8）的倍数
• 字号是否落在阶梯上（12/14/16/20/24/32/48 这类）
• 颜色是否引用了语义令牌而不是硬编码色值
• 圆角是否在档位内（4/8/12/16/full）

如果发现padding: 18px这种不在基数上的值，说明约束没完全生效，可能是 skill 没触发，也可能是 agent 在某个环节绕过了规则。这时候可以追问一句“检查并修正所有不符合 impeccable 尺度的数值”，让它自查。

我实测下来，codex cli 对 skill 的遵守度比 claude cli 略高一些，可能是因为 codex 的 skill 机制更结构化。claude cli 在长对话里偶尔会“忘记”约束，需要中途提醒。这不是 impeccable 的问题，是 agent 本身的上下文管理问题。

4. 浏览器扩展形态：给已有页面做设计体检

4.1 扩展的安装与激活

浏览器扩展形态的安装比 CLI 简单得多。通常是从扩展市场安装，或者加载本地解压的扩展目录。安装后在浏览器工具栏会出现图标，点击激活。

激活后扩展一般有两种工作模式：实时扫描和手动扫描。实时扫描会在页面加载时自动分析 DOM，手动扫描需要你点一下按钮。我建议先用手动扫描，因为实时扫描在复杂页面上可能拖慢浏览器。

扩展激活后，打开一个 AI 生成的页面，点扫描。它会在页面上叠加一层标注，把违反规范的元素高亮出来。标注通常分等级：严重违规（比如颜色完全不在令牌里）、警告（比如间距不在基数上）、提示（比如可以优化的层级关系）。

4.2 扩展能查出哪些问题

我把扩展的检查项整理成了一张表，方便对照：

这张表基本覆盖了 AI 生成前端最常见的视觉问题。对比度那一项尤其有用，AI 经常生成对比度不足的文字，肉眼看着还行，但无障碍标准过不了。

4.3 从扫描结果到修正的闭环

扩展的价值不只是“发现问题”，更在于“给出修正”。扫描后，每个违规项通常会附带建议值。比如padding: 18px会建议改成16px或20px，取决于上下文。你可以逐条应用，也可以批量应用。

批量应用要谨慎。我踩过一次坑：批量把所有 18px 改成 16px，结果某个卡片的视觉平衡被破坏了，因为那个 18px 是刻意为之的。所以我的建议是先看建议，再决定是否应用，尤其是涉及布局关键位置的数值。

修正完成后，扩展一般支持导出修正后的样式，你可以把它合并回代码。这样就完成了“生成—审查—修正—回写”的闭环。

一个实用技巧：把扩展的扫描结果导出成 JSON，然后用脚本批量处理。对于有几十个页面的项目，手动一条条改是不现实的。导出后用脚本按规则映射，效率高很多。

5. 尺度系统与语义令牌的落地细节

5.1 尺度基数的选择：4 还是 8

尺度基数是整套系统的地基。常见选择是 4px 或 8px。选哪个不是拍脑袋，要看你的产品密度。

4px 基数适合信息密度高的产品，比如后台管理系统、数据仪表盘、开发者工具。这类产品元素多、间距小，4px 的粒度能做出更精细的区分。8px 基数适合信息密度低的产品，比如营销页、移动端应用、内容型网站。这类产品留白多，8px 的粒度足够，而且数值更整齐。

impeccable 默认可能给的是 4px 或 8px，但你可以根据项目调整。调整后要重新生成尺度阶梯，确保所有档位都是新基数的倍数。我一般会在项目启动时就定好，中途改成本很高。

5.2 字号阶梯的设计逻辑

字号阶梯不是随便列几个数。它要满足两个条件：相邻档位有可感知的差异，整体覆盖从注释到标题的范围。

一个常见的阶梯是：12 / 14 / 16 / 20 / 24 / 32 / 48。12 用于辅助注释，14 用于次要文字，16 用于正文，20 用于小标题，24 用于中标题，32 用于大标题，48 用于展示型标题。相邻档位的比例大致在 1.2 到 1.5 之间，视觉上能明显区分。

AI 生成时最容易犯的错是“中间档位太多”。它可能生成 15px、17px、18px 这种，看起来精细，实际上视觉上分不出来，反而显得杂乱。尺度系统的作用就是砍掉这些中间档，强制 AI 在有限的档位里选。

5.3 语义令牌的命名规范

语义令牌的命名要遵循“用途优先，色值其次”的原则。不要用blue-500、gray-100这种色值命名，要用primary、surface、border-subtle这种用途命名。

原因很简单：色值会变，用途不会。今天的主色是蓝色，明天可能换成紫色，但“主色”这个用途不变。用用途命名，换色时只改令牌定义，所有引用处自动生效。用色值命名，换色时你得全局搜索替换，容易漏。

一套基础的语义令牌大概包括：

• 背景类：background、surface、surface-raised、surface-overlay
• 文字类：text-primary、text-secondary、text-disabled、text-inverse
• 边框类：border-default、border-subtle、border-strong、border-focus
• 状态类：primary、primary-hover、primary-active、danger、success、warning

AI 生成时引用这些令牌，而不是硬编码色值。这样即使 AI 在多个地方生成样式，颜色也是一致的。

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

6.1 skill 装了但 agent 不认

这是最高频的问题。表现是：你明明装了 impeccable skill，也用了触发词，但 agent 生成的东西还是老样子，数值乱七八糟。

排查顺序是这样的。先确认 skill 目录位置对不对，agent 的 skill 搜索路径可能不止一个，你装的地方未必是它扫的地方。再确认清单文件格式对不对，JSON 格式错误会导致 skill 加载失败但 agent 不报错。然后确认 agent 版本支持 skill 机制，老版本可能压根没这功能。最后确认触发词是否匹配，不同 agent 的触发词识别逻辑不一样，有的靠关键词，有的靠特定语法。

我遇到过一次是清单文件里 skill 名称写错了，agent 扫到了但注册失败，静默忽略。改对名称后立刻生效。

6.2 约束在长对话中失效

claude cli 在长对话里容易“忘记”约束，生成到后面几轮就开始放飞。这不是 impeccable 的锅，是 agent 的上下文窗口问题。

应对方法有两个。一是缩短对话轮次，每生成一个独立模块就开新对话，别在一个对话里生成整个项目。二是中途重申约束，在 prompt 里再提一句“继续遵循 impeccable 规范”。实测重申一次能管好几轮。

6.3 扩展扫描结果误报

扩展扫描偶尔会误报，把一些合理的自定义值标成违规。比如某个动画的过渡时间、某个特殊组件的尺寸，这些本来就不该受尺度系统约束。

处理方法是给扩展加白名单。大多数扩展支持在配置里排除特定选择器或特定属性。把那些确实需要自定义的地方加进白名单，扫描结果就干净了。别为了追求“零违规”把合理的自定义也改掉，那是本末倒置。

6.4 生成结果“规范但呆板”

这是另一个极端。约束太严，AI 生成的东西虽然一致，但缺乏变化，看起来像模板套出来的。

我的经验是：约束管的是基础层，创意管的是表现层。尺度、令牌、结构这些基础层要严格约束，但配色方案、插画风格、动效这些表现层可以放开。impeccable 的约束主要作用在基础层，表现层它管得不多。如果你觉得呆板，问题可能出在 prompt 里没给表现层的发挥空间，而不是约束太严。

6.5 常见问题速查表

7. 我个人的使用体会与几个实用建议

用了一段时间 impeccable，最大的感受是：它把“审美”这个模糊的东西，拆成了可执行、可检查、可修正的规则。以前让 AI 生成前端，好不好看全凭运气；现在至少有个底线，出来的东西不会太离谱。

几个实用建议。第一，项目启动时就定好尺度系统和令牌，别等生成了一堆页面再回头统一，成本高十倍。第二，CLI 和扩展配合用，CLI 管生成，扩展管审查，两条腿走路比单用一条稳。第三，别追求零违规，约束是服务产品的，不是产品服务约束，该自定义的地方就自定义。第四，把扫描结果导出成数据，用脚本批量处理，比手动改快得多。

还有一个我最近在试的玩法：把 impeccable 的令牌系统导出成一份设计规范文档，直接给团队里的设计师和前端看。这样人和 AI 用的是同一套规则，协作时少很多扯皮。这个方向后续还可以扩展，比如把令牌同步到 Figma 变量、同步到 CSS 变量、同步到 Tailwind 配置，让规范真正落到工程的每个环节。

踩过的坑也不少。最亏的一次是没确认 agent 版本就装 skill，折腾了一小时才发现是版本不支持。所以再强调一遍：先确认 agent 本身跑得通，再上 skill。这个顺序反了，后面全是无用功。