impeccable
Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
1实现原理 · 为什么它能做到
编译式多宿主分发：skill/ 是唯一 master 源（SKILL.src.md + scripts/ + reference/ + agents/），同一时刻仓库内已有 .claude/.cursor/.agents/.gemini 等 20 个宿主目录的编译副本，副本把占位符（{{scripts_path}}/{{command_hint}}…）展开为宿主路径、写入宿主 frontmatter（如 version: 4.3.1、user-invocable、allowed-tools）并剥掉 <!-- rule:… --> 一致性注释。
allowed-tools: - Bash(npx impeccable *) - Bash({{scripts_path}}/impeccable *)
会话启动协议：每会话先跑 `<skill-base-dir>/scripts/impeccable context`（launcher 是 POSIX shell，定位自含引擎二进制），让引擎读入 PRODUCT.md/DESIGN.md/匹配的 surface brief 并把指令（含 CONTEXT_STALE 等 directive）交回 agent；launcher 失败有显式降级——明示后直接读现有 PRODUCT.md/DESIGN.md 继续。
Run `<skill-base-dir>/scripts/impeccable context` once per session, where `<skill-base-dir>` is the directory that contains this SKILL.md (the skill folder, not a plugin root two levels above it); keep cwd at the user's project.
能力核心是随附引擎二进制（非 Node 运行时）：launcher 按序找 IMPECCABLE_BIN → 同目录 bin/<os>-<arch>/ → ~/.impeccable/bin → 版本钉住缓存 → PATH 上的 impeccable，最后兜底从作者 GitHub release 下载该版本二进制到用户缓存并做 sha256 sidecar 校验（fail closed：校验缺失/不符即拒绝执行）。
base="${IMPECCABLE_DOWNLOAD_BASE:-https://github.com/pbakaus/impeccable/releases/download}"
23 命令 + routing 的指令面：SKILL.md 主体是一张命令表（Build/Evaluate/Refine/Enhance/Fix + live 迭代），无参调用只出 context-aware 菜单绝不自动跑命令；每个命令对应 reference/ 下独立 playbook，规则以 <!-- rule:… --> 标记嵌入源文件供发布期一致性检查。
**No argument:** read [routing.md](reference/routing.md) and present its context-aware menu; never auto-run a command.
PRODUCT.md/DESIGN.md 双文档持久真相：init 只写 PRODUCT.md（产品真相：用户/任务/约束/平台），不碰视觉世界；document/extract 从成品代码反写 DESIGN.md（设计系统/token/组件），视觉方向在 new-work 决定并替换 DESIGN.md——『证据是权威，不是文件名』。
`init` captures durable product truth in PRODUCT.md. It does not invent a visual world and does not write DESIGN.md; [new-work.md](new-work.md) creates or expands one, and [document.md](document.md) records an incumbent one.
确定性检测器（61 条规则）以 hook 形式内建到宿主：hooks on 后 Claude Code/Codex/Copilot 用 post-tool-use hook 在每次 UI 文件编辑后自动跑检测器并把发现推回上下文；Cursor 用 preToolUse 在坏写入落地前拦截。配置在 .impeccable/config.json（本地覆盖 .impeccable/config.local.json）。
The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`).
live 浏览器变体模式：在本地 dev server（HMR）上把选中元素交给 AI 生成 HTML+CSS 变体热替换；通过轮询事件循环（_instructions 字段为权威下一步）与 .impeccable/live/ 会话 journal 保证断线可恢复；明文禁止注入生产站点/削弱 CSP。
Interactive live variant mode: select elements in the browser, pick a design action, and get AI-generated HTML+CSS variants hot-swapped via the dev server's HMR.
2核心能力
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| cli | impeccable 引擎（自含二进制，随 skill 的 scripts/impeccable launcher 定位/下载；技能通过 Bash 调用） |
| network | 引擎二进制下载通道（仅首次且缺二进制时）：GitHub Releases，engine-v<version> 资产 + .sha256 sidecar |
| package | npx impeccable（SKILL 授权 Bash(npx impeccable *) 的发布安装路径；README quick start 亦用 npx impeccable install） |
| network | 文档站/知识引用（非运行时调用）：impeccable.style、github.com/pbakaus/impeccable（README/docs 内链接）、google-labs-code/design.md spec（reference/document.md 内引用） |
4管控建议与判定依据
- scripts/: 执行本地脚本或命令: skill/scripts/impeccable launcher（POSIX sh）→ 引擎二进制：context/detect/hooks/liv
- 网络端点: 声明外部网络访问: 引擎二进制首次下载：https://github.com/pbakaus/impeccable/releases/download/engine-v<
- 本地工作目录: 文件读写与工件输出: 项目内：PRODUCT.md、DESIGN.md（+sidecar）、.impeccable/config.json 与 config.local.j
5第二遍独立确认
- [ok] 单一 master 源 + 多宿主编译副本 — diff skill/SKILL.src.md 与 .cursor/.claude 副本：差异仅为占位符展开（{{scripts_path}}→宿主路径）、frontmatter 增删（version/argument-hint/allowed-tools）、<!-- rule:… --> 注释剥离；正文结构一致。
- [ok] 每会话 context + 降级协议 — 编译副本与 src 均含 Setup 三步与 'Launcher unavailable' 段；引文逐字存在。
- [ok] 引擎二进制下载仅首次且 fail-closed — launcher 第 60-200 行精读：候选顺序 IMPECCABLE_BIN→sibling bin→~/.impeccable/bin→version cache→PATH probe→下载；下载后必须 sha256 sidecar 匹配才 chmod+mv+exec，sidecar 不可得/不匹配/空文件均拒绝（exit 127）。
- [ok] 61 规则与无 LLM 声明 — README 两处声明一致（'61 deterministic detector rules'、'no LLM and no API key'）；hooks.md 描述 per-edit 与 Stop 深扫两级；规则实体位于引擎二进制内（本仓库 skill 目录不含规则源码，属引擎发布物 [INFERENCE]）。
- [ok] 23 命令数 — SKILL.md 命令表逐行计数 = 23（craft 为 deprecated alias 仍列）；与 README '23 commands' 一致。
- [ok] hook 安装面与宿主 manifest — hooks.md 列出全部宿主清单路径（.claude/settings.local.json/.cursor/hooks.json/.codex/hooks.json/.github/hooks/impeccable.json/.grok/hooks/impeccable.json）；'reset' 动作会从 on 安装过的 manifest 移除条目。
- [ok] live 仅限本地 + journal 恢复 — live.md 明确 'requires a local checkout'、'injection into deployed production sites (including HTTPS) is unsupported'；.impeccable/live/sessions/ journal 与 live-status/resume 流程存在。
- [ok] 无凭证读取 — skill 目录（src/scripts/reference/agents + 编译副本）无 API key/token/secret/.env 读取代码；引擎行为以 README『no API key』声明 + 引文为据（引擎二进制内部未逐一审计 [INFERENCE]）。
6结论
1467f7553455c007…