AI coding agents如何生成impeccable前端设计：CLI与browser extension实战

1. 从"impeccable"说起：一个被低估的前端设计关键词

第一次看到"impeccable"这个词，是在翻一个海外前端团队的工程博客时。他们用这个词来形容一套AI coding agents产出的前端界面——不是"能用"，不是"好看"，而是"挑不出毛病"。这个词在中文语境里没有特别精准的对应，直译是"无可挑剔的"，但放在前端设计语境下，它其实指向一种很具体的东西：视觉上干净、交互上顺滑、代码上可维护，三者同时成立。

这两年AI coding agents的爆发，让"生成一个页面"这件事变得极其廉价。你随便给一个CLI工具丢一句prompt，它就能吐出一个能跑的React组件。但问题也随之而来：生成的东西越来越多，真正"impeccable"的却越来越少。大部分AI产出的前端代码，打开浏览器一看，间距是乱的，颜色是脏的，响应式是崩的，状态管理是缺失的。它能跑，但你不敢把它交给用户。

所以当我看到"impeccable"这个标题，配合AI coding agents、frontend design、CLI、browser extension这几个热搜词时，我大概能猜到它想解决的是什么问题：如何让AI coding agents产出的前端设计，从"能跑"提升到"无可挑剔"。这不是一个纯技术问题，而是一个工程审美和流程设计的问题。

这篇文章适合三类人看：一是正在用codex cli、zcode cli这类工具做前端开发的工程师，想知道怎么把产出质量拉上去；二是做browser extension或者CLI工具的产品同学，想理解前端设计自动化的边界在哪；三是对AI coding agents感兴趣但还没上手的人，想通过一个具体场景理解这类工具的真实能力。我会尽量把原理、操作、坑点都讲透，让你看完能直接抄作业。

2. 为什么AI生成的前端总是"差一口气"

2.1 从"能跑"到"impeccable"的鸿沟在哪

先说一个我自己的观察。我用codex cli生成过大概几十个前端页面，从landing page到dashboard都有。如果只看功能，成功率其实挺高的，80%以上能一次跑通。但如果用"impeccable"的标准去卡，能过的不到两成。差距主要出在三个地方。

第一个是视觉节奏。AI生成的页面，元素之间的间距往往是"均匀但无意义"的。它会给每个section都加一样的padding，给每个卡片都加一样的margin，结果就是整个页面像被压路机碾过，没有呼吸感。人类设计师会做的是：标题和正文之间用大间距，正文和辅助文字之间用小间距，形成视觉层级。这个层级感，AI默认是不懂的。

第二个是状态完整性。AI生成的组件，通常只处理happy path。按钮的hover态、focus态、disabled态、loading态，大概率是缺失的。表单的error态、success态、空态，也经常被忽略。你点一下按钮，它没有任何反馈，用户就会怀疑是不是没点上。这种细节，是"能跑"和"impeccable"之间最明显的分界线。

第三个是响应式断裂。AI生成的布局，在桌面端看着还行，一到移动端就崩。要么是文字溢出，要么是元素重叠，要么是横向滚动条。原因是它用的断点策略太粗暴，或者根本没考虑容器查询。这个问题在dashboard类页面尤其严重，因为表格和图表在窄屏下的处理非常考验设计功力。

2.2 AI coding agents的"审美盲区"从哪来

要理解为什么AI做不好这些，得先理解它的工作方式。不管是codex cli还是zcode cli，底层都是大模型在根据你的prompt生成代码。它的训练数据里当然有大量优秀的前端代码，但它学到的更多是"语法模式"和"组件结构"，而不是"设计意图"。

打个比方，这就像一个背了一万首诗的机器人，你让它写一首，它能写出格律工整、用词正确的诗，但它不知道这首诗要表达什么情绪，也不知道在哪个字上该重读。前端设计也是一样，AI知道display: flex怎么用，知道gap: 16px是常见值，但它不知道在这个具体场景下，16px是不是对的，gap该不该是24px。

更关键的是，AI没有"看"的能力。它生成代码的时候，脑子里没有渲染后的画面。它不知道这个颜色在深色模式下会不会刺眼，不知道这个字号在Retina屏上会不会发虚，不知道这个动画曲线会不会让人觉得卡顿。这些都需要"看到"才能判断，而AI看不到。

所以"impeccable"这个目标，本质上是要给AI coding agents补上"视觉判断"这一环。补的方式有两种：一种是在prompt里注入设计规范，让它按规则来；另一种是用browser extension或者截图工具，把渲染结果喂回去让它自己改。前者是预防，后者是修正，实际用起来通常要结合。

2.3 为什么CLI和browser extension是关键词

