Impeccable：为 AI 编程助手补上前端设计工作流

使用 AI 编写前端页面时，功能实现通常不是唯一的难点。页面可能可以运行，却依旧存在视觉同质化、信息层级不清晰、响应式细节不足、交互状态不完整等问题。

直接让 AI“把页面做得更漂亮”，结果往往取决于提示词是否具体、模型是否理解产品，以及开发者愿意花多少轮时间反复调整。

Impeccable 是一个试图改善这一过程的开源项目。它为 AI 编程助手提供设计指导、可调用的工作流命令、确定性界面检测工具，以及与部分编程工具集成的自动反馈和浏览器视觉迭代能力。

它并不是一个 UI 组件库，也不是新的前端框架。更准确地说，Impeccable 是一套帮助 AI 更系统地完成前端设计与质量改进工作的工具集。

项目主页：pbakaus/impeccable

一、Impeccable 解决什么问题？

AI 生成的界面有时会出现一些熟悉的套路：紫蓝渐变、过度使用的字体、层层嵌套的卡片、缺少节奏变化的间距，以及看起来精致却与产品定位关系不大的装饰元素。

这些做法并非在任何情况下都错误，但当它们成为默认答案时，不同产品的视觉表达就容易趋同。

除此以外，页面在工程层面也可能存在问题，例如文本溢出、触控目标过小、对比度不足、响应式布局不稳定，或者没有覆盖加载失败和空数据等状态。

Impeccable 希望把这些问题放进一个可以反复使用的工作流中：

理解产品、目标用户和页面的使用场景。
在编写代码之前明确页面目标与设计方向。
实现界面，并尽量遵循项目现有的设计系统。
通过检测器发现一部分明确的设计和实现问题。
使用 AI 判断检测结果、修正问题，并在浏览器中检查实际效果。

核心目标不只是让 AI 生成页面，而是让它在设计、实现和检查之间形成更稳定的闭环。

二、它由哪些部分组成？

根据项目 README，Impeccable 的主要组成包括一个设计 Skill、24 个命令、62 条确定性检测规则，以及用于浏览器视觉迭代的相关能力。具体数量与功能可能随版本调整，使用时应以仓库当前版本为准。

1. 设计 Skill：向 AI 提供工作方法

Skill 定义了 AI 在处理前端界面任务时应遵循的指导原则和步骤。例如，它要求 AI 理解产品需求、检查已有组件和视觉体系，并根据任务类型选择合适的设计方法。

Skill 并不等于一个新的模型。实际的设计判断大多仍由当前使用的 AI 模型完成，Impeccable 提供的是额外的上下文、方法和任务路由。

2. 命令系统：把设计任务拆成可调用的动作

Impeccable 将常见的设计任务整理成统一命令入口。开发者可以针对页面规划、审查、排版、布局或上线前检查选择合适的命令，而不必每次从零编写完整提示词。

3. 确定性检测器：检查能够明确识别的问题

检测器通过规则扫描支持的前端文件或页面，识别一部分常见的 UI 反模式和质量问题。它与 AI 的自由判断不同：确定性规则可以在相同输入和配置下重复执行，并输出结构化结果。

4. Hooks：把检测接入 AI 编程过程

在受支持的开发工具中，Impeccable 可以在编辑相关文件后运行检测，并将发现的问题反馈给 AI。这样，部分问题能够在当前任务上下文中得到修复，而不是等到开发者手动审查时才暴露。

5. 浏览器视觉迭代：检查真实渲染结果

对于需要反复调整的页面，Impeccable 还提供了视觉变体和浏览器迭代相关工作流。开发者可以围绕指定区域尝试不同方向，再根据实际页面效果进行取舍。

不同功能依赖的工具和运行环境并不完全相同；安装 Skill 不应被理解为所有自动化功能都会在所有宿主工具中自动可用。

三、常用命令有哪些？

Impeccable 通过统一入口调用命令：

/impeccable <command> <target>

下面列出一些常用命令及其用途。

命令	主要用途
`/impeccable init`	收集产品背景和约束，并生成`PRODUCT.md`
`/impeccable document`	根据现有项目整理`DESIGN.md`
`/impeccable shape`	在编写代码前规划 UX/UI
`/impeccable critique`	评估页面的信息层级、清晰度和用户体验
`/impeccable audit`	检查无障碍、性能、响应式等技术质量问题
`/impeccable polish`	在交付前做一轮设计质量收尾
`/impeccable distill`	精简不必要的视觉复杂度
`/impeccable harden`	补充错误处理、国际化、文本溢出和边界状态
`/impeccable layout`	改善布局、间距和视觉节奏
`/impeccable typeset`	调整字体、字号和排版层级
`/impeccable colorize`	为界面引入有目的的色彩
`/impeccable clarify`	改进标签、提示和错误文案的清晰度
`/impeccable adapt`	为不同设备和屏幕适配界面
`/impeccable optimize`	关注性能改进
`/impeccable animate`	增加有明确目的的动画与动效
`/impeccable live`	进行浏览器中的视觉变体迭代
`/impeccable generate`	为指定元素生成可比较的视觉变体

