Impeccable：让 AI 生成的前端设计不再「千篇一律」

今天在 GitHub Trending 上看到一个有意思的项目：Impeccable，它直击一个很多开发者都有体会、但很少有人系统解决的问题——AI 生成的前端界面为什么看起来都长得一模一样？

一、项目概述

Impeccable 是由 Paul Bakaus（jQuery UI 联合创始人、前 Google 产品经理）开发的一套设计技能包（Design Skill），专为 AI 编程助手（Cursor、Claude Code、Copilot 等）打造。它的核心目标是：让 AI 生成的前端代码和 UI 设计具备真正的设计感，而不是千篇一律的「SaaS 模板脸」。

项目在 GitHub 上开源（Apache 2.0 协议），配套官网 impeccable.style。

它解决的核心问题：

所有主流 AI 模型都在相同的 SaaS 模板数据集上训练，导致每次生成的前端界面都会出现这些「AI 痕迹」：

所有文字都用 Inter 字体
紫到蓝的渐变背景
卡片套卡片的嵌套结构
彩色背景上的灰色文字（可读性问题）
每个标题上方都有一个圆角方形图标磁贴

Impeccable 通过注入设计领域知识和显式反模式规则，把这些「AI 通病」系统性地消灭。

核心特性一览：

📚 7 大设计领域参考文件（Typography、Color、Spatial、Motion、Interaction、Responsive、UX Writing）
🔧 23 条设计命令（polish / audit / critique / distill / animate 等）
🚫 27 条确定性反模式规则 + 12 条 LLM 评判规则
🔌 支持 11 款主流 AI 编程工具（Cursor、Claude Code、Gemini CLI、Codex CLI 等）
🖥️ 独立 CLI 工具，无需 LLM API 即可检测反模式

二、技术原理

架构设计

Impeccable 的本质是一个上下文注入系统。它不直接生成 UI，而是通过将结构化的设计知识文件注入 AI 的上下文窗口，改变 AI 的「设计决策边界」：

用户 Prompt
    ↓
AI 编程助手（Cursor/Claude Code/...）
    ↓
注入 Impeccable Skill（7 大设计参考文件）
    ↓
AI 生成的前端代码/设计
    ↓
反模式检测（确定性规则 + LLM 评判）

7 大设计参考文件

Skill 的核心是位于 skill/ 目录下的 7 个参考文件，每次 AI 执行设计相关命令时都会自动加载：

参考文件	覆盖领域	关键设计决策
`typography.md`	字体系统、字体搭配、模块化比例、OpenType 特性	禁止默认 Inter；推荐使用衬线+无衬线组合
`color-and-contrast.md`	OKLCH 色彩空间、着色中性色、暗黑模式、可访问性	禁止纯黑/纯灰；使用 OKLCH 而非 HSL
`spatial-design.md`	间距系统、网格、视觉层次	8px 基础网格；禁止随意间距
`motion-design.md`	缓动曲线、交错动画、减弱运动	禁止 bounce/elastic 缓动（过时感）
`interaction-design.md`	表单、焦点状态、加载模式	禁止缺失焦点状态
`responsive-design.md`	移动优先、流式设计、容器查询	禁止固定宽度断点
`ux-writing.md`	按钮文案、错误信息、空状态	禁止「点击这里」等模糊文案

23 条设计命令的工作方式

所有命令通过统一的入口 /impeccable <command> 调用，每条命令都会：

加载上下文：读取项目的 DESIGN.md（如有）和 7 个参考文件
执行命令逻辑：按照该命令的专业设计流程执行
输出改进建议或直接修改代码

关键命令解析：

/impeccable audit：技术质量检查，覆盖 a11y、性能、响应式。确定性规则不需要 LLM，直接静态分析代码。
/impeccable critique：UX 设计评审，评估层次结构、清晰度、情感共鸣。需要 LLM 进行语义判断。
/impeccable polish：最终润色，对照设计系统对齐，检查发布就绪状态。
/impeccable bolder / quieter：情感调节命令，放大或收缩设计的视觉冲击力。
/impeccable live：可视化变体模式，在浏览器中实时迭代元素。

反模式检测引擎

项目自带独立的 CLI 检测工具，核心引擎位于 cli/engine/detect-antipatterns.mjs：

npx impeccable detect src/              # 扫描目录
npx impeccable detect index.html        # 扫描单文件
npx impeccable detect https://example.com  # Puppeteer 远程扫描
npx impeccable detect --fast --json .   # 仅正则匹配，JSON 输出

检测引擎覆盖 24 个具体问题，分为两类：

AI 痕迹类：侧边栏边框、紫色渐变、bounce 缓动、深色光晕等
通用设计质量类：行宽过长、padding 过挤、触摸目标过小、标题跳跃等

CLI 工具支持三种运行模式：

完整检测（AST 分析 + 正则 + 可选 LLM 评判）
快速模式（--fast，仅正则，无需 LLM，无需 API Key）
浏览器扩展模式（通过 Puppeteer 远程检测线上页面）

技术栈

Astro          → 官网构建（静态站点生成）
Puppeteer      → URL 扫描功能
css-tree       → CSS AST 解析（反模式检测）
htmlparser2    → HTML 解析
marked         → Markdown 渲染
Bun            → 构建脚本运行时

package.json 中可以看到，项目的 main 入口直接暴露了 detect-antipatterns.mjs，意味着其他工具可以通过 require('impeccable') 直接调用检测引擎，实现程序化集成。

三、安装与快速开始

环境要求

Node.js >= 18
支持任意一款 AI 编程助手（Cursor、Claude Code、Gemini CLI 等）

