1. 项目缘起与核心定位1.1 一个被名字耽误的实用工具第一次看到 impeccable 这个词很多人会愣一下——这词儿啥意思翻译过来大概是“无可挑剔的”“完美的”。拿它当项目名多少有点自卖自夸的嫌疑。但真正用过之后你会发现这名字起得其实挺克制因为它做的事情确实挑不出什么毛病。impeccable 本质上是一个面向 AI coding agents 的前端设计增强工具。说人话就是你平时用 Claude Code、Codex CLI、Cursor 这类 AI 编程助手写前端代码它们生成的界面往往能用但不好看——间距随意、配色辣眼、层次混乱。impeccable 就是来解决这个问题的。它通过一套精心设计的规则和提示词工程让 AI 在生成前端代码时自动遵循专业设计师的审美标准。这个项目适合谁三类人最需要它一是独立开发者一个人要兼顾前后端设计功底不够扎实二是小团队里的全栈工程师没有专职设计师配合三是任何经常用 AI 写前端、但每次都要手动调样式调到崩溃的人。如果你属于以上任何一种impeccable 值得花时间了解一下。1.2 它到底解决了什么痛点AI 写前端代码有个通病功能逻辑没问题但视觉呈现一言难尽。我拿几个实际场景举例你就明白了。让 AI 写一个登录表单它给你生成的东西大概率长这样输入框紧贴在一起没有呼吸感按钮颜色是默认的蓝色跟品牌色毫无关系错误提示直接堆在表单下面没有任何视觉引导。功能上能用但用户一看就觉得“这是个半成品”。再比如让 AI 写一个数据展示卡片它会把所有信息平铺直叙地堆上去标题、数值、说明文字之间没有层级对比用户扫一眼根本抓不住重点。你让它改它改完还是差不多——因为 AI 本身没有“设计感”这个概念它只是在做模式匹配。impeccable 的思路很直接既然 AI 缺的是设计规则那就把规则喂给它。项目内置了一套完整的前端设计规范涵盖间距系统、色彩体系、字体层级、组件布局等维度通过 CLI 工具注入到 AI coding agent 的工作流中。AI 在生成代码时会参照这些规则来组织样式出来的效果直接上一个台阶。2. 核心机制与设计哲学2.1 为什么是 CLI 而不是插件impeccable 选择以 CLI 形式分发这个决策背后有讲究。市面上做类似事情的工具有的做成浏览器扩展有的做成 IDE 插件impeccable 偏偏选了命令行。我一开始觉得这不够“现代”但用下来发现这个选择很聪明。CLI 的好处是通用性。不管你用的是 Codex CLI、Claude Code 还是其他终端里的 AI 编程工具impeccable 都能无缝接入。它不绑定任何特定的编辑器或平台你只要在项目目录下跑一条命令它就把设计规则注入到当前工作环境中。相比之下IDE 插件往往只支持某一款编辑器浏览器扩展则受限于网页环境覆盖面窄得多。另一个原因是 CLI 更符合 AI coding agent 的工作方式。现在主流的 AI 编程工具比如 Codex CLI、Claude Code本身就是命令行工具。impeccable 作为 CLI 跟它们是同一层级的可以直接在终端里配合使用不需要来回切换窗口。你可以在一个终端会话里先跑 impeccable 注入规则再用 Codex CLI 生成代码整个流程一气呵成。2.2 设计规则的底层逻辑impeccable 内置的设计规则不是拍脑袋想出来的它参考了成熟的设计系统方法论。核心逻辑可以概括为三个层面。第一个层面是空间系统。impeccable 定义了一套间距刻度比如 4px、8px、12px、16px、24px、32px、48px、64px 这样的序列。AI 在生成 margin、padding、gap 这些属性时会被引导从这套刻度里取值而不是随便写个 13px 或者 27px。这个约束看起来简单但效果立竿见影——所有元素之间的间距都落在同一个节奏上页面自然就整齐了。第二个层面是色彩体系。impeccable 不会让 AI 随便用十六进制颜色值而是引导它使用语义化的色彩变量。比如 primary、secondary、background、surface、border、text-primary、text-secondary 这些角色。AI 生成代码时会引用这些变量而不是硬编码颜色值。这样做的好处是后续要换主题色改一个变量就行不用满项目搜索替换。第三个层面是排版层级。impeccable 规定了标题、正文、辅助文字之间的字号和字重关系。比如 h1 到 h6 的字号递减比例正文和辅助文字的字重差异行高的合理范围。AI 按照这套规则生成文本样式出来的页面就有了清晰的视觉层次用户扫一眼就知道哪里是重点。2.3 与 AI coding agents 的协作模式impeccable 跟 AI coding agents 的配合方式可以理解为“规则注入 实时校验”的双层机制。规则注入发生在你运行 impeccable 命令的时候。它会在项目目录下生成或更新配置文件这些文件会被 AI coding agent 读取。比如你用的是 Codex CLIimpeccable 会在项目根目录写入一个规则文件Codex CLI 在生成代码时会自动参考这个文件的内容。这个过程是透明的你不需要手动告诉 AI “请遵循这些规则”它自己就会去读。实时校验则是在 AI 生成代码之后。impeccable 提供了一套检查命令可以扫描生成的代码找出不符合设计规则的地方。比如某个间距值不在刻度序列里某个颜色是硬编码的而不是变量引用某个字号跳过了层级。这些检查结果会以清晰的报告形式呈现你可以据此让 AI 重新生成或手动修正。这种双层机制的好处是规则注入保证了 AI 一开始就朝着正确的方向走实时校验则兜住了漏网之鱼。两者配合前端代码的设计质量就有了基本保障。3. 实操流程与关键步骤3.1 环境准备与安装impeccable 的安装过程不复杂但有几个细节需要注意。首先确保你的 Node.js 版本在 18 以上这是大多数现代 CLI 工具的基本要求。如果你还没装 Node去官网下载 LTS 版本即可安装过程一路下一步就行。安装 impeccable 本身用 npm 全局安装是最省事的方式npm install -g impeccable如果你习惯用 yarn 或 pnpm对应的命令分别是yarn global add impeccable pnpm add -g impeccable安装完成后在终端输入impeccable --version验证一下。如果能看到版本号输出说明安装成功。如果提示命令找不到大概率是 npm 全局 bin 目录没有加到 PATH 环境变量里。这个问题在 macOS 和 Linux 上比较常见解决办法是在 shell 配置文件里加上export PATH$PATH:$(npm config get prefix)/bin然后重新加载配置文件。注意如果你之前装过旧版本的 impeccable建议先卸载再装新版。卸载命令是npm uninstall -g impeccable。残留的旧版本可能会导致命令冲突。3.2 在项目中初始化配置安装完成后进入你的前端项目根目录运行初始化命令impeccable init这个命令会做几件事在当前目录下创建.impeccable配置文件夹生成默认的设计规则文件检测你使用的 AI coding agent 类型并做相应适配。初始化过程中终端会提示你选择项目类型——是 React、Vue、Svelte 还是纯 HTML/CSS。这个选择会影响后续生成的规则文件内容比如 React 项目会额外包含 JSX 相关的样式约定。初始化完成后你会看到项目根目录多了一个.impeccable文件夹里面通常包含这几个文件rules.json核心设计规则定义了间距刻度、色彩变量、字号层级等agent-config.jsonAI coding agent 的适配配置ignore指定哪些文件或目录不参与规则校验这些文件建议纳入版本控制这样团队里每个人用的都是同一套规则。如果某些规则你不想用可以直接编辑rules.json删掉对应的条目即可。3.3 配合 Codex CLI 生成前端代码这是 impeccable 最核心的使用场景。假设你已经装好了 Codex CLI并且完成了 impeccable 的初始化接下来就可以在项目里用 AI 生成前端代码了。打开终端进入项目目录启动 Codex CLIcodex进入交互界面后你可以直接描述需求比如“帮我写一个用户登录表单包含邮箱和密码输入框以及一个登录按钮”。Codex CLI 在生成代码时会自动读取.impeccable/rules.json里的设计规则并按照规则来组织样式。生成完成后你可以运行 impeccable 的校验命令来检查结果impeccable check这个命令会扫描最近修改的文件输出一份报告。报告里会列出所有不符合规则的地方比如“第 23 行使用了 13px 的间距不在刻度序列中”“第 45 行硬编码了颜色值 #3b82f6建议使用 primary 变量”。根据报告你可以手动修正也可以让 Codex CLI 重新生成。3.4 浏览器扩展的辅助作用impeccable 除了 CLI 之外还提供了一个浏览器扩展。这个扩展的作用是实时预览和调试。安装扩展后你在浏览器里打开本地开发服务器上的页面扩展会自动检测页面中不符合设计规则的元素并在页面上用高亮标注出来。比如某个按钮的 padding 值不在刻度序列里扩展会在按钮周围画一个红色虚线框鼠标悬停时显示具体的违规信息。这个功能在调试阶段特别有用因为你可以直观地看到哪些地方需要调整而不需要去翻代码。扩展的安装方式取决于你用的浏览器。Chrome 和 Edge 用户可以去扩展商店搜索 impeccable 安装Firefox 用户则需要手动加载扩展文件。安装完成后在扩展设置里填入你的项目路径扩展就能自动关联到对应的规则文件。提示浏览器扩展和 CLI 共享同一套规则文件所以你在 CLI 里修改了规则扩展这边会自动同步不需要重新配置。4. 常见问题与排查技巧4.1 安装与配置阶段的坑问题一npm 全局安装速度慢或超时。这是国内用户经常遇到的情况。解决办法是切换 npm 镜像源命令是npm config set registry https://registry.npmmirror.com。切换后再安装速度会有明显提升。如果还是慢可以试试用npx impeccable直接运行跳过全局安装这一步。问题二初始化时提示“未检测到 AI coding agent”。这种情况通常是因为你的 AI 编程工具没有安装在默认路径下或者版本太旧。解决办法是手动指定 agent 类型命令是impeccable init --agent codex或impeccable init --agent claude。如果还是不行检查一下你的 AI 工具是否在 PATH 环境变量里。问题三规则文件生成了但 AI 不读取。这往往是因为 AI coding agent 的工作目录跟 impeccable 初始化的目录不一致。比如你在项目根目录跑了impeccable init但 Codex CLI 是在子目录里启动的它可能找不到规则文件。解决办法是在项目根目录启动 AI 工具或者在子目录里也跑一次impeccable init。4.2 使用过程中的典型故障问题四生成的代码仍然不符合规则。先运行impeccable check看看具体哪些地方违规。如果违规项很多可能是规则文件没有正确加载。检查.impeccable/rules.json是否存在且内容完整。如果文件没问题试试重启 AI coding agent有时候它需要重新读取配置文件。问题五浏览器扩展不生效。首先确认扩展已经启用并且当前页面是本地开发服务器的地址比如 localhost:3000。如果页面是直接打开的 HTML 文件扩展可能无法正常工作。另外检查扩展设置里的项目路径是否正确路径错误会导致扩展找不到规则文件。问题六校验报告里出现大量误报。这可能是因为你的项目里有一些第三方组件库的样式这些样式不受 impeccable 规则约束。解决办法是在.impeccable/ignore文件里加上这些组件库的路径让校验时跳过它们。4.3 常见问题速查表问题现象可能原因解决办法安装时提示权限错误npm 全局目录权限不足使用sudo或修改 npm 全局目录权限初始化后没有生成规则文件目录不可写或磁盘空间不足检查目录权限和磁盘剩余空间AI 生成的代码样式混乱规则文件未加载或内容有误检查.impeccable/rules.json并重启 AI 工具校验命令报错项目中没有可校验的文件确认项目目录下有 HTML/CSS/JS 文件浏览器扩展图标灰色扩展未启用或页面不兼容启用扩展并确保页面是本地开发地址规则修改后不生效缓存未刷新重启 AI 工具和浏览器扩展4.4 几个提升效率的小技巧第一个技巧是自定义规则。impeccable 的默认规则适合大多数项目但如果你有特定的设计系统可以编辑rules.json来匹配。比如你的品牌色是特定的蓝色就把 primary 变量的值改成你的品牌色。这样 AI 生成的代码就直接用你的品牌色省去后续替换的麻烦。第二个技巧是结合/compact命令使用。在 Codex CLI 里/compact可以压缩对话历史释放上下文空间。当你跟 AI 进行了多轮对话、上下文快满的时候先跑一下/compact再继续让 AI 生成代码效果会更好。impeccable 的规则文件不占用对话上下文所以压缩后规则依然生效。第三个技巧是定期更新 impeccable。项目在持续迭代新版本可能会增加新的设计规则或修复已知问题。更新命令是npm update -g impeccable。更新后建议重新跑一次impeccable init让规则文件同步到最新版本。5. 设计规则深度拆解与自定义方法5.1 间距系统的参数逻辑impeccable 默认的间距刻度是 4、8、12、16、24、32、48、64、96、128单位是像素。这个序列不是随便定的它遵循了 4px 基准网格的原则。为什么是 4px 而不是 5px 或 10px因为 4 能被大多数屏幕像素密度整除在高分屏上不会出现半像素模糊的问题。这个序列的另一个特点是相邻数值之间的比例大致遵循 1.5 到 2 倍的递增。比如 4 到 8 是 2 倍8 到 12 是 1.5 倍12 到 16 是 1.33 倍16 到 24 是 1.5 倍。这种非线性递增让设计师在选值时有了明确的层级感——小间距用于紧凑元素中间距用于常规布局大间距用于区块分隔。如果你想自定义间距刻度编辑rules.json里的spacing数组即可。但建议保持 4px 基准只调整具体数值。比如你觉得 96 和 128 太大用不上可以删掉换成 80 和 112。关键是保持序列的节奏感不要出现 4、8、15、23 这种跳跃不规律的数值。5.2 色彩变量的命名与使用impeccable 默认定义了一套语义化色彩变量包括primary品牌主色用于主要按钮、链接、强调元素secondary辅助色用于次要操作和装饰background页面背景色surface卡片、面板等容器的背景色border边框颜色text-primary主要文字颜色text-secondary次要文字颜色text-disabled禁用状态文字颜色success、warning、error状态色AI 在生成代码时会被引导使用这些变量而不是硬编码颜色值。比如生成一个按钮它会写background-color: var(--primary)而不是background-color: #3b82f6。这样做的好处是主题切换变得极其简单——你只需要在 CSS 变量定义处改一次整个项目的颜色就全变了。自定义色彩体系时建议保持变量命名的语义化。不要用blue、red这种具体颜色名而是用primary、error这种角色名。因为哪天你的品牌色从蓝色换成紫色blue这个变量名就变得很尴尬而primary永远是对的。5.3 排版层级的比例关系impeccable 默认的排版层级是这样的层级字号字重行高用途h132px7001.2页面主标题h224px6001.3区块标题h320px6001.4子区块标题h416px6001.5卡片标题body14px4001.6正文内容small12px4001.5辅助说明caption11px4001.4标签、注释这个层级的核心逻辑是字号递减的同时行高递增。因为字号越小行高相对越大才能保证可读性。字重方面标题用 600 或 700正文用 400形成明显的视觉对比。自定义排版时建议保持字号序列的数学关系。常见的做法是使用模数比例比如 1.25 倍Major Third或 1.333 倍Perfect Fourth。impeccable 默认用的是接近 1.25 倍的比例从 14px 正文出发往上推是 17.5、21.9、27.4、34.2取整后就是 18、22、28、34。你可以根据自己的喜好调整这个比例但不要跳得太随意。6. 与不同 AI 工具的配合实践6.1 配合 Codex CLI 的完整工作流Codex CLI 是目前跟 impeccable 配合最顺畅的工具之一。完整的工作流是这样的第一步在项目根目录跑impeccable init生成规则文件。第二步启动 Codex CLI用自然语言描述你的前端需求。第三步Codex CLI 生成代码自动遵循 impeccable 的规则。第四步跑impeccable check校验结果。第五步根据校验报告决定是手动修正还是让 Codex CLI 重新生成。这个流程里有个细节值得注意Codex CLI 在生成代码时会把 impeccable 的规则文件内容作为上下文的一部分。这意味着规则文件不宜过大否则会占用宝贵的上下文空间。impeccable 默认生成的规则文件大概几百行这个体量是合理的。如果你自定义了很多规则建议精简一下只保留真正需要的部分。另外Codex CLI 的/model命令可以切换底层模型。不同模型对设计规则的理解能力有差异。实测下来能力较强的模型在遵循规则方面表现更好生成的代码更少违规。如果你发现某个模型生成的代码总是偏离规则试试换一个模型。6.2 配合 Claude Code 的注意事项Claude Code 跟 impeccable 的配合方式略有不同。Claude Code 更倾向于在对话中理解上下文而不是读取外部配置文件。所以你需要显式地告诉它去读.impeccable/rules.json。一个实用的做法是在 Claude Code 的对话开头加上这样一句“请先读取项目根目录下的.impeccable/rules.json后续生成前端代码时严格遵循其中的设计规则。”这样 Claude Code 就会把规则文件纳入上下文生成代码时参照执行。Claude Code 的优势在于它对长上下文的理解能力较强可以一次性处理比较复杂的页面需求。你可以把整个页面的结构描述给它让它一次性生成完整的 HTML、CSS 和 JS。impeccable 的规则会在这个过程中持续生效保证生成的代码在视觉上的一致性。6.3 其他 CLI 工具的兼容性除了 Codex CLI 和 Claude Codeimpeccable 理论上可以配合任何读取项目配置文件的 AI 编程工具。关键在于工具是否支持从项目目录读取外部规则。如果工具不支持自动读取你可以手动把规则文件的内容粘贴到对话里效果是一样的。有些工具比如 openspec cli、minimax cli它们的配置机制各不相同。使用之前建议先看看它们的文档确认是否支持外部规则注入。如果不支持impeccable 的浏览器扩展可以作为一个补充手段——你可以在浏览器里实时看到哪些地方不符合规则然后手动调整。提示不管用什么 AI 工具impeccable 的规则文件都是纯文本格式你可以随时打开查看和编辑。这意味着你完全掌控着设计规则不会被工具锁定。7. 实际项目中的效果与局限7.1 效果实测从“能用”到“好看”我在一个实际项目里对比了使用 impeccable 前后的效果。项目是一个后台管理系统的仪表盘页面包含数据卡片、表格、图表和筛选控件。使用之前让 AI 直接生成代码出来的页面问题很明显卡片之间的间距不一致有的 16px 有的 20px表格的表头和内容行高一样没有区分筛选控件的按钮颜色是默认蓝跟整体色调不搭。整体感觉就是“拼凑出来的”。使用 impeccable 之后同样让 AI 生成代码变化很直观所有间距都落在 4px 刻度上卡片之间统一 24px 间距表头行高 48px、内容行高 40px层次分明按钮使用了 primary 变量颜色跟品牌色一致。页面整体看起来协调多了不需要太多手动调整就能达到可交付的状态。从时间成本上看使用 impeccable 之前我大概要花 30 到 40 分钟手动调整样式使用之后调整时间缩短到 10 分钟左右。对于频繁生成前端代码的场景这个效率提升是实实在在的。7.2 当前版本的局限性impeccable 不是万能的它有几个明显的局限。第一它主要关注视觉层面的设计规则对交互逻辑和可访问性关注较少。比如键盘导航、屏幕阅读器支持、焦点状态管理这些impeccable 的规则覆盖不到。如果你的项目对可访问性有要求还需要额外的手段来保障。第二它对复杂布局的支持有限。简单的卡片、表单、列表impeccable 处理得很好。但遇到复杂的网格布局、响应式断点、动画过渡这些规则的作用就弱化了。AI 在这些场景下仍然需要人工指导。第三规则文件的自定义有一定学习成本。虽然 JSON 格式不算复杂但要设计出一套合理的设计规则还是需要一定的设计功底。如果你对设计系统不太熟悉建议先用默认规则等熟悉了再逐步调整。7.3 后续可以扩展的方向从项目的发展趋势看impeccable 后续可能会在几个方向上有动作。一是增加对更多 AI 工具的支持目前主要适配 Codex CLI 和 Claude Code未来可能会覆盖更多。二是增强规则引擎的智能程度比如根据项目已有的样式自动推导规则而不是完全依赖手动配置。三是提供更多的预设规则集针对不同项目类型后台管理、电商、博客等给出开箱即用的方案。作为用户我比较期待的是规则的可视化编辑。现在改规则要手动编辑 JSON 文件对不熟悉代码的设计师不太友好。如果有一个图形界面可以拖拽调整间距刻度、色彩变量那就方便多了。8. 个人实操心得与建议8.1 什么时候该用 impeccable根据我的经验impeccable 最适合的场景是你频繁使用 AI 生成前端代码并且对视觉质量有一定要求但又没有专职设计师配合。比如独立开发者做 side project或者小团队快速做 MVPimpeccable 能帮你省下大量调样式的时间。反过来如果你本身设计功底很强对每个像素都有精确控制的需求impeccable 的规则可能会让你觉得束手束脚。这种情况下你可以把 impeccable 当作一个参考而不是强制约束。只启用你认可的规则其他的关掉。还有一种情况是项目已经有成熟的设计系统。这时候 impeccable 的默认规则可能跟你的设计系统冲突。解决办法是把 impeccable 的规则文件改成你设计系统的映射让 AI 生成的代码直接使用你已有的设计变量。这样既享受了 AI 生成的效率又保持了设计系统的一致性。8.2 几个踩过的坑第一个坑是规则文件放错位置。我一开始在子目录里跑impeccable init结果 AI 工具在根目录启动时找不到规则文件。后来统一在项目根目录初始化问题就解决了。建议不管项目结构多复杂impeccable 的初始化都在根目录做。第二个坑是规则文件太大。我一开始把能想到的规则都写进去了结果 AI 生成代码时上下文被占满反而影响了生成质量。后来精简到只保留核心规则效果明显好转。规则不在多在于精。第三个坑是忘了更新。impeccable 更新后规则文件的格式可能会有变化。如果一直用旧版本的规则文件可能会错过新功能。建议每隔一段时间跑一次impeccable init让规则文件同步到最新版本。8.3 给新手的上手建议如果你刚开始用 impeccable我的建议是先用默认规则跑一遍完整流程感受一下效果。不要一上来就自定义规则那样容易陷入细节。等熟悉了基本用法再根据自己的需求逐步调整。另外建议把 impeccable 跟版本控制结合起来。.impeccable文件夹纳入 git 管理这样团队里每个人用的都是同一套规则。如果有人改了规则其他人拉取代码后自动生效不需要额外沟通。最后不要指望 impeccable 能解决所有设计问题。它是一个辅助工具帮你把 AI 生成的代码从“能用”提升到“好看”但真正的设计决策还是需要人来把关。把它当作一个靠谱的助手而不是替代品。