实际可用命令和具体行为以当前安装版本为准。输入 /impeccable 通常可以查看命令入口与提示。

例如，对一个已有的管理后台页面进行优化，可以先执行：

/impeccable critique settings

了解页面问题之后，再决定是否需要布局调整、文案改进或最后的精修：

/impeccable layout settings
/impeccable polish settings

这种方式的优点是把“页面不好看”拆成更明确的任务，减少一次性大幅改动造成的不可控性。

四、62 条检测规则能做什么？

Impeccable 不只通过提示词告诉 AI 应当注意哪些问题，还提供独立的检测引擎。项目 README 介绍了 62 条确定性检测规则，覆盖 AI 生成界面中常见的视觉套路及一些通用界面质量问题。

常见检测方向包括：

类别	示例
视觉反模式	渐变文字、装饰性发光、某些常见渐变配色和强调边框
字体与排版	过度常见的字体、标题与正文缺乏层级变化
布局与间距	卡片嵌套、间距单调、内容过于拥挤
色彩与可读性	文本对比度不足、特定颜色组合的可读性问题
动效	不必要的弹跳或弹性缓动、某些布局属性的过渡
基础质量	文本过长、触控目标太小、标题层级或页面结构问题

在安装了 CLI 的环境中，可以扫描本地前端目录：

npx impeccable detect src/

查看机器可读的结果：

npx impeccable detect --json src/

查看检测规则目录：

npx impeccable detect --list-rules

根据 README，确定性检测本身不需要调用 LLM，也不需要单独的模型 API Key。扫描网页 URL 则可能需要本机可用的 Chrome、Chromium 或 Edge 等浏览器环境。

检测结果不等于绝对设计标准

这里需要特别说明：规则引擎能够识别某些模式，却无法仅凭一条规则判断整个设计是否优秀。

例如，项目可能因为品牌规范而必须使用某种字体；某个渐变也可能是视觉识别的一部分；数据密集型页面也不一定能够完全消除容器嵌套。

因此，正确的做法不是无条件满足每一条规则，而是检查问题是否真实存在，并结合产品目标、品牌规范和具体使用场景作出判断。Impeccable 也支持针对明确的例外设置规则忽略项。

五、插件、Skill、检测规则与 Hook 的边界

理解各个部分的职责，有助于避免对 Impeccable 的能力产生误解。

部分	负责什么	不代表什么
插件/安装包	将 Skill、相关文件及受支持的集成配置安装到开发环境	不代表自动启用所有功能，也不代表它是一个独立的大模型
Skill 与命令	指导 AI 如何理解需求、规划设计、执行审查，并将任务路由到相应指令	不等同于确定性检测器，也不能保证模型每次都做出正确判断
确定性检测规则	对支持的代码或页面执行可重复的检查并报告问题	不是完整的审美评估，也不保证覆盖所有 UI 缺陷
Hooks	在支持的工具和事件中触发检测，并将结果反馈到 AI 工作流	不等同于编译器、测试套件或强制性的 CI 质量门禁
浏览器视觉迭代	帮助开发者基于真实渲染结果比较并调整界面	不代表每一种安装方式都自动具备完整的浏览器控制能力

简单来说：Skill 负责指导 AI 怎么做，规则负责检查一部分明确的问题，Hook 负责把检查接入工作流，安装机制负责把这些能力部署到具体工具中。

它们彼此配合，但不能互相替代。

六、如何在 Claude Code 中进行项目级安装？

推荐先进入准备启用 Impeccable 的项目根目录，再使用官方 CLI 安装器。

1. 安装到当前项目

cd your-project
npx impeccable install -y --providers=claude --scope=project

参数含义：

--providers=claude：为 Claude Code 安装。
--scope=project：选择项目范围，而不是直接为所有项目配置。
-y：自动确认安装过程中的常规确认项。

如果你希望先查看安装器识别到了哪些工具与目录，也可以不加 -y，交互确认提供方和安装范围：

npx impeccable install

安装完成后，重新加载或重启 Claude Code。首次使用时运行：

/impeccable init

这一步用于建立产品上下文，而不是直接开始修改页面。

2. 检查自动检测 Hook

CLI 安装器在受支持的环境中也会配置对应的 Hook。安装后可以查看状态：

/impeccable hooks status

启用当前项目的检测：

/impeccable hooks on

关闭检测：

/impeccable hooks off

在 Claude Code 中，可以打开 /hooks 检查已加载的 PostToolUse 和 Stop Hook，并按工作区信任提示进行授权。具体配置位置和权限行为以实际安装版本为准。

3. 如果只想使用 Skill，不想安装 Hook

可以在安装时明确禁用 Hook 配置：

npx impeccable install --providers=claude --scope=project --no-hooks

这样可以先体验命令和设计指导，再决定是否需要自动检测。

4. 更新

更新已有安装可以使用：

npx impeccable update

更新后应重新检查 Hook 状态；如果工具提示需要重新确认或授权，应先阅读相关配置再接受。

