Impeccable：给 AI 编码工具装上「设计之眼」

🎨 场景切入：AI 生成的界面，为什么总是「差点意思」？

你用过 AI 编程工具生成过一个 Dashboard 吗？代码能跑，逻辑正确，但一眼看过去就是觉得——平庸。卡片套卡片、紫色渐变标题栏、清一色的 Inter 字体、永远居中的内容块，所有 AI 生成的前端似乎都在模仿同一套「模板」。这背后的原因很简单：AI 是在大量现有代码上训练出来的，它学到的是设计「公约数」，而非设计「个性」。

Impeccable 正是为解决这个痛点而生。它不是又一个 UI 组件库，而是一套专门给 AI 看的「设计规范手册」——让 AI 在生成代码之前，先学会「什么是好的设计」。

📖 背景：一个人做的开源项目，GitHub 48 小时狂揽 5 万星

Impeccable 由 Google 前端架构师 Paul Bakaus（曾主导 jQuery UI 和 Chrome DevTools UI 重构）于 2025 年 11 月创建。项目上线仅两天即获得 5 万+ GitHub Stars，创造了开源史上最快的增长纪录之一。其设计理念源于 Anthropic 官方发布的 frontend-design skill，Paul 在此基础上进行了系统性扩展，融入了更多元的检测规则和跨平台支持。

图1：Impeccable 项目图标与品牌视觉

💡 类比：它更像是 AI 前端的「拼写检查器」

如果说代码审查工具（ESLint、Prettier）是检查「语法正确性」的拼写检查器，那么 Impeccable 就是检查「设计正确性」的拼写检查器。它内置了 58 条确定性检测规则，涵盖 AI 生成前端的典型「劣质特征」（俗称 AI Slop），让 AI 在交付代码前先过一遍「设计质量关」。

对于开发者来说，它的作用类似于：汽车出厂前的「质检员」，不改变车的结构，但会标记出每一个影响体验的小毛病。

⚙️ 核心功能：1 个 Skill，23 条命令，58 条检测规则

3.1 跨 Agent 平台的 Skill 系统

Impeccable 提供了统一的 impeccable Skill，可直接注入到 Claude Code、Cursor、GitHub Copilot、Gemini CLI、Codex CLI 等主流 AI 编程工具中。安装方式极其简单：

# 一键安装（自动识别平台）
npx impeccable install

# 或指定平台
npx impeccable install --providers=claude,cursor

安装后，AI 在每次设计任务前会自动加载 PRODUCT.md（产品规范）、DESIGN.md（设计系统规范）和对应的命令路由，获得完整的设计上下文。

3.2 23 条内置命令

Skill 内置 23 条命令，覆盖设计工作全生命周期：

命令	用途
/impeccable init	初始化项目设计规范
/impeccable audit	设计质量审查
/impeccable polish	润色优化现有 UI
/impeccable critique	批判性评审
/impeccable new	从零创建新界面
/impeccable teach	交互式设计指导
/impeccable hooks	自动检测已编辑文件
/impeccable doctor	检查规范文件一致性

3.3 CLI 离线检测器

不依赖 AI，直接通过命令行扫描文件或 URL：

# 扫描本地文件
npx impeccable detect src/

# 扫描线上页面（需 Puppeteer）
npx impeccable detect https://example.com

# JSON 输出用于 CI 集成
npx impeccable detect --json src/ > findings.json

CLI 引擎采用 3 层检测架构：

• 正则引擎（Regex）：极速模式，扫描 HTML/CSS/JSX/TSX/Vue/Svelte 文件
• JSDOM 引擎：解析 DOM 结构，检测元素嵌套、类名冲突
• 浏览器引擎（Browser）：Puppeteer 驱动，捕获运行时样式和动态内容

图2：项目作者 Paul Bakaus（GitHub @pbakaus）

3.4 58 条检测规则分类

AI Slop Tells（AI 生成特征）：检测紫色渐变文字、紫色/青色暗色系调色板、边框+圆角冲突等典型 AI 风格。

