Impeccable 下载安装及使用

1. 概述与核心理念

1.1 什么是 Impeccable？

Impeccable 是一个面向 Claude Code 的前端设计技能包，将 AI 的设计能力从"够用"提升到"卓越"。它适用于：

网站 --- 落地页、营销站、产品首页
应用 UI --- 仪表盘、编辑器、管理后台、设置页
组件 --- 表单、按钮、卡片、空状态、引导流程
设计系统 --- 设计令牌、组件库、设计规范

不适用于后端代码或非 UI 任务。

1.2 三条核心原则

原则	含义
全力以赴 (Go all out)	不妥协、不走捷径。交付物必须完整。
大胆梦想 (Dream big and bold)	独特、美丽、出众、高度启发性的作品。
工具迭代 (Iterate with tools)	利用截图、浏览器预览等工具反复打磨，直到达到标准。

1.3 命令速查表

命令	类别	一言描述
`/impeccable shape`	构建	编码前规划 UX/UI
`/impeccable init`	构建	创建 PRODUCT.md
`/impeccable document`	构建	生成 DESIGN.md
`/impeccable extract`	构建	提取可复用令牌和组件
`/impeccable critique`	评估	UX 设计评审
`/impeccable audit`	评估	技术质量审计
`/impeccable polish`	精炼	发布前最终质量检查
`/impeccable bolder`	精炼	增强平淡设计
`/impeccable quieter`	精炼	降低激进设计
`/impeccable distill`	精炼	精简至本质
`/impeccable harden`	精炼	生产就绪加固
`/impeccable onboard`	精炼	设计引导流程
`/impeccable animate`	增强	添加有目的的动效
`/impeccable colorize`	增强	添加战略性色彩
`/impeccable typeset`	增强	改善字体排版
`/impeccable layout`	增强	修复间距和层级
`/impeccable delight`	增强	添加个性和记忆点
`/impeccable overdrive`	增强	突破常规极限
`/impeccable clarify`	修复	改善 UX 文案
`/impeccable adapt`	修复	适配不同设备
`/impeccable optimize`	修复	优化 UI 性能
`/impeccable live`	迭代	浏览器实时变体迭代

2. 快速入门

2.1 首次使用

在 Claude Code 中，通过 /impeccable 前缀调用：

复制代码

/impeccable

不带参数运行时，Impeccable 会分析项目上下文，给出智能化的 2-3 条推荐命令。例如：

项目没有 PRODUCT.md → 推荐 /impeccable init
项目有代码但没有 DESIGN.md → 推荐 /impeccable document
从未做过设计评审 → 推荐 /impeccable critique
开发服务器正在运行 → 推荐 /impeccable live

2.2 基础配置

大多数命令在首次运行时，Impeccable 会自动通过 context.mjs 加载项目上下文，无需手动配置。但对于 Live 模式，需要确保：

项目有运行的开发服务器（支持 HMR）
或项目是静态 HTML 文件

2.3 命令格式

复制代码

/impeccable <命令> [目标]

目标可以是文件路径、URL、组件名或页面路由。例如：

复制代码

/impeccable critique src/pages/index.astro
/impeccable polish src/components/Hero.tsx
/impeccable audit public/index.html

3. 四大设计模式

每个界面都有一个"访客成功模式"。选择正确的模式是设计决策的第一步。

3.1 Persuade（说服）

访客要做出决定并行动；设计就是产品。

适用场景：落地页、营销页面、活动页、定价页。

核心目标：赢得注意力和行动。用真实的图像传达信息，遵循已确立的世界观而非品类惯例。

3.2 Operate（操作）

访客要完成任务。

适用场景：应用 UI、仪表盘、编辑器、管理后台、设置、工具。

核心目标：可扫描性、一致性、原生预期和真实使用场景优先于表达。品牌存在于精确的细节中。

3.3 Read（阅读）

访客要理解内容。

适用场景：文档、文章、指南、帮助页面、更新日志。

核心目标：为理解而结构化，然后让阅读体验值得停留。

3.4 Experience（体验）

访客置身于作品之中。

适用场景：作品集、画廊、展示页。