热搜词里出现了CLI和browser extension，这不是偶然的。CLI是AI coding agents的主要交互方式，codex cli、zcode cli、gitlab cli这些工具，都是通过命令行来触发代码生成的。CLI的好处是快、可脚本化、容易集成到CI流程里。你可以在终端里一句话生成一个组件，然后直接跑测试。

但CLI有个天然缺陷：它看不到渲染结果。你在终端里只能看到代码，看不到页面。所以browser extension就补上了这一环。它可以在浏览器里实时检查AI生成的页面，把视觉问题、可访问性问题、性能问题抓出来，再反馈给CLI去修。这个"CLI生成 + extension检查"的闭环，是目前做impeccable前端比较靠谱的路径。

我实测下来，这个闭环如果搭得好，能把AI生成前端的可用率从两成提到六成以上。剩下的四成，要么是需求本身太模糊，要么是设计规范没定义清楚，要么是AI确实理解不了某些复杂的交互逻辑。但六成已经是很可观的提升了，至少能帮你省掉大量重复劳动。

3. 搭建impeccable前端工作流的核心组件

3.1 工具选型：CLI、extension和设计规范的三件套

要把这套流程跑起来，你需要三样东西：一个能生成代码的CLI工具、一个能检查视觉的browser extension、一份能约束AI的设计规范。这三样缺一不可，而且它们之间要有明确的接口。

CLI工具的选择上，codex cli是目前比较成熟的一个。它的优势是prompt理解能力强，能处理比较复杂的组件需求，而且支持/compact、/model、/resume这些命令，方便你在长会话里管理上下文。zcode cli和trae cli也各有特点，前者对中文prompt的适配更好，后者在集成IDE方面做得更顺。如果你团队已经在用gitlab，gitlab cli安装后也能直接调用，省去切换成本。

browser extension这块，我推荐用能同时做视觉回归和可访问性检查的。视觉回归的核心是截图对比，它能告诉你这次生成的页面和上次比，哪些像素变了。可访问性检查的核心是axe-core这类规则引擎，它能抓出对比度不足、缺少alt、焦点顺序错乱这些问题。这两个能力合在一起，基本能覆盖"impeccable"的大部分硬性要求。

设计规范是最容易被忽略但最重要的一环。你不能指望AI自己悟出你的设计系统，你得把它写成AI能读的格式。我通常会用一份design-tokens.json加一份rules.md。前者定义颜色、间距、字号、圆角、阴影这些原子值，后者定义使用规则，比如"卡片内间距用16px，卡片间间距用24px"、"主按钮用primary色，次按钮用outline样式"。这份规范越具体，AI的产出就越稳定。

3.2 设计规范的"可执行化"：从Figma到JSON

很多人以为设计规范就是Figma里那套样式，其实不是。Figma里的样式是给人看的，AI读不懂。你需要把它转成结构化的、可被程序消费的格式。这个过程我称之为"可执行化"。

具体怎么做？第一步，把Figma里的color styles导出成JSON。大部分设计工具都支持这个操作，导出后你会得到类似{"primary": "#3B82F6", "surface": "#FFFFFF"}这样的结构。第二步，把间距、字号、圆角这些也整理成同样的格式。第三步，也是最关键的一步，写一份规则文件，把"什么时候用哪个token"讲清楚。

举个例子，光有{"spacing": {"sm": 8, "md": 16, "lg": 24}}是不够的，AI不知道什么时候用sm什么时候用lg。你得补上规则："表单字段之间的垂直间距用md，表单和提交按钮之间用lg，按钮内部的水平padding用md"。这种规则写起来琐碎，但写一次能用很久，而且能显著降低AI的随机性。

我自己的做法是维护一个rules.md，里面按组件类型分节。每个组件下面写清楚它的结构、状态、间距规则、颜色规则。这份文件我会在每次用CLI生成代码时，作为context一起喂给AI。实测下来，有这份规则和没有，产出质量差距非常大。没有规则的时候，AI生成的按钮padding是随机的，有时候8px有时候20px；有了规则之后，基本能稳定在规范值上。

3.3 检查闭环：extension如何把视觉问题喂回CLI

光有生成还不够，你得有检查。browser extension在这里的角色，是把"人眼能看出来的问题"转成"AI能读懂的反馈"。

具体流程是这样的：CLI生成代码后，你在本地跑起来，用extension打开页面。extension会自动做几件事：截图当前页面、跑可访问性规则、检查响应式断点、测量元素间距。然后它把这些结果整理成一份报告，格式是结构化的JSON或者Markdown。这份报告里会写清楚"哪个元素在哪个断点下溢出了"、"哪个按钮的对比度只有3.2:1低于4.5:1的标准"、"哪个卡片的间距是12px但规范要求16px"。

拿到这份报告后，你把它贴回CLI，让AI根据报告修改代码。这里有个技巧：不要一次性把所有问题都丢回去，那样AI会改乱。我通常按优先级分批，先修布局和响应式，再修状态和交互，最后修视觉细节。每批改完重新检查，确认没问题再进下一批。

