1. 从"impeccable"说起：一个被低估的前端设计关键词
第一次看到"impeccable"这个词，是在一个前端项目的代码评审里。当时有个同事在 PR 描述里写了一句话："The spacing here is not impeccable." 我盯着这个词看了半天——它不像"beautiful"那么主观，也不像"clean"那么笼统，它指向的是一种无可挑剔的精确感：像素对齐、间距一致、状态完整、边界情况都考虑到了。
后来我慢慢意识到，"impeccable"在前端设计语境里其实是一个非常有分量的标准。它不只是"好看"，而是"挑不出毛病"。这两者之间的差距，恰恰是普通开发者和资深前端之间的分水岭。一个按钮能点、能跳转，这叫"能用"；一个按钮在 hover、focus、active、disabled、loading 五种状态下都有恰当的视觉反馈，间距和周围元素严格对齐，暗色模式下对比度达标，键盘 Tab 聚焦时轮廓清晰可见——这才叫 impeccable。
而当下这个时间点特别有意思：AI coding agents 正在大规模进入前端开发流程。CLI 工具、浏览器扩展、代码生成模型，这些东西让"写出能跑的代码"变得前所未有的容易。但"能跑"和"impeccable"之间的距离，反而被拉大了。因为 AI 生成代码的默认水平，往往停留在"功能正确"这一层，细节打磨几乎全靠人来兜底。
所以这篇内容我想聊的，不是某个具体框架的 API，而是一套围绕"impeccable"这个标准建立起来的前端设计工作流——怎么用 CLI 工具和浏览器扩展把 AI coding agents 的输出，从"能用"推到"挑不出毛病"。适合已经在前端岗位上、或者正在用 AI 辅助写前端代码的开发者看。如果你只是想让页面跑起来，这篇可能有点"较真"；但如果你在意交付质量，下面这些经验应该能帮你省不少返工时间。
2. 为什么"impeccable"值得单独拿出来做标准
2.1 前端设计的三个层次：能用、好用、挑不出毛病
我习惯把前端交付质量分成三层。第一层是能用：功能跑通，数据能渲染，点击有响应。这一层现在 AI 基本能独立完成，你给个需求描述，codex cli 或者类似的 agent 就能吐出一版可运行的代码。第二层是好用：交互流畅，加载有反馈，错误有提示，移动端不崩。这一层 AI 能完成七八成，剩下的靠人补。第三层就是impeccable：所有边界情况都覆盖，视觉细节经得起放大镜看，代码结构让下一个接手的人挑不出刺。
大部分团队卡在第二层到第三层之间。不是不知道第三层更好，而是投入产出比看起来不划算——多花两小时调间距，用户真的能感知到吗？我的经验是：单个细节用户感知不到，但几十个细节叠加起来，用户会说"这个产品用起来很舒服"，虽然他说不出为什么。这就是 impeccable 的价值，它是一种累积性的体验优势。
2.2 AI 生成代码的"默认粗糙度"从哪来
用 AI coding agents 写前端，你会发现一个规律：它生成的代码在"主干逻辑"上往往没问题，但在"边缘细节"上系统性偏弱。我总结下来有三个来源。
第一是训练数据的分布偏差。网上大量前端代码示例本身就是"能跑就行"的水平，AI 学到的默认风格就是这种。第二是缺乏运行时反馈。AI 写代码时看不到真实渲染效果，它不知道那个 margin 在 1440px 屏幕上看起来是 16px 还是 17px。第三是状态覆盖不全。人写代码时会想"如果这里加载失败呢"，AI 默认只处理 happy path。
理解了这三点，你就知道为什么需要一套外部工具链来补足——CLI 负责在代码层面做检查和批量修正，浏览器扩展负责在渲染层面做实时验证。这两者配合，才能把 AI 的输出拉到 impeccable 的水平。
2.3 为什么现在是把这套流程固化下来的好时机
CLI 工具生态这两年成熟得很快。以前你要做代码规范检查，得自己配 ESLint、Stylelint、Prettier 一堆东西，规则还得自己写。现在很多 CLI 工具已经内置了前端设计相关的检查能力，比如间距一致性、颜色对比度、响应式断点覆盖。浏览器扩展这边也一样，以前调样式靠 DevTools 手动看，现在有扩展能自动标注出"这个元素的间距和设计系统不一致"。
更重要的是，AI coding agents 已经能接受 CLI 的输出作为反馈。你可以让 agent 生成代码，然后用 CLI 跑一遍检查，把检查结果喂回给 agent 让它修正。这个生成-检查-修正的闭环，是把 AI 输出推向 impeccable 的关键机制。下面我会详细拆这套流程怎么搭。
3. 工具链选型：CLI 与浏览器扩展怎么配
3.1 CLI 工具在前端设计流程中的定位
CLI 工具在这套流程里扮演的是代码层守门员的角色。它不关心渲染出来长什么样，它关心的是代码里有没有埋下隐患。比如：硬编码的颜色值有没有走设计 token、间距用的是不是 4 的倍数、有没有遗漏的:focus-visible样式、媒体查询断点是不是和设计系统一致。
我目前用的组合是这样的：一个负责代码风格和基础规范的 CLI（类似 codex cli 这种能理解项目上下文的），一个负责设计 token 一致性的检查脚本，再加一个负责可访问性扫描的。这三个各管一摊，跑完一轮基本能把代码层的问题筛干净。
选 CLI 工具时我踩过的坑是：不要追求一个工具解决所有问题。有些工具号称能检查一切，结果每项都做得不深。宁可三个小工具各司其职，组合起来更灵活。另外要注意 CLI 的输出格式，最好是结构化的（JSON 或类似格式），这样方便喂给 AI agent 做后续修正。
3.2 浏览器扩展负责的"渲染层验证"
CLI 检查完代码，接下来要验证真实渲染效果。这一步浏览器扩展不可替代。我常用的几类扩展：一类是做视觉回归的，能对比当前渲染和基线截图的差异；一类是做间距标注的，鼠标悬停就能看到元素的实际 margin/padding 值；还有一类是做对比度检查的，实时标出不符合 WCAG 标准的文字。
这里有个实操心得：视觉回归扩展一定要在固定视口尺寸下用。我一开始没注意，在不同窗口大小下截图对比，结果全是误报。后来固定成 1440x900 和 375x812 两个尺寸，误报率直接降下来了。另外，动态内容（比如时间戳、随机头像）要在对比时排除掉，否则每次都有差异。
3.3 两者如何与 AI coding agents 形成闭环
闭环的逻辑是这样的：AI agent 生成或修改代码 → CLI 跑代码层检查 → 浏览器扩展跑渲染层验证 → 把两层的问题汇总成结构化反馈 → 喂回给 AI agent → agent 修正 → 再跑一遍。这个循环通常跑两到三轮，代码质量就能从"能用"推到接近 impeccable。
关键点在于反馈的结构化。如果你只是把 CLI 的原始输出丢给 agent，它可能抓不住重点。我一般会把问题按严重程度分级：阻断性问题（必须修）、建议性问题（最好修）、风格问题（可修可不修）。然后只把前两类喂给 agent，避免它在无关紧要的细节上浪费 token。
提示：这个闭环里，人的角色从"写代码"变成了"定义标准和审核结果"。标准定得越清晰，闭环跑得越顺。所以前期花时间把设计 token、间距规则、状态清单整理成文档，是非常值得的投入。
4. 核心细节：把"挑不出毛病"拆成可执行的检查项
4.1 间距与对齐：4px 网格是底线不是上限
间距是前端设计里最容易被忽视、又最影响观感的东西。我的做法是强制 4px 网格：所有 margin、padding、gap 的值必须是 4 的倍数。为什么是 4 不是 8？因为 8 网格在移动端太粗，很多紧凑布局需要 4px 的粒度。4px 网格既能保证一致性，又留了足够的灵活度。
在 CLI 层面，我会写一个脚本扫描所有样式文件，把非 4 倍数的间距值揪出来。这个脚本很简单，正则匹配margin|padding|gap后面的数值，然后做取模判断。跑一遍下来，AI 生成的代码里通常有 10% 到 20% 的间距值不符合网格，修正后整体观感会明显提升。
对齐这块，浏览器扩展帮大忙。我用的扩展能画出元素的边界框，一眼就能看出哪些元素没对齐。常见的坑是：图标和文字基线不对齐、卡片内边距左右不一致、表单标签和输入框顶部没对齐。这些在代码里看不出来，渲染出来才明显。
4.2 状态覆盖：五种状态一个都不能少
交互元素的状态覆盖是 impeccable 的硬指标。我要求每个可交互元素至少覆盖五种状态：default、hover、focus-visible、active、disabled。如果涉及异步操作，还要加loading；如果涉及数据展示，还要加empty和error。
AI 生成代码时，默认只给 default 和 hover，偶尔给个 active。focus-visible 经常被漏掉，这是可访问性的大问题——键盘用户根本不知道焦点在哪。我的做法是在 CLI 检查里加一条规则：所有button、a、input选择器必须出现:focus-visible样式，否则报错。
loading 状态也常被忽略。一个提交按钮，点击后如果没有任何反馈，用户会以为没点上，然后狂点。加个 loading 状态，按钮变灰加个转圈，体验立刻不一样。这个细节 AI 不会主动加，得你在 prompt 里明确要求，或者用 CLI 检查兜底。
4.3 颜色与对比度：暗色模式是照妖镜
颜色这块，我强烈建议从一开始就用设计 token，不要在代码里硬编码色值。硬编码的后果是：改主题时你得全局搜索替换，漏一个就出问题。用 token 的话，改一处全局生效。
对比度检查是浏览器扩展的强项。WCAG AA 标准要求正文文字对比度至少 4.5:1，大号文字至少 3:1。我见过太多项目正文对比度只有 3:1 出头，在亮屏环境下看着还行，一到户外或者暗色模式就糊成一片。扩展能实时算出对比度值，不达标就标红。
暗色模式是检验颜色系统的照妖镜。很多项目亮色模式做得不错，一切到暗色就露馅：阴影看不见了、边框和背景融在一起、品牌色在深色背景上刺眼。我的做法是暗色模式单独定义一套 token，不要用亮色的 token 做反转，因为反转出来的颜色往往不协调。
4.4 响应式断点：不是加了媒体查询就叫响应式
响应式的常见误区是：加了几个媒体查询就以为搞定了。实际上 impeccable 的响应式要求是每个断点下都没有布局崩坏。我一般会检查这几个断点：375（手机）、768（平板竖）、1024（平板横）、1440（桌面）、1920（大屏）。
检查方法是浏览器扩展的响应式预览功能，能同时看多个断点的渲染效果。重点看：文字有没有溢出容器、图片有没有变形、导航有没有折叠、表格有没有横向滚动条。AI 生成的响应式代码经常在中间断点（768 到 1024 之间）出问题，因为训练数据里这个区间的示例比较少。
注意：响应式检查一定要用真实内容，不要用 Lorem ipsum。真实内容的长度差异很大，短文案在窄屏下没问题，长文案可能就溢出了。我习惯用项目里最长的那个标题和描述来做测试。
5. 实操流程：从 AI 生成到 impeccable 的完整闭环
5.1 第一步：定义项目的设计约束文档
在让 AI 写任何代码之前，先花半小时写一份设计约束文档。这份文档不需要很长，但要把关键规则列清楚。我的模板包含这几块：间距网格（4px）、颜色 token 列表、字体层级（h1 到 body 的字号和行高）、断点定义、状态清单、圆角规范、阴影规范。
这份文档的作用是给 AI 一个明确的边界。你可以在 prompt 里直接引用它，比如"按照 DESIGN.md 里的间距规则生成这个卡片组件"。实测下来，有约束文档的情况下，AI 生成代码的首次合格率能从 60% 提到 80% 左右。
文档格式我推荐用 Markdown，放在项目根目录。这样 CLI 工具和 AI agent 都能读到。如果项目用 openspec cli 这类工具管理规范，也可以把约束写进 spec 文件里，效果类似。
5.2 第二步：用 CLI 生成初始代码并跑第一轮检查
让 AI agent 生成代码后，先别急着看渲染效果，跑一轮 CLI 检查。我通常跑三个命令：代码风格检查、设计 token 一致性检查、可访问性扫描。这三个命令可以写成一个 npm script，一条命令跑完。
第一轮检查的结果通常比较惨，会有几十条警告。别慌，这是正常的。把结果按严重程度排序，先修阻断性的。我一般会把 CLI 输出重定向到一个文件，然后用脚本解析成结构化数据，再喂给 AI agent 让它批量修正。
这里有个技巧：分批修正，不要一次性全丢给 agent。一次修 5 到 10 个问题，agent 的准确率最高。一次丢 50 个问题，它容易顾此失彼，修了新的坏了旧的。
5.3 第三步：浏览器扩展做渲染层验证
CLI 检查通过后，打开浏览器，用扩展做渲染层验证。我按这个顺序看：先看整体布局有没有崩，再看间距对齐，再看状态覆盖，最后看对比度和响应式。
视觉回归扩展在这一步特别有用。如果你有设计稿，可以把设计稿截图和实际渲染做对比，扩展会高亮出差异区域。没有设计稿的话，就靠肉眼加间距标注扩展，逐个检查关键元素。
这一步发现的问题，往往 CLI 检查不出来。比如：两个元素在代码里间距都是 16px，但渲染出来看着不一样，因为其中一个有额外的 line-height 影响。这种问题只能靠渲染层验证发现。
5.4 第四步：把问题反馈给 AI agent 做修正
渲染层的问题整理成清单后，连同 CLI 的剩余问题一起喂给 AI agent。反馈的格式我建议用这样的结构：问题描述、期望结果、相关文件路径、参考示例（如果有）。结构越清晰，agent 修得越准。
修正完再跑一遍 CLI 和渲染层验证。通常两到三轮就能收敛。如果某个问题反复修不好，可能是你的约束文档没写清楚，或者 agent 理解有偏差，这时候需要人工介入，手动改一下，然后把正确的做法补充到约束文档里，避免下次再犯。
5.5 第五步：固化检查流程为可复用的脚本
跑通一遍后，把整个流程固化成脚本。我的做法是写一个check-impeccable.sh，里面依次跑 CLI 检查、启动本地服务、跑视觉回归、汇总结果。这样每次改完代码，一条命令就能跑完所有检查。
这个脚本还可以集成到 CI 里。每次提交代码自动跑，不通过就阻断合并。这样 impeccable 就从"靠自觉"变成了"靠流程保证"。团队里新人接手时，也不用反复强调规范，CI 会告诉他哪里不达标。
6. 常见问题与排查技巧实录
6.1 AI 生成的代码总是漏掉 focus 状态怎么办
这是最高频的问题。我的解决办法是在约束文档里把 focus-visible 列为强制项，并且在 CLI 检查里加硬性规则。另外在 prompt 里明确写"所有可交互元素必须包含 :focus-visible 样式，使用 2px 实线轮廓，偏移 2px"。
如果 agent 还是漏，可以在项目里建一个基础样式文件，全局定义:focus-visible的默认样式，这样即使组件没单独写，也有兜底。全局样式大概长这样：
:focus-visible { outline: 2px solid var(--color-focus); outline-offset: 2px; }这样至少保证了可访问性底线，组件层面再按需覆盖。
6.2 间距检查脚本误报太多怎么调
间距检查脚本的误报主要来自两个地方：一是负值 margin（比如margin-top: -4px），二是百分比或 calc 计算的值。我的处理方式是：负值 margin 单独列出来人工审核，因为负 margin 往往是刻意为之；百分比和 calc 值跳过检查，因为它们的实际渲染值取决于上下文。
另外，line-height和letter-spacing不要纳入间距检查，它们不属于网格体系。我一开始把 line-height 也纳入检查，结果误报一大堆，后来单独排除掉就清爽了。
6.3 暗色模式下颜色对比度不达标怎么系统解决
暗色模式的对比度问题，根源通常是直接用了亮色模式的色值做反转。正确的做法是为暗色模式单独定义一套语义化 token。比如亮色模式下--color-text-primary是#1a1a1a，暗色模式下不是简单的#e5e5e5，而是要根据背景色重新计算对比度。
我一般会用对比度计算工具，把暗色背景和候选文字色输进去，找到满足 4.5:1 的最接近色值。这个过程有点繁琐，但做一次就能一劳永逸。建议把暗色 token 也写进约束文档，让 AI 生成代码时直接引用。
6.4 视觉回归测试总是有差异怎么稳定下来
视觉回归不稳定的原因通常有三个：动态内容、字体渲染差异、动画未结束。动态内容要在截图前屏蔽掉，比如把时间戳替换成固定值。字体渲染差异在不同操作系统上确实存在，解决办法是在 CI 里用容器化的浏览器，保证渲染环境一致。动画未结束的话，截图前加个等待，或者禁用动画。
我踩过最坑的一次是：视觉回归在本地跑没问题，到 CI 就挂。排查半天发现是 CI 环境的字体和本地不一样，导致文字宽度有细微差异。后来统一用容器化浏览器就解决了。
6.5 问题速查表
| 问题现象 | 可能原因 | 排查方向 | 解决方式 |
|---|---|---|---|
| 间距看着不齐 | 非 4px 倍数或 line-height 干扰 | 用间距标注扩展逐个检查 | 统一到 4px 网格，检查 line-height |
| 键盘 Tab 看不到焦点 | 缺少 focus-visible 样式 | 全局搜索:focus-visible | 加全局兜底样式 |
| 暗色模式文字发糊 | 对比度不足 | 用对比度扩展实测 | 重新计算暗色 token |
| 中间断点布局崩 | 媒体查询覆盖不全 | 多断点同时预览 | 补充 768-1024 区间样式 |
| 视觉回归误报 | 动态内容或环境差异 | 检查截图差异区域 | 屏蔽动态内容，容器化浏览器 |
| AI 反复修不好同一问题 | 约束文档不清晰 | 检查文档对应条目 | 补充正确示例到文档 |
7. 我在这套流程里踩过的坑和总结的经验
7.1 不要一开始就追求全自动化
我最初的想法是把整个流程全自动化：AI 生成、CLI 检查、自动修正、自动提交，人完全不介入。跑了两周发现不行。问题在于有些判断需要人的审美和经验，比如"这个间距虽然符合 4px 网格，但视觉上就是不舒服"，这种 AI 判断不了。
后来我调整成半自动化：机械性的检查（间距、对比度、状态覆盖）全自动，审美性的判断（视觉平衡、层次感）人工介入。这样效率和质量都兼顾了。全自动适合规范明确的部分，人工适合需要判断的部分。
7.2 约束文档要持续迭代
约束文档不是写一次就完事的。每次人工修正了 AI 的问题，都要回头想想：这个问题能不能写进文档，让下次不再犯？我现在的文档已经迭代了十几版，从最初的一页纸变成了现在的五页，但 AI 的首次合格率也从 60% 提到了 85% 以上。
文档迭代的关键是记录具体案例。不要只写"间距要用 4px 网格"，要写"卡片内边距用 16px，卡片间距用 24px，表单元素间距用 12px"。具体的数值比抽象的原则更有指导性。
7.3 CLI 和浏览器扩展的边界要分清
CLI 能查的，浏览器扩展不用重复查；浏览器扩展能查的，CLI 也别硬上。我见过有人用 CLI 去检查渲染效果，写一堆复杂的 AST 分析，结果还不如浏览器扩展点一下来得准。工具各有所长，别让 CLI 干它不擅长的活。
我的分工是：CLI 管代码层（语法、token、结构），浏览器扩展管渲染层（视觉、交互、响应式）。两者有少量重叠（比如对比度），重叠部分以浏览器扩展为准，因为它是实测值。
7.4 团队协作时标准要统一
一个人用这套流程，标准在自己脑子里。团队用的话，标准必须写下来、统一起来。我们团队的做法是把约束文档放进项目仓库，新人入职第一件事就是读它。CI 里跑检查脚本，不通过不让合并。这样标准就从"口头约定"变成了"流程强制"。
统一标准还有个好处：代码评审时不用再争论"这个间距该用 16 还是 20"，因为文档里写清楚了。评审的精力可以放在更有价值的地方，比如交互逻辑、边界情况。
7.5 最后分享一个提效小技巧
如果你也在用 AI coding agents 写前端，可以试试在 prompt 末尾加一句："生成后请自查间距是否符合 4px 网格、所有交互元素是否包含 focus-visible 状态、颜色是否使用了设计 token。" 这句话能让 AI 在生成阶段就自我检查一遍，减少后续修正的工作量。我实测下来，加了这句话之后，CLI 检查的警告数量平均减少了三成。
这个技巧的本质是把检查前置。与其生成完再检查再修正，不如让 AI 在生成时就带着检查意识。虽然不能完全替代外部检查，但能省不少来回。后续如果 agent 的能力再强一些，也许能把更多检查项前置到生成阶段，那时候 impeccable 的门槛就更低了。