核心目标：让作品从第一个视口引导一切；界面退居幕后。

重要提示：模式由被请求的界面决定，而非产品。一个工具的落地页仍然是 Persuade；一个时尚品牌的文档仍然是 Read。

4. 命令完整参考

Impeccable 提供 18 个子命令，按功能分为六大类：

4.1 构建类 (Build)

`shape [feature]` --- 规划 UX/UI

在编写代码之前进行 UX/UI 规划。分三个阶段：

发现访谈：1-2 轮结构化提问，了解目的、用户、成果、约束
确定设计方向：通过概念工作坊选择视觉世界
撰写 Brief：输出精炼的设计简报

shape 只规划不实现。完成后应使用 writing-plans 制定实施计划。

`init` --- 初始化产品上下文

捕获持久化的产品真相，生成 PRODUCT.md。包含：

平台（web / ios / android / adaptive）
用户画像和使用场景
产品目的和定位
运营上下文
能力、约束和术语
品牌承诺
已有证据和资产
产品原则
无障碍和包容性需求

首次使用 Impeccable 时，强烈建议先运行此命令。

`document` --- 生成设计系统文档

从现有代码中提取设计令牌和组件，生成 DESIGN.md 和 .impeccable/design.json。

两种模式：

扫描模式（默认）：从 CSS 变量、Tailwind 配置、组件库中自动提取
种子模式：适用于尚无代码的项目，通过工作坊确定视觉方向

`extract [target]` --- 提取可复用令牌和组件

识别重复模式、硬编码值和不一致变体，将其提取为设计系统中的可复用令牌和组件。

4.2 评估类 (Evaluate)

`critique [target]` --- UX 设计评审

执行完整的 UX 设计评审，包含：

双评估机制：评估 A（设计总监视角，包括设计特异性、认知负荷、情感旅程、Nielsen 启发式评分）和评估 B（自动化检测器扫描 + 浏览器可视化），两个评估必须在独立的子代理中并行执行
Nielsen 10 项启发式评分（每项 0-4 分，满分 40）
设计特异性评估：判断界面是否为该产品"定制"还是品类可互换的
认知负荷分析：基于 8 项清单评估心理负担
5 种角色测试：Alex（高效用户）、Jordan（新手）、Sam（无障碍用户）、Riley（压力测试）、Casey（移动端分心用户）
持久化快照 ：评审结果保存到 .impeccable/critique/ 目录，支持趋势追踪

输出 P0-P3 优先级问题和建议的后续命令。

`audit [target]` --- 技术质量审计

从 5 个维度进行可测量的代码级审计（每项 0-4 分，满分 20）：

维度	检查内容
无障碍 (A11y)	对比度、ARIA、键盘导航、语义 HTML、alt 文本
性能	布局抖动、动画性能、资源优化、包大小
主题化	硬编码颜色、暗色模式、令牌一致性
响应式设计	固定宽度、触摸目标、横向滚动、文本缩放
实现完整性	设计系统一致性、反模式检测

注意：critique 关注设计质量（用户体验），audit 关注技术质量（代码实现）。两者互补。

4.3 精炼类 (Refine)

`polish [target]` --- 发布前最终质量检查

系统性打磨整个用户路径：

建立系统基准（读取 DESIGN.md，分类问题）
收集证据（使用功能，读取之前的 critique 快照）
分类修复：
- 优先级 1：功能性缺陷、数据丢失、误导状态
- 优先级 2：缺失的加载/空/错误/成功/禁用状态
- 优先级 3：流程、层级、响应式偏移
- 优先级 4：视觉和动效不一致
- 优先级 5：代码和资源清理

`bolder [target]` --- 增强平淡的设计

放大设计的某一部分，使其匹配周围部分的表达水平。核心原则：

范围至上：只触碰被命名的目标，其他一切保持不变
使用系统已有的语言：放大系统已有的主题动机和字体比例
骨骼测试：去掉文案后，结构本身是否仍能传达核心信息

`quieter [target]` --- 降低过于激进的设计

减少视觉强度但保留个性。"安静"不等于无聊，而是精致和舒适。

关键手段：