这个闭环跑顺了之后，你会发现AI的产出质量在迭代中快速收敛。第一版可能只有六十分，改两轮就能到八十五分，改三轮基本能到九十分以上。剩下的十分，通常是需要人类设计师介入的创意部分，那部分AI确实替代不了，也没必要替代。

4. 实操：用codex cli生成一个impeccable的卡片组件

4.1 环境准备与CLI安装要点

在开始之前，先把环境搭好。codex cli的安装方式取决于你的系统，macOS和Linux下通常是通过包管理器或者官方脚本，Windows下建议用WSL。安装完成后，你需要配置API key和默认模型。这里有个细节：不同模型对前端代码的理解能力差异很大，建议先用/model命令看看有哪些可选，然后选一个在前端任务上表现好的。

安装过程中容易踩的坑有两个。一是权限问题，CLI需要读写你的项目目录，如果权限没给够，生成的文件会写不进去。二是网络问题，如果你的环境需要走代理才能访问模型服务，记得在CLI的配置里设好，否则会一直超时。这两个问题看起来简单，但实际卡住过不少人。

装好之后，建议先跑一个最小用例验证。比如让它生成一个"hello world"的React组件，看看能不能正常输出。这一步过了，再进正式任务。另外，codex cli的/compact命令很有用，它能把长会话的上下文压缩，避免token超限。如果你要生成一个复杂组件，会话会很长，记得适时用/compact。

4.2 写一份AI能读懂的prompt

prompt的质量直接决定产出质量。我见过很多人写prompt就一句话："帮我生成一个卡片组件"。这种prompt出来的东西，基本没法用。好的prompt应该包含四部分：组件描述、设计规范、状态要求、技术约束。

组件描述要讲清楚这个卡片是干什么的，包含哪些元素。比如"一个产品卡片，包含产品图、标题、描述、价格、加入购物车按钮"。设计规范要引用你的design tokens，比如"标题用heading-md字号，描述用body-sm，价格用primary色加粗"。状态要求要列全，比如"按钮需要default、hover、active、disabled、loading五种状态"。技术约束要说明框架和依赖，比如"用React + TypeScript，样式用CSS Modules，不要引入额外UI库"。

我实测下来，prompt里每多一条明确约束，产出质量就提升一截。但也不能太多，太多AI会顾此失彼。我的经验是控制在15到20条约束之间，按重要性排序，把最关键的放前面。另外，把rules.md的内容直接贴进prompt，比让AI自己去读文件更可靠，因为有些CLI工具对文件读取的支持不稳定。

4.3 生成、检查、迭代的完整流程

现在进入实操。假设我们要生成一个产品卡片组件，流程分四步。

第一步，生成初版。在CLI里输入prompt，等它输出代码。输出后先别急着看细节，先跑起来看整体。这一步主要看结构对不对，元素全不全。

第二步，用extension检查。打开页面，跑一遍检查。重点关注三类问题：布局问题（溢出、重叠、错位）、状态问题（hover、focus、disabled是否正常）、可访问性问题（对比度、alt、焦点顺序）。把问题记下来，按优先级排序。

第三步，反馈修改。把问题整理成清单，贴回CLI。这里要注意，反馈要具体，不要说"按钮不好看"，要说"按钮的hover态背景色和default态对比度不足，建议加深10%"。AI对具体指令的响应远好于模糊指令。

第四步，重复第二步和第三步，直到检查通过。通常两到三轮就能收敛。收敛后，把最终代码提交，同时把这次用到的prompt和规则更新到你的规范文件里，下次生成类似组件时可以直接复用。

这个流程跑一遍大概需要20到30分钟，比人手写快不了太多，但胜在稳定和可复用。当你需要生成十个类似组件时，边际成本会急剧下降，因为prompt和规则都是现成的。

4.4 关键参数与代码片段解析

生成过程中有几个参数值得特别关注。第一个是间距的基准值。我建议用8px作为基准，所有间距都是8的倍数。这个规则简单，AI容易遵守，而且视觉上比较协调。第二个是字号阶梯。我通常用12、14、16、20、24、32这六档，覆盖从辅助文字到主标题的需求。第三个是圆角。卡片用12px，按钮用8px，输入框用6px，这个层级能形成微妙的视觉区分。

下面是一段生成后的卡片组件代码片段，我做了简化：

interface ProductCardProps { image: string; title: string; description: string; price: number; onAddToCart: () => void; loading?: boolean; } export function ProductCard({ image, title, description, price, onAddToCart, loading }: ProductCardProps) { return ( <article className={styles.card}> <img src={image} alt={title} className={styles.image} /> <div className={styles.body}> <h3 className={styles.title}>{title}</h3> <p className={styles.description}>{description}</p> <div className={styles.footer}> <span className={styles.price}>${price.toFixed(2)}</span> <button className={styles.button} onClick={onAddToCart} disabled={loading} aria-busy={loading} > {loading ? 'Adding...' : 'Add to Cart'} </button> </div> </div> </article> ); }

