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方面做得更顺。如果你团队已经在用gitlabgitlab 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能读懂的promptprompt的质量直接决定产出质量。我见过很多人写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 nameviewport contentwidthdevice-width, initial-scale1这一漏移动端就会按桌面宽度渲染然后缩小看起来就是崩了。加上这行一半的问题能解决。第二步检查有没有固定宽度。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的ringactive缩放0.98disabled透明度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 排查速查表问题现象可能原因排查方法修复方案移动端横向滚动固定宽度或viewport缺失检查width值和meta标签改max-width补viewport按钮无反馈状态缺失对照状态清单prompt里补状态要求对比度不足颜色选择不当用对比度工具测调整颜色至4.5:1以上焦点顺序乱DOM与视觉顺序不一致键盘Tab测试调整DOM结构间距不统一未引用token检查CSS值强制使用design tokens文字溢出未处理长文本输入超长文本测试加text-overflow或换行图片变形未设object-fit检查img样式加object-fit: cover动画卡顿用了非合成属性看DevTools性能面板改用transform和opacity这张表我贴在显示器边上每次检查的时候扫一眼能省不少时间。里面每一条都是踩过坑之后总结的尤其是动画卡顿那条很多人不知道width和height的动画会触发重排改成transform: scale就顺了。6. 把impeccable变成习惯一些个人体会这套流程我跑了大概半年最大的感受是impeccable不是一次性的目标而是一个持续收敛的过程。你不可能指望AI一次生成完美的代码但你可以通过规范、检查、迭代让每一版都比上一版好一点。积累下来你的项目里就会沉淀出一批高质量的组件和规则后续生成新东西的时候起点会越来越高。另一个体会是规范的价值远大于工具。我换过好几个CLI工具从codex cli到zcode cli再到trae cli每个工具的手感不一样但真正决定产出质量的还是那份rules.md和design-tokens.json。工具会过时规范不会。所以如果你刚开始做这件事我建议先把规范写扎实工具选哪个反而是次要的。最后分享一个小技巧每次生成完一个组件花两分钟把这次用到的prompt和遇到的问题记下来追加到你的规范文件里。三个月后你会有一份非常贴合自己项目的AI生成指南那时候再生成新组件基本能做到一次到位。这个习惯看起来笨但回报率极高我强烈建议你试试。