降低饱和度（到 70-85%）
用着色的灰色替代纯灰色
减少装饰元素
缩短动效距离和时间
保留核心信息的视觉锚点

`distill [target]` --- 精简至本质

去除复杂性，保留核心。移除视觉噪音、冗余内容和嵌套结构。

`harden [target]` --- 生产就绪加固

处理真实世界的边缘情况：

极端文本长度（100+ 字符的名称）
特殊字符（emoji、RTL、CJK）
国际化（德语比英语长 30%、阿拉伯语 RTL、日期/数字格式）
网络错误状态（offline、timeout、API 错误码）
空状态、加载状态、权限状态
大数据集（1000+ 条目）
并发操作和竞态条件

`onboard [target]` --- 设计引导流程

设计首次使用体验、空状态和激活流程。

4.4 增强类 (Enhance)

`animate [target]` --- 添加有目的的动效

用动效解释状态、关系和层级。核心要求：

确定一个"焦点时刻"作为动效核心
选择表达意义的材质（不只是 transform + opacity）
遵循时间规范（100-150ms 即时反馈，500-800ms 焦点入场）
出口快于入口
尊重 prefers-reduced-motion
内容在默认状态下始终可见

`colorize [target]` --- 为单色 UI 添加战略性色彩

不只是在各处撒颜色。选择色彩策略：

Restrained（克制）：中性色 + 单一强调色
Committed（投入）：一种饱和色占据表面 30-60%
Full palette（全调色板）：3-4 个有命名的角色色
Drenched（浸染）：表面就是颜色本身

`typeset [target]` --- 改善字体排版

修复字体层级、字体配对和排版比例。避免常见的 AI 默认字体选择。

`layout [target]` --- 修复间距和视觉层级

处理间距节奏、网格对齐和视觉层级。

`delight [target]` --- 添加个性和记忆点

在"值得奖励的时刻"注入产品个性：成功确认、等待状态、空状态引导、错误恢复。核心原则：愉悦感必须来自产品机制本身，而非通用的装饰。

`overdrive [target]` --- 突破常规极限

将界面的某个部分推向"技术上非凡"的领域。例如：

百万行数据的虚拟滚动表格
从触发按钮变形而来的对话框（View Transitions API）
实时流式验证的表单
Canvas/WebGL 渲染的数据可视化
滚动驱动的电影级动画

重要：此命令会先提出 2-3 个方向供你选择，不会直接实施。

4.5 修复类 (Fix)

`clarify [target]` --- 改善 UX 文案

修复标签、错误信息和引导文案，使用产品的语言。控件命名其动作，错误命名问题和恢复方式。

`adapt [target]` --- 适配不同设备

处理响应式断点、触摸目标、文本缩放和设备特定行为。适用于 web；原生平台使用 adapt.native.md。

`optimize [target]` --- 诊断和修复 UI 性能

分析并修复渲染性能、包大小和加载速度问题。

4.6 迭代类 (Iterate)

`live` --- 实时视觉变体模式

在浏览器中选择元素，获取 AI 生成的 HTML+CSS 变体，通过 HMR 热替换实时预览。详见第 6 章。

4.7 其他管理命令