完整安装指南见官方 README：Impeccable Installation。

七、PRODUCT.md、DESIGN.md 与项目上下文

Impeccable 不希望 AI 每次执行设计任务时都从零猜测产品背景。它使用不同文档保存不同类型的长期信息。

`PRODUCT.md`：记录产品事实

例如：

产品主要服务哪些用户。
产品解决什么问题。
用户在什么环境和场景中使用它。
业务限制、内容要求和品牌约束是什么。
哪些内容有真实依据，哪些内容不能凭空编造。

这些信息决定设计应该服务于什么目标。

`DESIGN.md`：记录视觉系统

例如：

使用的字体与字号层级。
色彩、间距和圆角规范。
现有组件与视觉表达方式。
哪些设计决策需要在不同页面之间保持一致。

这些信息帮助 AI 延续项目的既有风格，而不是在每个页面中重新发明一套设计。

初始化产品上下文可以执行：

/impeccable init

如果项目已有页面，希望提取当前的视觉规范，可以执行：

/impeccable document

产品背景与视觉规范是两个不同概念。缺少 DESIGN.md 并不意味着现有项目没有设计体系；已有的代码、组件和资产同样可能包含明确的视觉规则。

八、推荐的实际工作流

对于 Vue 3、Nuxt 或其他前端项目，我建议采用循序渐进的方式。

新页面

用 /impeccable init 建立产品背景。
明确页面目标、用户任务和必须保留的内容。
使用 /impeccable shape 等命令先规划设计方向。
实现页面，并检查实际渲染结果。
执行 /impeccable critique 或 /impeccable audit，按优先级修复问题。
在交付前执行 /impeccable polish。

已有页面改版

先阅读项目的产品资料、组件、样式和设计文档。
通过 /impeccable critique 找到当前页面的主要问题。
明确改版范围，不随意替换用户没有要求修改的内容。
分批调整布局、排版、色彩和交互状态。
检查不同屏幕尺寸和关键状态，并运行检测器。
检查 Git 变更，确认没有无关改动。

在编码过程中使用自动检测

如果 Hook 已正确启用，检测器可以在相关文件变更后提供反馈。它适合发现一部分明确的问题，但仍应结合构建、测试、浏览器验收和人工判断。

九、它适合哪些场景？

比较适合：

使用 AI 开发官网、产品落地页和展示型网站。
使用 AI 开发管理后台、仪表盘、表单和配置页面。
希望多个页面遵循统一设计系统的中小型前端项目。
希望在 AI 生成代码时自动发现部分 UI 质量问题的团队。
需要反复比较页面视觉方向并根据真实渲染效果迭代的项目。

价值相对有限的场景：

纯后端 API、数据库迁移等不涉及界面的任务。
页面极少、设计要求非常简单，且没有持续 UI 迭代需求的项目。
项目已经拥有严格的设计检查与视觉回归体系，且现有流程能够覆盖同类问题的场景。

工具越完整，并不代表越适合每个项目。可以先从 Skill 和手动审查开始，只有在自动反馈能够明显减少重复劳动时，再启用 Hook。

十、局限与注意事项

1. 设计规则带有判断边界

常见设计模式不是天然错误。规则引擎只能提供发现，不能替代产品定位、品牌规范与设计判断。

2. 不应把“避免套路”理解为强制追求另类

好的设计不等于刻意避开所有常见组件。熟悉的交互模式往往能够降低用户的学习成本。设计是否合适，应该由产品目标与用户场景决定，而不是为了追求独特而牺牲可用性。

3. 自动检测不能代替完整质量保障

检测器不能覆盖所有浏览器兼容问题、业务逻辑缺陷和真实用户体验问题。项目仍然需要构建检查、自动化测试、无障碍验证和必要的人工验收。

4. 注意安装范围与配置文件

项目级安装会写入当前仓库相关配置，但不同宿主工具的 Hook 清单、信任机制以及本地配置文件可能不同。执行安装或更新前，应检查现有配置；不要直接覆盖项目原有的设置。

5. 让规则例外保持具体

如果某个字体或动效是经过确认的品牌选择，建议只忽略对应的规则和值，并说明原因。不要因为一个误报就关闭所有检测规则。

十一、总结

Impeccable 的核心价值，是把前端设计中的一部分经验和流程变成 AI 编程助手可以反复使用的工具。

它不仅给 AI 提供设计指导，还结合命令系统、确定性检测、自动 Hook 和浏览器迭代，形成从规划、实现到检查的工作流程。

对经常使用 AI 编写 Vue、Nuxt 或其他 Web 界面的开发者来说，它值得一试，尤其是在页面视觉同质化、设计规范难以保持一致，以及缺少稳定 UI 检查流程的项目中。

但它并不是“自动生成完美 UI”的保证。最有效的方式仍然是先明确产品目标和设计约束，再让工具辅助发现问题，最后结合浏览器实际效果、测试和开发者判断完成交付。

项目地址：https://github.com/pbakaus/impeccable

官方文档：https://impeccable.style/docs/