第35章 Agent 缺失的设计词汇表(第35章):用 impeccable 检测 UI 设计问题
运行检测扫描
在终端里检查你的 UI。
本页共 5 个小节。
大多数 agent 使用 /impeccable。在 Codex 中使用 $impeccable。
无需启动 AI 对话,即可扫描已知的设计问题。检测器会检查代码和渲染后的页面,找出低对比度、文本溢出、常见 AI 设计套路、偏离设计系统等问题。
运行扫描
在项目目录下执行:
npx impeccable detect src/
可以只传一个文件做针对性检查,也可以传 URL 检查渲染后的页面:
npx impeccable detect src/components/Card.tsx npx impeccable detect http://localhost:3000
源码扫描检查 UI 代码和样式;URL 扫描会在浏览器中打开页面,从而基于渲染后的布局进行检查。根据想检查的内容选择合适的对象。
读懂检测结果
每条结果都会指明所违反的规则、定位相关代码或元素,并解释需要重新考量什么。下面是一个小型 CSS 示例的真实检测结果:
在 example.css 中 h1 { background: linear-gradient(90deg, #ff3399, #8833ff); background-clip: text; -webkit-background-clip: text; color: transparent; } 检测结果 gradient-text 第 3 行 · background-clip: text + gradient 检测器建议使用纯色文字。请判断这个渐变在设计中是否有实际作用。 规则和位置来自真实扫描结果。上面的说明文字为本示例做了精简。
遇到真实问题就修复它;如果是有意为之的设计选择,则记录一条范围明确的例外。扫描干净表示这些检查未发现值得报告的问题;更宏观的设计评估可以交给 critique。
退出码与自动化
如果脚本或 CI 任务需要结果,可以使用 JSON:
npx impeccable detect --json src/
代码 含义
0 扫描完成,无主要问题。可能仍有建议(advisory)。
2 扫描完成,发现主要问题。
1 至少有一个目标无法扫描。
主要问题决定结果数量和退出码。建议(advisory)只是附加观察,不会导致扫描失败。退出码 1 应视为扫描失败,即使其他目标产生了结果。
保存输出或隐藏建议
JSON 输出到标准输出,人类可读的结果输出到标准错误:
npx impeccable detect --json src/ > findings.json npx impeccable detect src/ 2> findings.txt
--quiet 将文字输出精简为最终计数。--no-advisory 在单次扫描中隐藏建议。
对照你的设计系统检查
如果本地存在 DESIGN.md,检测器会依据它检查文档化的字体、颜色、圆角半径和字号。配套的 .impeccable/design.json 文件提供结构化的 token 和字阶数据。
用 document 命令保持记录最新:
/impeccable document
单次扫描跳过设计系统检查:
npx impeccable detect --no-design-system src/
保留有意的选择
忽略(ignores)对手动扫描和 design hooks 都生效。尽量记录具体值:
npx impeccable ignores add-value overused-font Inter --reason "Brand font"
这样规则对其他字体依然生效。配置与忽略章节介绍了文件范围、私有例外以及之后删除忽略的方法。
更多扫描选项
文件类型与服务端模板
扫描文件夹时会查找受支持的 UI 和样式文件。HTML 扫描会包含链接的本地 CSS。JSX、TSX、Vue、Svelte、Astro 和样式表文件会接受源码检查。
如需声明额外的模板扩展名(如 Blade 或 ERB),在 detector.extensions 下配置。参见服务端模板。
检测器针对 Web 界面。如果是原生 iOS 或 Android 项目,请使用适合该平台的 audit。
视口、设计领域与管道输入
URL 扫描默认使用 1280 × 800 视口。可以指定更小的尺寸来检查移动端布局:
npx impeccable detect --viewport 390x844 http://localhost:3000
可将检查限定到某个设计领域,也可用逗号组合多个领域:
npx impeccable detect --scope type src/ npx impeccable detect --scope type,layout src/
通过管道传入文本且未指定目标时,检测器会读取标准输入:
cat component.css | npx impeccable detect
项目设置与跳过忽略的扫描
手动扫描会读取 .impeccable/config.json 和 .impeccable/config.local.json。关闭 hooks 并不会禁用手动扫描。
--no-inline-ignores 会绕过文件内的忽略注释,但保留配置中的忽略。--no-config 则两者都绕过,同时也不读取项目配置和本地设计系统上下文。
如果某条例外涉及不应提交到仓库的内容,可使用文件内的忽略注释。