命令	说明
`/impeccable hooks <on	off
`/impeccable doctor`	诊断和修复项目 Impeccable 制品的漂移
`pin / unpin`	为常用命令创建独立快捷方式

5. 核心工作流

5.1 标准设计流程

复制代码

/impeccable init          → 捕获产品上下文 (PRODUCT.md)
/impeccable shape <目标>   → 规划 UX/UI 设计简报
/impeccable document      → 提取/建立设计系统 (DESIGN.md)
[实施阶段]
/impeccable critique      → 设计评审
/impeccable audit         → 技术审计
/impeccable polish        → 发布前打磨

5.2 新建视觉世界 (New Work Flow)

当需要创建新界面或更换视觉标识时：

确定已有的真相 --- 读取 DESIGN.md、代码、令牌和组件；判断是重构、扩展还是新建
通过提问明确方向 --- 根据模式（Persuade/Operate/Read/Experience）提出 2-3 个相关问题
选择发明程度 ：
- 扩展现有界面：继承视觉系统
- 在现有世界中创建完整界面：运行概念种子脚本
- 创建或替换视觉世界：7 个具体视觉系统候选 → 概念种子 → 方向决策
确定方向 --- 撰写方向契约（Thesis / Own-World / Story / First Viewport / Form）
可视化方向 --- 在构建前生成设计预览图并获得批准
全力构建 --- 构建选定的方向，不妥协
检查和完成 --- 运行完成评审代理

5.3 方向决策机制

Impeccable 使用独特的"概念种子"机制：

从产品的文化世界导出 7 个具体的视觉系统候选
运行 concept-seed.mjs 脚本随机分配一个方向（防止用户总选最安全的选项）
同时提供 2-3 个候选方向作为替代
用户可按需重新抽选或指定自己的方向
始终提供"品类标准"作为安静的默认退出选项

6. Live 实时迭代模式

Live 模式是 Impeccable 最具特色的功能：在浏览器中直接选择和迭代 UI 元素。

6.1 工作流程

复制代码

用户：/impeccable live
  → live.mjs 启动辅助服务器
  → 打开应用页面

用户在浏览器中：
  1. 点击 Impeccable 图标激活选择模式
  2. 点击任意 UI 元素选中它
  3. 在动作栏中选择操作（bolder, typeset, colorize 等）
  4. 可选：在元素上添加注释和草图
  5. 点击 Go 提交生成请求

Claude（后台）：
  1. 读取元素的 HTML/CSS 和用户注释
  2. 提取身份锁（identity lock）------当前表面的颜色、字体、布局
  3. 生成 3 个在品牌内的变体（带可调参数）
  4. 将变体写入源文件
  5. 浏览器通过 HMR 自动刷新

用户在浏览器中：
  1. 按 1/2/3 键切换变体
  2. 拖动参数滑块实时调整
  3. 点击 Accept 确认变体
  4. 或点击 ✕ 放弃

Accept 后：
  → live-accept.mjs 将选中的变体持久化到源文件
  → 清理临时标记
  → 参数值烘焙到最终 CSS

6.2 身份锁 (Identity Lock)

Live 模式的核心约束：所有变体必须读起来像同一个品牌。

每个变体从 6 个轴中选择一个不同的主轴：

层级 (Hierarchy)
布局拓扑 (Layout topology)
字体系统 (Typographic system)
色彩策略 (Color strategy)
密度 (Density)
结构分解 (Structural decomposition)

6.3 变体参数

每个变体可附带 0-4 个可调参数（由元素大小决定预算）：

元素大小	建议参数数
叶子/微小（单个按钮、图标）	0
小型（标签输入、简单卡片）	0-1
中型（段落组件、导航簇）	目标 2
大型（英雄区、完整页面区域）	2-3，最多 4

三种参数类型：

range ：滑块（驱动 CSS 变量 --p-<id>）
steps ：分段选择（驱动 data 属性 data-p-<id>）
toggle：开关（同时驱动 CSS 变量和 data 属性）

6.4 Steer 模式

Live 模式还支持"Steer"------通过浏览器中的全局栏发送页面级方向指令，无需选中具体元素。支持语音输入（Web Speech API）。

6.5 首次配置

首次运行 live 需要配置 .impeccable/live/config.json。Impeccable 会根据框架自动建议配置：

框架	files	insertBefore
Vite / React (SPA)	`["index.html"]`	`</body>`
Next.js (App Router)	`["app/layout.tsx"]`	`</body>`
SvelteKit	`["src/app.html"]`	`</body>`
Astro	`["<root layout .astro>"]`	`</body>`
多页面站点	`["public/*/.html"]`	`</body>`

如果项目有 CSP（内容安全策略），需要允许 http://localhost:8400。

7. 设计制品管理

Impeccable 维护几个关键制品文件：

7.1 PRODUCT.md

位置：项目根目录

内容：持久化的产品真相------用户、目的、定位、约束、品牌承诺。不包含视觉设计内容。

7.2 DESIGN.md

位置：项目根目录

内容：持久化的视觉设计决策。遵循 DESIGN.md 规范，包含：

复制代码

---
name: 项目名称
colors:
  primary: "#b8422e"
typography:
  display:
    fontFamily: "Cormorant Garamond, Georgia, serif"
components:
  button-primary:
    backgroundColor: "{colors.primary}"
---

8 个规范章节（按顺序）：

Overview（概述 + 创意北极星）
Colors（角色色 + 命名规则）
Typography（字体配对、层级、比例）
Layout（网格、间距、响应式）
Elevation & Depth（阴影词汇、深度策略）
Shapes（圆角、边框、剪裁）
Components（按钮、卡片、输入框等）
Do's and Don'ts（视觉约束）

7.3 `.impeccable/design.json`

DESIGN.md 的机器可读扩展，包含：

色调渐变（tonal ramps）
阴影/动效令牌
断点
完整组件 HTML/CSS 片段（用于 Live 面板渲染）

7.4 表面简报 (Surface Briefs)

某个特定路由或组件的策略，存储为独立的简报文件。包含：范围、访客模式、受众、任务、约束、选定的方向、未解决的决策。

7.5 制品健康检查

使用 /impeccable doctor 检查所有制品的漂移状态。不要在设计任务中作为副作用修复漂移。

8. 工艺底线 (Craft Floor)

工艺底线是 Impeccable 的质量标准------在每个构建完成后必须检查的事项。

8.1 必须验证

项目	标准
对比度	正文 ≥4.5:1，大文字 ≥3:1
深度	阴影有偏移和柔和模糊
间距	紧凑组合，宽松分离，标题上方空间大于下方
字体	正文宽度 65-75ch，展示最大 6rem，字距下限 -0.04em
动效	一个精心设计的时刻，不是分散的效果
状态	hover, disabled, loading, error, empty
文案	控件命名其动作，错误命名问题和恢复方式
覆盖	每个 Brief 要求都存在且可在数秒内找到

8.2 默认禁止

这些是品类的默认模式，不是绝对禁令。当 Brief 明确要求时可以使用。但当方向是自由的，选择它们意味着你没有真正做决定：

页面骨架：

相同尺寸的"图标+标题+文字"卡片作为页面结构
"大数字+小标签+支撑数据+强调色"的英雄指标模板
每个段落上方的紧凑大写引导词
无信息量的章节编号（01/02/03）
用于不需要中断或保护焦点任务的模态框

表面习惯：

渐变文字
装饰性玻璃和模糊效果
超过 1px 的彩色边框
迷你图表、进度环和柔和阴影的圆角矩形占位
"技术感"的等宽字体
因品类默认选择亮色/暗色------应从使用场景出发

9. Hooks 自动检测

9.1 设计检测器 Hook

Impeccable 可以在每次 UI 文件编辑后自动运行检测器：

复制代码

/impeccable hooks on      # 启用
/impeccable hooks off     # 禁用
/impeccable hooks status  # 查看状态

检测器会扫描 HTML/CSS 文件，识别设计反模式（梯度文字、无意义的引导词、卡片嵌套等）。

9.2 忽略规则

可以通过 .impeccable/critique/ignore.md 配置需要忽略的发现。

10. 最佳实践与反模式

10.1 推荐工作流

新项目 ：init → shape → document → 实施 → critique → polish
现有项目改进 ：critique → 根据结果选择适当命令 → polish
快速迭代 ：live（在浏览器中实时调整）
发布前 ：audit + polish

10.2 品牌字体自查

以下字体是训练数据默认值，选择它们需要额外理由：

Fraunces, Playfair Display, Cormorant, Lora, Crimson, Newsreader, Syne, Space Grotesk, Space Mono, IBM Plex, Inter（作为展示字体）, DM Sans, DM Serif, Outfit, Plus Jakarta Sans, Instrument Sans

10.3 常见反模式

反模式	正确做法
跳过 `init` 直接设计	先捕获产品真相，再设计
所有问题都用 `critique`	区分设计问题和技术问题
打磨时偷偷重构	打磨是精炼，不是替代
泛化所有变体	保持品牌身份一致性
跳过 Live 的 Carbonize 清理	遗留 `@scope` 死代码和标记注释
在头显环境中运行 Live 决策	回退到结构化问题工具

10.4 色彩策略选择指南

策略	适用场景
Restrained（克制）	Operate、Read 表面
Committed（投入）	Persuade、Experience 表面
Full palette（全调色板）	品牌建设、复杂系统
Drenched（浸染）	高影响力 Persuade、艺术项目

10.5 安全渲染清单

在声称完成之前：

用鼠标、键盘、触摸走完完整路径
检查移动端、中等和宽布局
检查加载、空、错误、成功、禁用、长内容、缺失内容状态
检查缩放、对比度、焦点、语义和屏幕阅读器名称
检查控制台错误、布局偏移、交互延迟

Impeccable 下载安装及使用

目录

1. 概述与核心理念

1.1 什么是 Impeccable？

1.2 三条核心原则

1.3 命令速查表

2. 快速入门

2.1 首次使用

2.2 基础配置

2.3 命令格式

3. 四大设计模式

3.1 Persuade（说服）

3.2 Operate（操作）

3.3 Read（阅读）

3.4 Experience（体验）

4. 命令完整参考

4.1 构建类 (Build)

shape [feature] --- 规划 UX/UI

init --- 初始化产品上下文

document --- 生成设计系统文档

extract [target] --- 提取可复用令牌和组件

4.2 评估类 (Evaluate)

critique [target] --- UX 设计评审

audit [target] --- 技术质量审计

4.3 精炼类 (Refine)

polish [target] --- 发布前最终质量检查

bolder [target] --- 增强平淡的设计

quieter [target] --- 降低过于激进的设计

distill [target] --- 精简至本质

harden [target] --- 生产就绪加固

onboard [target] --- 设计引导流程

4.4 增强类 (Enhance)

animate [target] --- 添加有目的的动效

colorize [target] --- 为单色 UI 添加战略性色彩

typeset [target] --- 改善字体排版

layout [target] --- 修复间距和视觉层级

delight [target] --- 添加个性和记忆点

overdrive [target] --- 突破常规极限

4.5 修复类 (Fix)

clarify [target] --- 改善 UX 文案

adapt [target] --- 适配不同设备

optimize [target] --- 诊断和修复 UI 性能

4.6 迭代类 (Iterate)

live --- 实时视觉变体模式

4.7 其他管理命令

5. 核心工作流

5.1 标准设计流程

5.2 新建视觉世界 (New Work Flow)

5.3 方向决策机制

6. Live 实时迭代模式

6.1 工作流程

6.2 身份锁 (Identity Lock)

6.3 变体参数

6.4 Steer 模式

6.5 首次配置

7. 设计制品管理

7.1 PRODUCT.md

7.2 DESIGN.md

7.3 .impeccable/design.json

7.4 表面简报 (Surface Briefs)

7.5 制品健康检查

8. 工艺底线 (Craft Floor)

8.1 必须验证

8.2 默认禁止

9. Hooks 自动检测

9.1 设计检测器 Hook

9.2 忽略规则

10. 最佳实践与反模式

10.1 推荐工作流

10.2 品牌字体自查

10.3 常见反模式

10.4 色彩策略选择指南

10.5 安全渲染清单

`shape [feature]` --- 规划 UX/UI

`init` --- 初始化产品上下文

`document` --- 生成设计系统文档

`extract [target]` --- 提取可复用令牌和组件

`critique [target]` --- UX 设计评审

`audit [target]` --- 技术质量审计

`polish [target]` --- 发布前最终质量检查

`bolder [target]` --- 增强平淡的设计

`quieter [target]` --- 降低过于激进的设计

`distill [target]` --- 精简至本质

`harden [target]` --- 生产就绪加固

`onboard [target]` --- 设计引导流程

`animate [target]` --- 添加有目的的动效

`colorize [target]` --- 为单色 UI 添加战略性色彩

`typeset [target]` --- 改善字体排版

`layout [target]` --- 修复间距和视觉层级

`delight [target]` --- 添加个性和记忆点

`overdrive [target]` --- 突破常规极限

`clarify [target]` --- 改善 UX 文案

`adapt [target]` --- 适配不同设备

`optimize [target]` --- 诊断和修复 UI 性能

`live` --- 实时视觉变体模式

7.3 `.impeccable/design.json`