[Github] Impeccable – 面向 AI 编程 Agent 的前端设计与审查 Skill

Github发现2026-10-24发布 WarpEdit

Impeccable 是 Paul Bakaus 开源的前端设计工具，面向 Claude Code、Cursor、Codex 等 AI 编程工具。它把设计上下文、界面评审、定向修改和规则检测放进同一套工作流，让你能明确要求 AI 调整排版、简化布局或检查交互问题。已经有页面、却总觉得“哪里不对”的开发者，可以用它把模糊的修改意见拆成具体任务。

Impeccable 浅色3D概念封面：产品上下文、字体与间距工具连接到前端页面打磨

先把产品说清楚

只告诉 AI“做得高级一点”，很难约束它该保留什么、该改变什么。面向老用户的设置页和面向新访客的宣传页，任务不同，值得强调的信息也不同。Impeccable 从产品上下文开始：init 检查项目，补齐会影响设计的关键信息，并写入 PRODUCT.md，记录受众、用途、使用环境、约束和表达方式。

DESIGN.md 则承载另一类信息：项目已经采用或新确定的视觉系统，包括字体、颜色、组件和布局约定。把产品事实与视觉表达分开后，调整配色不必改掉产品定位，打磨局部页面也有现成规范可依。已有项目还可以用 /impeccable document 从代码中整理设计系统。

它对嵌套卡片、重复的模板化配色、失衡的文字层级等模式有明确检查，但这些规则需要放回具体产品判断。例如品牌已经固定某种字体，就应记录有理由的例外；不能为了消除提示，把整个网站改成另一套风格。

一张原型还不是网页

官方的 Neo Mirai 案例展示了这套流程的一个实际用途：把虚构会议的页面原型和品牌工具包，落实成可以使用的响应式网站。原型与品牌工具包由 GPT Image 2 生成，先确定开场大图、议程、讲者、展示区和票务区的顺序与比例。

Impeccable 官方 Neo Mirai 案例的完整页面原型，包含会议首屏、议程、讲者、展示区与票务布局 — 官方 Neo Mirai 案例的页面原型，题材为虚构会议。

实现时，原图中的城市场景、人物和装饰元素还要重新生成或拆成可用资源；导航、轮播控制、悬停状态和不同屏幕布局，也需要写进页面。这些工作解释了 Impeccable 为什么同时关注视觉方向、实现和浏览器迭代：一张原型图可以交代构图，却交代不了所有交互状态。

同一案例的实际页面延续了原型的大幅开场图、深色议程区和橙色内容带。官方说明，浏览器检查帮助发现并修正了遮挡、裁图、导航状态和讲者轮播等问题。下面是官方提供的页面首屏，便于观察原型怎样进入实际页面；这些素材不代表本文进行了复现测试。

Impeccable 官方 Neo Mirai 案例的实际页面首屏，以城市主视觉配合会议标题、导航及下方议程区域 — 同一官方案例的实际页面首屏，延续原型的开场构图。

验收这类页面时，内容是否完整、窄屏下能否阅读、交互入口是否能完成任务，都需要检查。Impeccable 的 polish 也明确要求检查真实使用路径，并处理局部视觉细节。

安装后先选一种任务

使用官方推荐的安装器时，需要 Node.js 18.19.0 或更高版本。在实际前端项目的根目录运行：

npx impeccable install

安装器会列出检测到的编程工具，让你选择目标工具及项目级或全局安装范围，并在支持的平台询问是否安装自动检查 Hook。随后重新加载对应编程工具，在 Claude Code 等使用斜杠命令的工具里运行：

/impeccable init

Codex 使用 /skills 或 $impeccable 入口调用这项 Skill；如果启用了项目 Hook，还需要在安装或更新后打开 /hooks，按提示批准。技能能被发现与自动 Hook 获准运行，是两件需要分别确认的事。

对于已经存在的页面，先明确当前问题，再选择对应命令：

当前要解决什么	入口	用途
页面重点不清楚、使用起来费解	`critique`	从层级、清晰度和使用体验提出设计评审
无障碍、响应式或实现质量有问题	`audit`	整理技术检查结果，先记录问题
内容和结构太复杂	`distill`	简化页面，保留核心任务
方案已确定，需要交付前收尾	`polish`	按现有设计系统打磨状态、布局和交互

例如要整理设置页，可以先运行 /impeccable critique settings，把评审中的具体问题作为下一步输入。若问题确实是层级过多，再要求 /impeccable distill settings，并说明必须保留的字段和保存行为；最后用 /impeccable polish settings 检查完成状态。这里的 settings 是目标区域描述，使用时替换为自己项目里明确的页面、组件或路径。

audit 的职责是生成检查报告，不直接修复；polish 则要求保留已有视觉方向、内容、行为和范围外部分。如果连概念都需要更换，应明确提出重新设计。把这些边界说清楚，才能避免一次局部调整变成整页重做。

检测器能查到什么

独立 CLI 检测器可以直接扫描源码或已渲染页面，不需要先开启 AI 对话，也不需要 LLM API Key。例如在项目根目录扫描前端源码，并保存机器可读结果：

npx impeccable detect --json src/ > findings.json

结果会给出规则及相关代码或元素位置。它能识别一批确定性的设计与实现问题，例如文本溢出、过小的触控目标、标题层级跳跃，以及部分常见模板化样式；有 DESIGN.md 和相应结构化设计记录时，还可以检查设计系统偏差。源码扫描与 URL 扫描使用的证据不同：前者看代码和样式，后者还可检查渲染后的布局。

在脚本或 CI 中使用时，要区分三种退出码：0 表示扫描完成且没有主要发现，2 表示扫描完成但有主要发现，1 表示至少一个目标没有成功扫描。附加建议可能仍会出现，不能只根据终端有没有文字判断成败。

检测器通过，只能说明这组检查没有报告主要问题。页面是否易懂、是否适合用户任务、视觉方向是否贴合产品，还需要评审和实际查看。品牌字体等有意选择可以按具体值、文件或规则记录例外，保留其他检查；不必为了得到零提示关闭整套检测。

浏览器迭代的边界

live 和 generate 用于在浏览器中围绕具体元素迭代视觉方案。可写回的 Live 模式需要本地源码，以及开发服务器或本地静态 HTML。线上网站则可以通过 detect URL 或浏览器扩展做检查，不能据此直接把生产站点接成可写的实时编辑环境。

安装后的 Hook 会在支持的平台把编辑后的检测发现反馈给 Agent。它通过随 Skill 提供的启动器运行独立引擎；引擎可能随包提供，也可能在第一次运行时下载到本地缓存。只想手动检查时，安装器提供 --no-hooks 选项，不必把自动检查作为所有项目的前提。

设计命令仍由你所用编程工具的模型执行，相应用量按该工具计算；独立检测器无需模型，并不等于所有设计流程都不消耗模型或图片生成用量。视觉方向选样也会请求 Impeccable 的服务。项目方说明，默认匿名记录选样与选择信息，不发送项目名称、文件或源码；可以运行 npx impeccable telemetry off 关闭记录，但选样请求本身仍会发生。

截至 2026 年 10 月 24 日核验，Skill 与 CLI 的最新公开版本均为 4.7.0，发布于 10 月 19 日；仓库主分支在 10 月 23 日仍有提交。项目采用 Apache 2.0 许可证，第三方来源另见仓库 NOTICE。本文依据官方仓库、文档和案例整理，未在本机安装或验证整套工作流。