Impeccable 架构全景图：设计技能、检测CLI与浏览器扩展的协作指南-编程实验室

Impeccable 架构全景图：设计技能、检测CLI与浏览器扩展的协作指南

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable

Impeccable 是一款面向 AI 编码工具的设计技能包，它为 AI 提供 23 个设计命令、59 条确定性反模式检测规则，并附带检测 CLI 与浏览器扩展。本文带你一次看懂这三者如何分工协作，让 AI 写出不再"一眼 AI"的前端界面。

一张图看懂整体架构 🧭

Impeccable 由三大组件构成，各自解决一个环节的问题：

组件	位置	职责
设计技能（Skill）	skill/	教 AI "怎么设计"：命令、流程、反模式清单
检测 CLI	cli/	机器可执行的质检：59 条规则扫描代码或线上页面
浏览器扩展	extension/	在任意网页上一键检测 UI 反模式

三者共享同一套规则与配置，形成"设计 → 检测 → 修复"的闭环。

组件一：设计技能（Skill）——AI 的设计手册

技能是 Impeccable 的核心。安装后，你在 AI 工具里输入/impeccable <命令>即可调用，共 23 个命令，例如audit（技术质检）、polish（发布前打磨）、bolder（放大胆设计）、quieter（收敛过度设计）、live（浏览器内实时迭代变体）。

命令的行为定义来自 skill/SKILL.src.md，每个命令对应一份"剧本"（playbook），存放在 skill/reference/ 目录：

skill/reference/init.md：一次性初始化，写入 PRODUCT.md 与 DESIGN.md
skill/reference/audit.md：技术质量检查（无障碍、性能、响应式）
skill/reference/live.md：浏览器可视化变体模式
skill/reference/hooks.md：管理检测钩子

技能还内置了脚本能力，例如 skill/scripts/detect.mjs 供 AI 在会话中直接调用检测器，skill/scripts/live-server.mjs 支撑 live 模式的本地预览服务。

组件二：检测 CLI —— 无需 AI 的确定性质检

CLI 最大的价值在于确定性：不依赖大模型、不需要 API Key，同样的代码永远给出同样的结果。典型用法：

npx impeccable detect src/ # 扫描目录 npx impeccable detect index.html # 扫描单个 HTML 文件 npx impeccable detect https://example.com # 扫描线上页面 npx impeccable detect --json . # 输出 CI 友好的 JSON

实现上，CLI 入口是 cli/engine/cli/main.mjs，规则注册表在 cli/engine/registry/antipatterns.mjs。检测引擎按目标分成四类，位于 cli/engine/engines/：

regex 引擎：detect-text.mjs，扫描源码文本中的反模式（如滥用 Inter 字体、紫色渐变、bounce 缓动）
static-html 引擎：detect-html.mjs 配合 css-cascade.mjs 分析静态页面与 CSS 级联
browser 引擎：detect-url.mjs，用 Puppeteer 打开真实页面
visual 引擎：screenshot-contrast.mjs，基于截图检测文字遮挡与对比度问题

检测结果可被豁免：.impeccable/config.json中配置ignoreRules，或在文件内写行内豁免，管理命令见 README.md 的 CLI 章节。

组件三：浏览器扩展 —— 随手检测任意网页

扩展面向普通用户，manifest 定义在 extension/manifest.json（Manifest V3，描述为"Detect common UI anti-patterns in any web page"）。功能分布在：

图标弹窗：extension/popup/popup.html，点击工具栏图标即可检测当前页面
DevTools 面板：extension/devtools/devtools.html 与 extension/devtools/devtools.js，在开发者工具侧边栏展示检测发现
后台脚本：extension/background/service-worker.js 负责跨页面调度

三者如何协作？🔁

规则同源：技能、CLI、扩展都消费同一份 59 条规则清单，改一处规则，三个端同时生效。
钩子打通编辑流：在 Claude Code、Cursor、Codex 等工具中，安装时会注册"设计钩子"（见 skill/scripts/hook.mjs），AI 每次修改 UI 文件后自动跑检测器，问题实时反馈给 AI 修复。
配置统一：共享配置存放在项目的.impeccable/config.json，/impeccable hooks命令与npx impeccable detect读取同一份忽略规则。
live 模式串起设计与检测：浏览器里选中元素 → AI 生成变体 → 你点选满意方案，源码由 skill/scripts/live/ 下的适配脚本自动回写到代码库。

快速上手三步走 🚀

第 1 步：安装技能

npx impeccable install

命令会自动识别你的 AI 工具目录（如.claude、.cursor）并写入技能与钩子。

第 2 步：初始化设计上下文

在 AI 工具中运行：

/impeccable init

它会询问你的产品定位（品牌型还是产品型），并生成 PRODUCT.md 与 DESIGN.md，供后续所有命令读取。

第 3 步：按需调用命令

/impeccable audit blog # 审计博客页面 /impeccable polish settings # 打磨设置页 /impeccable detect # （或命令行）npx impeccable detect src/

总结

Impeccable 的架构本质是"一个规则中心 + 三个执行端"：设计技能负责教会 AI 设计，检测 CLI 负责在代码与 CI 里把关，浏览器扩展负责让普通用户随时体检任意网页。理解这条"设计 → 检测 → 修复"的协作链路，你就掌握了用好这套工具的全部钥匙。

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Impeccable 架构全景图：设计技能、检测CLI与浏览器扩展的协作指南