企业官网建设流程全解析

CI/CD集成Impeccable：提交前设计检查与PR门禁配置完整指南

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

Impeccable是一套让 AI 编程助手更懂设计的"设计语言技能"，除了 23 条设计命令，它还内置了59 条确定性设计检测规则——不依赖 LLM、不需要 API Key，用一条 CLI 命令就能把"紫色渐变、Inter 字体、卡片套卡片"等 AI 生成的设计坏味道扫出来。本文教你把Impeccable detect接入 CI/CD，实现提交前设计检查与PR 门禁，让设计质量像单元测试一样可拦截、可豁免、可追溯。

为什么设计检查值得进 CI？

传统 CI 门禁只关心"能不能跑"，不关心"好不好看"。AI 生成前端时代，同一批模板审美反复出现：Inter 字体、紫蓝渐变、灰色文字压在彩色背景上……这些"设计 slop"肉眼难查，却极易规模化。

Impeccable 的 59 条规则全部是确定性检测，覆盖两大类问题：

• AI slop 特征：侧边边框、紫色渐变、bounce 缓动、暗色霓虹光晕等
• 通用设计质量：行宽过长、内边距拥挤、触控目标过小、标题层级跳跃等

规则源码在 cli/engine/registry/antipatterns.mjs 与 cli/engine/rules/checks.mjs，想确认某条规则的判定逻辑可以直接翻源码。

核心命令：impeccable detect 设计检测器

CI 集成只需要记住一条命令（完整用法见 README.md 的 CLI 章节）：

npx impeccable detect src/ # 扫描目录 npx impeccable detect index.html # 扫描单个 HTML npx impeccable detect --json . # CI 友好的 JSON 输出 npx impeccable detect --no-config src/ # 裸扫，忽略项目配置

它对 CI 友好的三个关键特性（实现见 cli/engine/cli/main.mjs）：

1. 退出码即门禁信号：发现非建议级问题时以退出码2结束；无问题或仅有 advisory（建议级）笔记时以0结束。advisory 类规则只展示、永不阻塞自动化。
2. --json输出结构化结果：可直接被工作流步骤解析、上报、写回 PR 评论。
3. 尊重项目配置：自动读取.impeccable/config.json的detector.ignoreRules/ignoreFiles/ignoreValues设置，CI 与本地行为完全一致。

💡 扫描 URL 时会走 Puppeteer 真实渲染；扫描本地文件走静态 HTML/CSS 分析，无需浏览器，速度快、适合放进每个 PR。

一键安装步骤：接入前的一次性配置

在业务项目根目录执行：

npx impeccable install

它会探测你的 AI 工具目录（Claude Code、Cursor、Codex 等）并安装技能与design hook。如果暂时只想用 CI，也可以跳过此步——detect命令本身独立可用，无需 AI 工具在场。

PR门禁配置：最小可用的 CI 工作流

在.github/workflows/design-gate.yml中放一个最小门禁，思路与 Impeccable 仓库自身的 ci.yml 一致——push/PR 触发、按变更裁剪、失败即红：

name: Design Gate on: pull_request: branches: [main] jobs: detect: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 22 - name: Run Impeccable design detector run: npx impeccable detect --json src/ > findings.json - name: Show summary on failure if: failure() run: cat findings.json

退出码2会让该步骤直接失败，PR 状态即变为红 ✅→❌，门禁完成。几个调优建议：

• 只扫 UI 相关目录（src/、app/），避免全仓扫描拖慢 CI
• --scope type,layout可按设计域收窄规则集，先拦最严重的
• 团队想"先观察后拦截"，可先不加exit-code失败策略，把 JSON 结果上传为 artifact 观察两周再收紧

豁免与忽略：让门禁不误伤

好的门禁要"可解释地放行"，Impeccable 提供了两层豁免机制：

① 仓库级配置——写在.impeccable/config.json的detector键下：

{ "detector": { "ignoreRules": ["bounce-easing"], "ignoreFiles": ["src/legacy/**"] } }

也可用 CLI 管理（见 cli/bin/commands/ignores.mjs）：

npx impeccable ignores add-file "src/legacy/**" npx impeccable ignores add-value overused-font Inter --reason "Brand font"

② 文件级内联豁免——随代码一起走 diff，reviewer 一眼可见理由：

<!-- impeccable-disable overused-font: 导出的品牌文档，保留 Inter --> /* impeccable-disable-line overused-font */ // impeccable-disable-next-line bounce-easing: 有意的弹跳效果

规则：品牌遗留代码用ignoreFiles整目录豁免，单处例外用内联注释。这样 CI 报告永远是"零噪音"，团队才不会绕过门禁。

提交前实时拦截：design hook 设计钩子

CI 是"事后拦截"，design hook 则是"事前拦截"。在 Claude Code、GitHub Copilot、Codex、Cursor、Grok Build 上，npx impeccable install会额外安装 provider 原生 hook 清单：

• Cursor：在坏写入落盘之前直接拦截
• Claude Code / Copilot / Codex：编辑后把检测结果回灌给 agent，支持在 Stop 时机做深度复查
• hook 与detect共享同一套detector忽略配置，CI 与本地判定口径统一

各 provider 的 hook 清单路径（如.cursor/hooks.json、.codex/hooks.json）在 README.md 的 Design hook 一节有完整列表。配合本文的 PR 门禁，就形成了"编辑时提示 → 提交前检查 → PR 门禁兜底"的三道防线。

进阶：从 Impeccable 自家 CI 学三门功课

Impeccable 仓库的 ci.yml 本身就是 CI/CD 设计的教科书：

1. 按变更裁剪测试：scripts/ci-test-plan.mjs 先分析 PR 改了什么，只跑相关的测试组（detector、live、framework 各自按需触发），PR 门禁快而准；
2. 慢测试挪到夜间全量：完整 live-e2e 矩阵对 PR 太慢，改为每日 cron 对 main 全量跑一次，PR 只跑 smoke 组；
3. 僵尸 PR 自动管理：sheriff.yml 每天定时运行 scripts/github/sheriff.mjs，超过 7 天无响应的 PR 自动留言提醒，14 天后关闭，保持 PR 队列健康。

把"变更检测 + 分级执行 + 夜间全量"这套模式套到你的设计门禁上：PR 上跑detect（秒级），主分支每日跑含 URL 渲染的完整扫描，成本与覆盖率兼得。

常见配置问题排查清单

调试细节（如 hook 审计日志hook.auditLog）见 docs/DEVELOP.md 与 README.md。

总结

把 Impeccable 接入 CI/CD 只需三步：detect --json进工作流 → 配置.impeccable/config.json豁免 → 用 exit code 2 做 PR 门禁。再叠加 design hook 的编辑时拦截，你的团队就拥有了不依赖 LLM、不烧 token、毫秒级出结果的确定性设计质量防线。设计不再靠"感觉不错"，而是和测试覆盖率一样，变成一个可以持续度量的数字。

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