1. 从“impeccable”说起：一个被低估的前端设计关键词
第一次看到“impeccable”这个词，是在一个前端项目的代码注释里。当时团队里有人在 review 一段 CSS 时写了句/* keep this impeccable */，意思是“这段样式别动，已经无可挑剔了”。后来我慢慢发现，这个词在前端圈子里出现的频率越来越高，尤其是在 AI coding agents 开始大规模介入前端开发之后——它几乎成了一个隐性标准：你让 AI 帮你写界面，出来的东西能不能称得上 impeccable，直接决定了你要不要返工。
所以这篇博文，我想围绕“impeccable”这个关键词，聊聊它背后真正指向的那件事：如何让 AI coding agents 产出的前端设计达到“无可挑剔”的水准。这不是一篇讲某个具体工具怎么安装的教程，而是一份从 CLI 工作流、browser extension 辅助验证、到设计规范约束的完整实操总结。适合已经在用 codex cli、zcode cli、trae cli 这类工具做前端开发，但总觉得 AI 生成结果“差一口气”的开发者；也适合刚接触 AI 辅助前端、想少走弯路的同学。
我自己的背景是做了七八年前端，最近一年大量使用各类 CLI 形态的 AI coding agent 来搭界面、改组件、调样式。踩过的坑包括但不限于：AI 生成的间距永远差 4px、颜色对比度不达标、响应式断点乱写、组件命名前后不一致。这些问题单独看都不致命，但堆在一起，你的项目就离 impeccable 越来越远。下面我把这一年的经验拆开讲，尽量做到你读完能直接抄作业。
2. 为什么 AI 写的前端总是“差一口气”
2.1 问题的根源不在模型能力，而在约束缺失
很多人抱怨 AI coding agents 写前端不行，第一反应是“模型太笨”。但我实测下来，主流 CLI 工具背后的模型在单点能力上已经足够强——你让它写一个卡片组件，它能在三秒内给你一份结构完整、语义合理的代码。问题出在约束条件没有被显式传递。
举个具体例子。你让 AI 写一个按钮，它默认给你padding: 8px 16px、border-radius: 4px、font-size: 14px。单看没问题，但你的设计系统里按钮是padding: 10px 20px、border-radius: 6px、font-size: 15px。AI 不知道这些，它只能按训练数据里最常见的值来猜。结果就是每个组件都要你手动改一遍，改到最后你自己都烦了。
这就是为什么“impeccable”在前端语境下，首先是一个约束管理问题，而不是模型能力问题。你需要把设计 token、间距体系、颜色变量、断点规则这些东西，以 AI 能理解的方式喂给它。
2.2 CLI 工具改变了什么，又没改变什么
codex cli、zcode cli、trae cli 这类工具的出现，确实让 AI 辅助开发的门槛降了很多。你不需要打开浏览器、不需要复制粘贴代码，直接在终端里就能让 AI 读写项目文件。这个工作流的效率提升是实打实的。
但它没有改变的是：AI 依然不知道你的项目上下文。CLI 工具能读到你的文件，但读到的只是文本。它不知道你的设计系统文档在哪、不知道你的品牌色为什么是那个值、不知道你的响应式策略是 mobile-first 还是 desktop-first。这些信息如果不主动提供，AI 就只能靠猜。
我试过在 codex cli 里直接让它改一个组件的样式，结果它把整个文件的缩进从 2 空格改成了 4 空格，还顺手“优化”了几个它认为不合理的类名。那次之后我就明白了一个道理：用 CLI 工具做前端，你必须先建立规则，再让 AI 在规则内工作。
2.3 “impeccable”的四个可量化维度
把“无可挑剔”拆开，我总结出四个可以量化检查的维度：
| 维度 | 具体指标 | 常见 AI 翻车点 |
|---|---|---|
| 视觉一致性 | 间距、圆角、阴影、字号是否统一 | 同一页面出现 3 种不同的卡片圆角 |
| 响应式完整 | 断点覆盖、容器查询、流式布局 | 只在 1440px 下好看，移动端直接溢出 |
| 可访问性 | 对比度、焦点态、语义标签 | 按钮没有 focus-visible 样式 |
| 代码整洁度 | 命名规范、无冗余样式、无魔法数字 | 硬编码颜色值、重复定义变量 |
这四个维度里，前三个是用户能直接感知的，第四个是维护者能感知的。AI 在前三个维度上翻车最多，因为这三个都依赖“全局一致性”，而 AI 每次生成都是局部视角。
3. 用 CLI 工作流把设计约束“焊死”在项目里
3.1 建立一份 AI 能读懂的设计约束文件
我的做法是在项目根目录放一个DESIGN_RULES.md，专门给 AI coding agents 读。这个文件不追求文采，只追求结构化、可检索、无歧义。内容大概长这样：
# Design Rules ## Spacing Scale - Base unit: 4px - Allowed values: 4, 8, 12, 16, 24, 32, 48, 64 - Never use arbitrary values like 10px, 15px, 20px ## Border Radius - Small: 4px (inputs, tags) - Medium: 8px (cards, modals) - Large: 16px (hero sections) - Full: 9999px (avatars, pills) ## Colors - Primary: var(--color-primary) #2563EB - Never hardcode hex values in components - Text on primary must use white or --color-primary-foreground ## Breakpoints - Mobile: 0-639px - Tablet: 640-1023px - Desktop: 1024px+ - Always mobile-first ## Component Naming - Use PascalCase for components - Use kebab-case for CSS classes - Prefix all custom classes with `app-`这份文件的关键在于用否定句明确边界。“Never use arbitrary values”比“Prefer consistent spacing”有效得多，因为 AI 对否定指令的执行率明显更高。我实测下来，加了这份文件之后，AI 生成的间距错误率从大概 40% 降到了 10% 以下。
3.2 在 CLI 里用系统提示词固化规则
光有文件还不够，你得让 AI 每次生成前都读到它。不同 CLI 工具的做法不一样，但核心思路一致：把设计规则作为系统提示词的一部分。
以 codex cli 为例，我通常会在项目根目录放一个.codex/instructions.md，内容里明确写：
Before generating any frontend code, read DESIGN_RULES.md. All spacing values must come from the allowed scale. All colors must use CSS variables defined in globals.css. If a required token is missing, ask before inventing a new one.然后在实际对话里，我会用/compact命令定期压缩上下文，确保设计规则不会被后续的长对话挤掉。这个细节很多人忽略——CLI 工具的上下文窗口是有限的，聊得越久，早期的规则越容易被稀释。定期 compact 并重新注入规则，是我保持输出稳定性的关键操作。
3.3 用 browser extension 做实时视觉验证
CLI 工具负责生成代码，但代码到底长什么样，你得用眼睛看。这时候 browser extension 就派上用场了。我常用的组合是：一个用于检查可访问性的扩展，一个用于测量间距和颜色的扩展。
具体流程是这样的：AI 生成组件后，我在本地起 dev server，用 browser extension 打开页面，然后逐项检查：
- 用测量工具点一下卡片的内边距，看是不是 16px 或 24px，而不是 15px 这种奇怪的值
- 用对比度检查工具看文字和背景的对比度是否达到 4.5:1
- 用响应式预览工具从 320px 拖到 1920px，看有没有布局断裂
发现问题后，我不直接改代码，而是把问题描述反馈给 CLI 里的 AI，让它按规则重新生成。这样做的好处是：修正逻辑被固化在 AI 的工作流里，下次同类问题它会自己避免。如果你每次都手动改，AI 永远学不会。
提示：browser extension 的选择上，优先选那些能输出具体数值的，而不是只给“通过/不通过”的。具体数值方便你反馈给 AI，比如“卡片内边距是 15px，应该是 16px”，比“间距不对”有效十倍。
4. 核心细节：让 AI 输出 impeccable 前端的关键操作
4.1 组件生成前的“三问”检查
每次让 AI 生成一个新组件之前，我会先问自己三个问题，并把答案作为提示词的一部分传给 CLI：
- 这个组件在哪些断点下会出现？如果只在桌面端出现，就不需要写移动端样式；如果全端出现，就要明确 mobile-first 的写法。
- 它复用哪些已有 token？把相关的 CSS 变量名直接列给 AI，避免它自己发明。
- 它的交互状态有哪些？hover、focus、active、disabled、loading，这些状态如果不提前说，AI 大概率只写默认态。
这三个问题看起来简单，但能挡掉大部分返工。我统计过，加了这三问之后，组件首次生成可用率从大概 50% 提升到了 80% 左右。
4.2 用“示例驱动”代替“描述驱动”
AI 对示例的理解能力远强于对描述的理解能力。与其说“写一个符合我们设计系统的卡片”，不如直接给它一个已经写好的卡片组件作为参考：
/* Reference card component */ .app-card { padding: 24px; border-radius: 8px; background: var(--color-surface); box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1); }然后说“按这个风格写一个用户资料卡片”。AI 会提取 padding、border-radius、background、box-shadow 这些模式，应用到新组件上。这个方法我称之为“示例锚定”，比纯文字描述稳定得多。
4.3 响应式断点的参数计算过程
响应式是 AI 最容易翻车的地方。我见过 AI 写出@media (max-width: 768px)和@media (min-width: 768px)同时存在的代码，导致 768px 这个点被两个规则同时命中。为了避免这种问题，我在 DESIGN_RULES.md 里明确定义了断点体系，并且要求 AI 在写媒体查询时必须引用变量：
:root { --bp-sm: 640px; --bp-md: 1024px; --bp-lg: 1280px; } /* AI must use these */ @media (min-width: 640px) { ... } @media (min-width: 1024px) { ... }为什么选 640 和 1024 而不是 768 和 1200？因为 640 是很多移动设备横屏的临界点，1024 是 iPad 横屏的宽度。这两个值在实际测试中覆盖了绝大多数设备场景，而且和主流 CSS 框架的默认断点接近，AI 的训练数据里对这些值更熟悉，生成时出错概率更低。
4.4 可访问性的自动化检查
可访问性这块，我建议不要依赖 AI 自觉，而是用工具强制检查。具体做法是在项目里装一个 lint 规则，然后在 CLI 工作流里让 AI 每次生成后自动跑一遍。
我常用的检查项包括：
- 所有图片是否有 alt 属性
- 所有按钮是否有可识别的文本或 aria-label
- 所有表单输入是否有关联的 label
- 颜色对比度是否达标
- 焦点顺序是否合理
这些检查用 browser extension 也能做，但集成到 CLI 工作流里更高效。你可以在让 AI 生成代码后，直接追加一句“跑一下 a11y 检查，把不通过的项目修掉”。AI 会自己调用工具、读结果、改代码，整个过程不需要你介入。
注意：可访问性检查工具的报告有时候会有误报，尤其是对比度检查。如果 AI 说某个颜色对比度不达标，但你觉得视觉上没问题，先手动验证一下再决定要不要改。我遇到过工具把半透明背景上的文字误判为低对比度的情况。
5. 实操全流程：从零搭一个 impeccable 的组件
5.1 环境准备与工具链确认
开始之前，确认你的工具链是齐的。我用的组合是：
- 一个 CLI 形态的 AI coding agent（codex cli 或同类工具）
- 一个 browser extension 用于视觉验证
- 一个 CSS lint 工具（stylelint 就够）
- 一个可访问性检查工具
这些工具不需要全部装齐才能开始，但装齐之后工作流会顺畅很多。尤其是 stylelint，它能在 AI 生成代码后立刻告诉你哪里违反了规则，比人工检查快得多。
5.2 第一步：写设计规则文件
按第 3.1 节的模板，把项目的间距、圆角、颜色、断点、命名规范写进DESIGN_RULES.md。这一步不要偷懒，规则越具体，后面越省事。我建议至少花半小时把这份文件写扎实，包括：
- 所有允许的间距值
- 所有允许的圆角值
- 所有颜色变量及其使用场景
- 所有断点及其对应的设备类型
- 组件命名和 CSS 类命名的规则
写完之后，把这份文件放到项目根目录，并在 CLI 的系统提示词里引用它。
5.3 第二步：生成第一个组件并验证
让 AI 生成一个简单的按钮组件，提示词大概这样：
Read DESIGN_RULES.md first. Generate a primary button component using our design tokens. Include hover, focus-visible, active, and disabled states. Use mobile-first responsive approach. Output as a React component with CSS modules.生成后，不要急着用。先做三件事：
- 用 stylelint 跑一遍，看有没有违反规则的硬编码值
- 用 browser extension 在浏览器里看实际效果，检查间距、颜色、对比度
- 用键盘 Tab 键走一遍，看焦点态是否清晰
发现问题后，把具体问题反馈给 AI，让它修正。修正后的版本再跑一遍检查。这个循环通常需要两到三轮，但每轮之后 AI 的输出都会更接近 impeccable。
5.4 第三步：批量生成与一致性维护
单个组件跑通之后，就可以批量生成其他组件了。这时候的关键是保持参考一致性。我的做法是：每生成一个新组件，都把已经通过验证的组件作为参考传给 AI。
比如生成卡片组件时，提示词里加上：
Reference the Button component at src/components/Button/Button.module.css for spacing and color usage patterns.这样 AI 会提取按钮组件的 token 使用方式，应用到卡片上。批量生成十个组件后，整个页面的视觉一致性会明显好于逐个独立生成。
5.5 第四步：用 browser extension 做整页审查
所有组件生成完、拼成页面后，用 browser extension 做一次整页审查。重点看：
- 页面整体的间距节奏是否统一
- 不同组件的圆角是否一致
- 颜色使用是否克制（有没有出现设计系统之外的颜色）
- 响应式断点处是否有布局跳变
这一步我通常会截图，然后把截图和问题描述一起发给 CLI 里的 AI，让它做最后一轮修正。AI 对截图的理解能力现在很强，能识别出“这个卡片和上面那个卡片的间距不一样”这类问题。
6. 常见问题与排查技巧实录
6.1 AI 总是忽略设计规则怎么办
这是最常见的问题。你明明写了 DESIGN_RULES.md，AI 还是按自己的习惯来。原因通常是规则文件没有被正确加载，或者被后续对话挤出了上下文。
排查步骤：
- 确认规则文件在项目根目录，且文件名和系统提示词里引用的一致
- 在对话开始时，明确让 AI 复述一遍关键规则，确认它读到了
- 如果对话很长，用
/compact压缩后重新注入规则 - 如果还是不行，把规则直接写在提示词里，而不是依赖文件引用
我实测下来，把关键规则直接写在提示词里的执行率最高，但缺点是每次都要复制粘贴。折中方案是：规则文件放完整的，提示词里放最关键的十条。
6.2 生成的样式在浏览器里和预期不符
有时候 AI 生成的代码看起来没问题，但浏览器里就是不对。常见原因和排查方法：
| 现象 | 可能原因 | 排查方法 |
|---|---|---|
| 间距不对 | CSS 优先级冲突 | 用 DevTools 看实际生效的规则 |
| 颜色不对 | 变量未定义或拼写错误 | 检查 CSS 变量是否在作用域内 |
| 布局错乱 | flex/grid 属性冲突 | 逐层检查容器的 display 属性 |
| 响应式失效 | 媒体查询顺序错误 | 确认移动端规则在桌面端规则之前 |
这类问题的核心排查思路是：不要猜，用 DevTools 看实际计算值。然后把计算值和预期值的差异反馈给 AI，让它修正。
6.3 多个 CLI 工具混用时的一致性维护
有些人会同时用 codex cli 和 trae cli，或者在不同项目里用不同工具。混用时最大的问题是：不同工具对同一份设计规则的理解可能不一致。
我的建议是：设计规则文件保持唯一，所有工具都引用同一份。如果某个工具对规则的理解有偏差，就在该工具的专属配置里加一条覆盖规则，而不是改主规则文件。这样能保证跨工具的一致性。
6.4 性能与生成速度的平衡
AI 生成前端代码时，如果你要求它做完整的可访问性检查、响应式验证、样式 lint，生成速度会明显变慢。我的经验是：开发阶段可以放宽检查，提交前再跑完整检查。
具体做法是：在 CLI 里配置两套提示词，一套用于快速生成（只检查关键规则），一套用于提交前审查（跑全部检查）。这样既保证了开发效率，又保证了最终质量。
提示：如果你用的是支持自定义命令的 CLI 工具，可以把这两套提示词做成两个命令，比如
/quick-gen和/full-review，用起来会顺手很多。
6.5 常见问题速查表
| 问题 | 快速排查 | 长期解法 |
|---|---|---|
| AI 忽略设计规则 | 确认规则被加载 | 规则写入系统提示词 |
| 间距值不统一 | 用测量工具检查 | 在规则里明确允许值 |
| 响应式断裂 | 从 320px 拖到 1920px | 定义断点变量并强制引用 |
| 颜色硬编码 | 搜索 hex 值 | 规则里禁止硬编码 |
| 焦点态缺失 | Tab 键走一遍 | 规则里要求所有交互元素有 focus-visible |
| 组件命名混乱 | 检查文件命名 | 规则里明确命名规范 |
7. 我个人的几条实操心得
第一，不要追求一次生成就 impeccable。AI 生成前端代码是一个迭代过程，第一版有问题是正常的。关键是建立一套快速反馈和修正的机制，让每一轮迭代都更接近目标。
第二，规则文件要持续维护。项目在变，设计系统在变，规则文件也要跟着更新。我每个月会花半小时 review 一遍 DESIGN_RULES.md，把新出现的模式加进去，把不再使用的规则删掉。
第三，browser extension 的验证不能省。CLI 工具再强，也替代不了人眼看一遍。我见过太多代码层面没问题、视觉层面一塌糊涂的案例。花五分钟用扩展检查一遍，能省下后面半小时的返工。
第四，把 AI 当成一个需要明确指令的初级开发者。你给它的约束越清晰，它的输出越稳定。模糊的指令只会得到模糊的结果，这一点在前端设计上尤其明显。
最后分享一个小技巧：如果你用的是支持多轮对话的 CLI 工具，可以在每次生成新组件前，让 AI 先复述一遍它将要遵守的规则。这个动作看起来多余，但能显著降低它“忘记规则”的概率。我现在的习惯是，每开一个新对话，第一句就是“复述 DESIGN_RULES.md 里的间距和颜色规则”，确认它读到了再开始干活。