Typography（字体排版）：检测 Inter/Roboto 字体过度使用、扁平字体层级、单字体族等问题。

Color & Contrast（色彩对比）：WCAG AA 合规性、灰色文字在彩色背景上的可读性、纯黑/纯白的使用规范。

Layout & Composition（布局构图）：嵌套卡片、单调间距、全居中布局等设计反模式。

Motion（动效）：弹跳/弹性缓动、layout 属性过渡等性能隐患。

Quality（质量）：小字号正文、拥挤内边距、超长行长度、小触摸目标等可访问性问题。

🚀 上手门槛：零配置，即装即用

Impeccable 几乎没有学习曲线。安装 npx impeccable install 后，在 AI 编码工具中直接输入 /impeccable init 即可初始化设计规范。之后每一次 UI 设计任务，AI 都会自动遵循规范，无需人工干预。

唯一的前置要求是 Node.js >= 22.12.0（用于 CLI），Skill 本身通过各平台的原生 Skill 机制加载，不需要额外的运行环境。

⚖️ 争议与局限

设计风格固化的风险：Impeccable 的规则库基于西方设计语境，可能不适合所有地区的审美习惯。东亚市场的扁平化、极简主义与西方略有差异，过度依赖 Impeccable 可能导致设计同质化从「AI 风格」转向「Impeccable 风格」。

规则优先级不透明：58 条规则之间可能存在冲突，文档中对优先级描述较少，用户需要手动调整或忽略某些规则。

对非前端任务无效：Impeccable 专注于前端 UI，对后端逻辑、移动端原生界面、游戏 UI 等领域完全无能为力。

🌟 行业意义：AI 前端质量的里程碑

Impeccable 的出现标志着 AI 前端开发从「能跑就行」到「追求质量」的分水岭。在 2025 年末这个节点，AI 生成代码的能力已经不是瓶颈，瓶颈在于如何让 AI 理解「什么是好的设计」。Paul Bakaus 的思路是：不改变 AI 的训练数据，而是给它提供一套可注入的设计规范层——这是一个聪明且务实的工程选择。

从技术架构看，Impeccable 的分层设计（源 Skill → 各平台 SKILL.md → 命令路由 → 参考文档）也为其他领域的 Agent 规范设计提供了范本。

截至 2026 年 7 月，项目已获 49,384 Stars，是当前 GitHub 上增长最快的 AI 开发者工具之一。

🔧 技术架构解析

目录结构

impeccable/
├── skill/              # Skill 源文件（所有平台的 SKILL.md 生成自此）
│   ├── SKILL.src.md    # Skill 主定义 + 命令路由表
│   ├── reference/      # 各命令的详细参考文档
│   └── scripts/        # 构建脚本（含平台 transformer）
├── cli/                # CLI 引擎（独立于 AI 平台运行）
│   ├── bin/cli.js      # CLI 入口
│   ├── engine/         # 检测引擎
│   │   ├── engines/    # 正则/JSDOM/浏览器三层引擎
│   │   ├── registry/   # 58 条检测规则注册表
│   │   ├── rules/      # 各类别规则实现
│   │   └── shared/     # 颜色/字体/页面等共享工具
│   └── lib/            # 工具库
├── extension/           # Chrome 浏览器扩展（视觉辅助）
└── site/               # 官网（https://impeccable.style）

核心技术栈

• Node.js ESM 模块：package.json 中明确要求 Node.js >= 22.12.0
• 纯 JavaScript/TypeScript：无前端框架依赖，CLI 工具链极轻量
• JSDOM：服务端 HTML 解析
• Puppeteer：浏览器自动化检测
• Bun：开发阶段使用 Bun 作为包管理器和运行时

代码质量

Impeccable 的代码质量相当高：文档覆盖完整（CLAUDE.md 高达 35KB），AGENTS.md 明确说明了贡献规范，DESIGN.md 包含完整的设计 token 系统。测试覆盖在 tests/ 目录中，通过 fixture 验证各类规则行为。