安装方式

方式一：CLI 安装器（推荐）

# 在项目根目录执行，自动检测当前 AI 工具并写入对应目录
npx impeccable skills install

方式二：从官网下载 ZIP

访问 impeccable.style，下载对应工具的 ZIP 包，解压到项目目录。

方式三：手动复制到对应目录

# Cursor
cp -r dist/cursor/.cursor your-project/

# Claude Code（项目级）
cp -r dist/claude-code/.claude your-project/

# Claude Code（全局，所有项目生效）
cp -r dist/claude-code/.claude/* ~/.claude/

# Codex CLI
cp -r dist/agents/.agents your-project/

安装后的最小验证

在 AI 编程助手中输入：

/impeccable

如果看到完整的 23 条命令列表，说明安装成功。

首次使用流程

# 1. 初始化项目设计上下文（生成 PRODUCT.md 和 DESIGN.md）
/impeccable init

# 2. 对当前项目进行设计审计
/impeccable audit

# 3. 对特定页面进行 UX 评审
/impeccable critique landing

# 4. 最终发布前润色
/impeccable polish

四、使用方法与实战

场景一：消除 AI 生成的「模板脸」

用 Cursor 或 Claude Code 生成一个 dashboard 页面后，执行：

/impeccable polish dashboard

Impeccable 会对照设计系统规则，自动识别并修正以下问题：

将所有 Inter 字体替换为更有个性的字体组合
将紫蓝渐变替换为符合品牌调性的色彩方案
消除不必要的卡片嵌套
修复彩色背景上的灰色文字对比度问题

场景二：设计审计 CI/CD 集成

在 CI 流水线中集成反模式检测：

# package.json
{
  "scripts": {
    "lint:design": "npx impeccable detect --fast --json src/ > design-lint.json"
  }
}

配合 --fast --json 参数，可以在 CI 中实现无 LLM 依赖的设计质量检测，输出结构化 JSON 报告。

场景三：可视化实时迭代（Live Mode）

/impeccable live

此命令启动浏览器可视化模式，开发者可以在页面上直接框选元素，AI 实时生成变体供预览和采纳，真正实现「所见即所得」的设计迭代。

进阶技巧：命令固定

如果某条命令使用频率很高，可以用 pin 将其固定为独立快捷命令：

/impeccable pin audit

之后即可直接用 /audit 替代 /impeccable audit，减少输入。

五、常见问题与解决方案

Q1: 安装后 AI 助手识别不到 `/impeccable` 命令？

原因：不同 AI 工具的 skill 加载机制不同，部分需要手动启用。

解决方案：

Cursor：需切换到 Nightly 频道，在 Settings → Rules 中启用 Agent Skills
Gemini CLI：需安装 preview 版本，运行 /settings 启用 Skills
安装后重启 AI 工具

Q2: CLI 检测工具与 Skill 有什么区别？

区别：

Skill（通过 /impeccable 调用）：需要 AI 编程助手，提供设计改进建议和代码修改
CLI（npx impeccable detect）：独立运行，无需 LLM，纯静态分析，适合 CI/CD 集成

两者可以配合使用：CI 中用 CLI 做门禁，/impeccable audit 做深度设计评审。

Q3: 反模式规则会影响 AI 的正常设计发挥吗？

不会。反模式规则定义的是「不要做什么」，而不是「必须怎么做」。AI 仍然有充分的创意空间，只是避开了那些已经被训练数据放大的低质量设计模式。

Q4: 是否支持团队共享设计配置？

支持。/impeccable init 生成的 DESIGN.md 和 PRODUCT.md 可以提交到版本库，整个团队共享同一套设计上下文，确保 AI 为所有团队成员生成风格一致的代码。

Q5: Puppeteer 依赖安装失败（中国大陆网络环境）？

解决方案：puppeteer 是可选依赖（optionalDependencies），检测本地文件和目录时不依赖它。仅在使用 URL 扫描功能时需要。可以设置 npm 镜像或跳过可选依赖安装：

npm install impeccable --no-optional

六、总结

Impeccable 抓住了 AI 辅助前端开发的一个关键痛点：设计同质化。它通过「知识注入 + 规则约束」的双重机制，让 AI 生成的前端代码真正具备设计品质，而不是换汤不换药的模板复读。

适合使用的场景：

用 Cursor/Claude Code 生成前端页面，但受困于「AI 味」太重
需要为团队建立 AI 辅助开发的设计规范
希望在 CI 中加入设计质量门禁

项目活跃度： 当前版本 v2.3.2，持续维护中，拥有完整的测试覆盖和多工具支持。

如果你也在用 AI 写前端，但总觉得生成的界面「差点意思」，Impeccable 值得一试。

一、项目概述#

二、技术原理#

架构设计#

7 大设计参考文件#

23 条设计命令的工作方式#

反模式检测引擎#

技术栈#

三、安装与快速开始#

环境要求#

安装方式#

安装后的最小验证#

首次使用流程#

四、使用方法与实战#

场景一：消除 AI 生成的「模板脸」#

场景二：设计审计 CI/CD 集成#

场景三：可视化实时迭代（Live Mode）#

进阶技巧：命令固定#

五、常见问题与解决方案#

Q1: 安装后 AI 助手识别不到 /impeccable 命令？#

Q2: CLI 检测工具与 Skill 有什么区别？#

Q3: 反模式规则会影响 AI 的正常设计发挥吗？#

Q4: 是否支持团队共享设计配置？#

Q5: Puppeteer 依赖安装失败（中国大陆网络环境）？#

六、总结#