这段代码里有几个impeccable的细节：alt用了title而不是空字符串，保证可访问性；aria-busy标记了loading状态，屏幕阅读器能感知；disabled和loading联动，避免重复提交。这些细节，如果prompt里不写，AI大概率不会主动加。

对应的CSS里，间距全部用token，颜色全部用变量，hover和focus态都有定义。这些看起来是小事，但正是这些小事堆起来，才让一个组件从"能跑"变成"impeccable"。

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

5.1 AI生成的布局在移动端崩了怎么办

这是最高频的问题。表现是桌面端正常，一到窄屏就出现横向滚动条或者元素重叠。排查思路分三步。

第一步，先确认是不是viewport meta没写。很多AI生成的HTML会漏掉<meta name="viewport" content="width=device-width, initial-scale=1">，这一漏，移动端就会按桌面宽度渲染，然后缩小，看起来就是"崩了"。加上这行，一半的问题能解决。

第二步，检查有没有固定宽度。AI很喜欢写width: 320px这种硬编码，在窄屏下必然溢出。解决办法是改成max-width或者width: 100%，配合box-sizing: border-box。如果用了flex或者grid，检查有没有设min-width: 0，这个属性在flex子项里很关键，不设的话内容会撑破容器。

第三步，检查断点策略。AI默认用的断点通常是768px和1024px，但实际项目可能需要更细的断点。我建议在prompt里明确写清楚断点值，比如"在640px以下单列，640到1024两列，1024以上三列"。写清楚之后，AI生成的媒体查询会准确很多。

5.2 状态缺失和交互反馈不足的修复思路

状态缺失是另一个高频问题。AI生成的按钮，十有八九只有default态。修复思路是建立一个状态清单，每次生成后对照检查。

清单包括：hover态（背景色变化或阴影）、focus态（outline或ring，且要可见）、active态（按下时的反馈）、disabled态（降低透明度加cursor: not-allowed）、loading态（spinner或文字变化）。表单元素还要加error态和success态。这个清单可以写进prompt，让AI一次生成全。

如果AI还是漏了，就在反馈里明确说"给按钮补上hover、focus、active、disabled四个状态，hover背景加深10%，focus加2px的ring，active缩放0.98，disabled透明度0.5"。这种具体指令，AI执行起来很准。

5.3 可访问性检查不通过的典型场景

可访问性问题里，最常见的是对比度不足。AI选的颜色，在白色背景上看着还行，但实际对比度可能只有3:1，低于WCAG AA标准的4.5:1。解决办法是用对比度检查工具测一下，不达标就调整。我通常会把主色和背景色的对比度控制在7:1以上，这样即使有透明度变化也还有余量。

第二常见的是缺少alt。AI生成的img标签，alt经常是空的或者就是文件名。正确的做法是：装饰性图片用alt=""，内容性图片用描述性文字。这个规则要写进prompt。

第三是焦点顺序错乱。AI生成的DOM顺序有时候和视觉顺序不一致，导致键盘Tab的时候跳来跳去。解决办法是检查DOM结构，确保它和视觉阅读顺序一致。如果用了绝对定位或者flex order，要特别小心。

5.4 排查速查表

这张表我贴在显示器边上，每次检查的时候扫一眼，能省不少时间。里面每一条都是踩过坑之后总结的，尤其是动画卡顿那条，很多人不知道width和height的动画会触发重排，改成transform: scale就顺了。

6. 把impeccable变成习惯：一些个人体会

这套流程我跑了大概半年，最大的感受是：impeccable不是一次性的目标，而是一个持续收敛的过程。你不可能指望AI一次生成完美的代码，但你可以通过规范、检查、迭代，让每一版都比上一版好一点。积累下来，你的项目里就会沉淀出一批高质量的组件和规则，后续生成新东西的时候，起点会越来越高。

另一个体会是，规范的价值远大于工具。我换过好几个CLI工具，从codex cli到zcode cli再到trae cli，每个工具的手感不一样，但真正决定产出质量的，还是那份rules.md和design-tokens.json。工具会过时，规范不会。所以如果你刚开始做这件事，我建议先把规范写扎实，工具选哪个反而是次要的。

最后分享一个小技巧：每次生成完一个组件，花两分钟把这次用到的prompt和遇到的问题记下来，追加到你的规范文件里。三个月后，你会有一份非常贴合自己项目的"AI生成指南"，那时候再生成新组件，基本能做到一次到位。这个习惯看起来笨，但回报率极高，我强烈建议你试试。