Impeccable 完整教學 — 讓 AI 生成的前端設計脫離「AI 味」

1. 專案定位

問題：AI 生成的 UI 千篇一律

每個 LLM（大型語言模型）都在相同的 SaaS template（SaaS 模板）上訓練。不加引導，AI 生成的前端介面總會出現相同的設計慣性：

• Inter 字體配到底
• Purple-to-blue gradient（紫到藍漸層）無處不在
• Card nested in card（卡片套卡片）
• Gray text on colored background（灰字配色彩背景）
• Rounded-square icon tile（圓角方形圖示磚）在每個 heading 上方

解法：一套共享的設計語彙

Impeccable 為 AI coding agent（AI 編程代理）提供一套結構化的前端設計語言，讓你能用精確的設計指令取代模糊的 prompt（提示詞）。它不是一個 UI framework（UI 框架），而是 AI 的「設計品味注入層」。

三個交付物

適用對象

• 使用 AI coding tool（AI 編程工具）做前端開發的工程師
• 希望 AI 輸出通過專業設計審查的產品經理
• 想建立團隊設計一致性的 design engineer（設計工程師）

2. 安裝指南

方法一：CLI Installer（推薦）

在專案根目錄執行：

1npx impeccable skills install

此指令會自動偵測你使用的 AI harness（AI 載體），把編譯後的 skill 寫入對應位置（.claude/skills/、.cursor/skills/ 等）。支援 Cursor、Claude Code、Gemini CLI、Codex CLI 等 11 種工具。

安裝後記得重新載入 harness。

方法二：Claude Code Plugin（Claude Code 使用者）

1/plugin marketplace add pbakaus/impeccable

或使用通用的 skill 安裝指令：

1npx skills add pbakaus/impeccable

方法三：從網站下載

1. 前往 impeccable.style
2. 下載對應工具的 ZIP
3. 解壓縮到專案目錄

方法四：從 Repository 手動複製

Cursor：

1cp -r dist/cursor/.cursor your-project/

注意：Cursor 需在 Settings → Beta 切換到 Nightly channel，並在 Settings → Rules 啟用 Agent Skills。

Claude Code：

1# 專案級別
2cp -r dist/claude-code/.claude your-project/
3
4# 或全域級別
5cp -r dist/claude-code/.claude/* ~/.claude/

Gemini CLI：

1cp -r dist/gemini/.gemini your-project/

Codex CLI：

1# 專案級別
2cp -r dist/agents/.agents your-project/
3
4# 或使用者級別
5mkdir -p ~/.agents/skills
6cp -r dist/agents/.agents/skills/* ~/.agents/skills/

環境需求

驗證安裝

安裝完成後，在 AI harness 中輸入：

1/impeccable

應會顯示完整的 command list（指令列表）。

3. 核心架構解析

系統總覽

Impeccable 的架構由三個獨立但互補的子系統組成，共享同一套 anti-pattern rule（反模式規則）定義。

flowchart TD
    subgraph SKILL["Skill 子系統"]
        SRC["SKILL.src.md
技能原始碼"]
        REF["7 個 Domain Reference
typography / color / motion
spatial / interaction
responsive / ux-writing"]
        CMD["23 個 Slash Command
craft / audit / critique
polish / live / ..."]
        SRC --> REF
        SRC --> CMD
    end

    subgraph CLI["CLI 子系統"]
        ENTRY["cli/bin/cli.js
入口"]
        ENGINE["Detection Engine"]
        REGEX["Regex Engine
--fast 模式"]
        HTML["Static HTML Engine
DOM 解析"]
        BROWSER["Browser Engine
Puppeteer"]
        RULES["rules/checks.mjs
27 條反模式規則"]
        ENTRY --> ENGINE
        ENGINE --> REGEX
        ENGINE --> HTML
        ENGINE --> BROWSER
        ENGINE --> RULES
    end

    subgraph EXT["Browser Extension 子系統"]
        MANIFEST["manifest.json
Manifest V3"]
        DEVTOOLS["DevTools Panel"]
        POPUP["Popup UI"]
        INJECT["Content Script
頁面注入偵測"]
        MANIFEST --> DEVTOOLS
        MANIFEST --> POPUP
        MANIFEST --> INJECT
    end

    subgraph BUILD["Build Pipeline"]
        BUILDSRC["scripts/build.js"]
        TRANSFORM["Provider Transformers
scripts/lib/transformers/"]
        DIST["dist/
11 種 harness 輸出"]
        BUILDSRC --> TRANSFORM
        TRANSFORM --> DIST
    end

    SKILL -->|"安裝到
AI harness"| DIST
    CLI -->|"共享規則"| RULES
    EXT -->|"嵌入偵測器"| RULES

Detection Engine（偵測引擎）

CLI 的核心是三層偵測引擎，根據輸入類型自動選擇：

Skill Build Pipeline（技能建構管線）

skill/SKILL.src.md 是所有 harness skill 的 single source of truth（唯一事實來源）。scripts/build.js 透過 scripts/lib/transformers/providers.js 中的 provider config（提供者設定），為每種 AI harness 產出客製化的 skill 檔案到 dist/ 目錄。

Live Mode 架構

/impeccable live 啟動一個本地 HTTP server（live-server.mjs），透過 token-based auth（token 認證）保護所有 endpoint。瀏覽器端注入 live-browser.js，建立 WebSocket 連線，讓 AI agent 能在瀏覽器中即時修改 DOM、提交或放棄變更。

4. 使用方式詳解

基本指令

所有指令透過 /impeccable 進入：

1/impeccable audit              # 技術品質審查
2/impeccable critique           # UX 設計審查
3/impeccable polish             # 最終修飾
4/impeccable distill            # 去除多餘

指定範圍

大多數指令接受可選的 target（目標）參數：

1/impeccable audit the header       # 只審查 header
2/impeccable polish the checkout    # 只修飾結帳流程
3/impeccable harden the login form  # 強化登入表單

設計工作流範例

完整設計流程（craft flow）：

1/impeccable init          # 1. 設定設計脈絡
2/impeccable craft         # 2. 規劃 → 建構 → 迭代
3/impeccable audit         # 3. 技術品質檢查
4/impeccable critique      # 4. UX 設計審查
5/impeccable polish        # 5. 最終修飾

針對性修正：

1/impeccable bolder        # 放大無聊的設計
2/impeccable quieter       # 收斂過度張揚的設計
3/impeccable typeset       # 修正字體選擇與層次
4/impeccable colorize      # 引入策略性色彩
5/impeccable animate       # 加入有意義的動態

Pin（釘選）常用指令

1/impeccable pin audit     # 建立 /audit 捷徑
2/impeccable pin polish    # 建立 /polish 捷徑

之後直接用 /audit 即可。

CLI 獨立使用

不需 AI harness 也能用 CLI 偵測反模式：

 1# 掃描目錄
 2npx impeccable detect src/
 3
 4# 掃描 HTML 檔案
 5npx impeccable detect index.html
 6
 7# 掃描 URL（需 Puppeteer）
 8npx impeccable detect https://example.com
 9
10# 快速模式（純 regex）+ JSON 輸出
11npx impeccable detect --fast --json .

Skills 管理

1npx impeccable skills install   # 安裝到目前專案
2npx impeccable skills update    # 更新到最新版
3npx impeccable skills check     # 檢查是否有更新
4npx impeccable skills help      # 列出所有可用 skill

5. 應用場景

場景一：新專案啟動

團隊使用 AI coding tool 開始新的 SaaS 產品。安裝 Impeccable 後，先執行 /impeccable init 建立 PRODUCT.md 和 DESIGN.md，定義品牌個性、色彩系統、排版規則。之後每次用 AI 產生 UI 時，Impeccable 的 reference file 會自動載入，讓 AI 輸出符合專案的設計系統。

場景二：CI/CD 整合

在 CI pipeline 中加入 npx impeccable detect --fast --json src/，自動偵測每次 PR 引入的設計反模式。當偵測到 bounce easing、purple gradient 等「AI 味」時自動阻擋合併。

場景三：既有專案設計升級

對已上線的專案執行 /impeccable audit 找出技術品質問題，再用 /impeccable critique 做 UX 審查。根據報告用 /impeccable polish 逐步修正，最後用 /impeccable live 在瀏覽器中微調視覺細節。

場景四：設計系統文件化

用 /impeccable document 從現有程式碼自動產生 DESIGN.md，記錄色彩 token、排版系統、間距規則。再用 /impeccable extract 抽取可重用的 component（元件）與 token（設計令牌）。

場景五：Live Mode 迭代

用 /impeccable live 啟動即時模式，在瀏覽器中直接看到 AI 提出的設計變更。可以即時 accept（接受）或 discard（放棄）每個變更，不需切換回編輯器。

6. 資安掃描報告

掃描範圍

掃描整個 repository 的 JavaScript 原始碼（排除 node_modules、.git），檢查以下高風險 pattern（模式）：

• eval() / exec() 呼叫
• child_process / spawn / execSync 使用
• innerHTML / outerHTML / document.write DOM 注入
• Hardcoded secret（硬編碼機密）/ API key
• pickle.load / __import__ / os.system

發現

🟡 eval() — Browser Extension DevTools（中風險）

風險評估：這是 Chrome DevTools extension API 的標準用法，用於在被檢查的頁面上下文中執行程式碼。屬於 DevTools 擴充套件的正常 pattern，但使用者應注意 extension permission scope（擴充套件權限範圍）。

🟡 child_process — Live Server 與 Skill Scripts（中風險）

風險評估：所有 child_process 使用都在 skill script 內部，用於合法的開發工具操作（啟動 server、執行 git 指令、呼叫 CLI）。沒有使用者輸入直接拼接到 shell command 的情況。

🟡 innerHTML — Live Browser UI（中風險）

風險評估：innerHTML 使用集中在 live-browser.js 的 UI 建構，內容為硬編碼的 SVG icon 或清空操作，非使用者輸入注入。風險可控。

🟢 無硬編碼機密

未發現 API key、password、secret token 等硬編碼機密。Live server 使用 randomUUID() 動態產生 session token。

🟢 無 Python 風險 Pattern

未發現 pickle.load、__import__、os.system、subprocess 等 Python 風險 pattern（本專案為純 JavaScript）。

總評

🟢 安全性良好 — 所有 eval() 使用限於 Chrome DevTools API 標準用法；child_process 使用合理且無使用者輸入拼接；innerHTML 用於 UI 建構而非使用者內容注入。token-based auth（token 認證）保護 live server endpoint。無硬編碼機密。

7. FAQ

Q1：Impeccable 和 Anthropic 的 frontend-design skill 有什麼不同？

Impeccable 從 Anthropic 的 frontend-design 出發，但大幅擴充了 domain reference（從 1 個到 7 個）、加入 23 個結構化指令、27 條確定性反模式規則、CLI 工具與瀏覽器擴充套件。原始 skill 只提供一般性設計指引，Impeccable 提供可操作的設計語彙。

Q2：安裝後需要 API key 嗎？

Skill 和 slash command：不需要額外 API key，它們透過你的 AI harness 運作。 CLI detect：確定性規則不需 API key；若啟用 LLM critique pass 則需要。 Browser Extension：不需 API key。

Q3：支援哪些 CSS framework？

Impeccable 的偵測規則是 framework-agnostic（框架無關）的，掃描的是最終呈現的 CSS 屬性，不依賴特定 framework。Tailwind、vanilla CSS、CSS-in-JS 都支援。

Q4：--fast flag 做什麼？

--fast 啟用純 regex engine（正則引擎），跳過 DOM 解析和 Puppeteer，速度最快但精準度較低。適合 CI/CD pipeline 中的快速掃描。

Q5：live mode 會修改我的原始碼嗎？

是的，當你 accept 一個變更時，live mode 會直接修改對應的原始碼檔案。discard 則不會。所有變更都在本地進行，不會推送到 remote（遠端）。

Q6：可以只安裝 CLI 不裝 skill 嗎？

可以。npx impeccable detect 是獨立的，不需要安裝 skill 到任何 AI harness。

8. 進階技巧

自訂 DESIGN.md

/impeccable init 產生的 DESIGN.md 定義了專案的設計 token（設計令牌）。你可以手動編輯它來覆寫預設值：

• colors: — 定義品牌色彩（使用 OKLCH 色彩空間）
• typography: — 字體選擇與比例尺度
• motion: — 動態曲線與時長偏好
• spatial: — 間距系統與網格

客製化反模式規則

CLI 的反模式規則定義在 cli/engine/registry/antipatterns.mjs。你可以 fork 後新增專案特定的規則。

Brand Register（品牌暫存器）

Impeccable 的 skill 內建 brand-vs-product register（品牌 vs 產品暫存器）。在 PRODUCT.md 中定義 register: brand 或 register: product，skill 會自動調整設計建議的風格強度。

框架特定 Adapter（轉接器）

Live mode 支援框架特定的 adapter：

• Svelte adapter（#179 最近新增）
• 其他框架可透過 live-server.mjs 的 adapter API 擴充

Profiler（分析器）

CLI 內建 profile/profiler.mjs，可以產生偵測結果的統計摘要，包括各類反模式的出現頻率與嚴重度分佈。

JSON 輸出整合

1npx impeccable detect --json src/ | jq '.findings | group_by(.severity) | map({severity: .[0].severity, count: length})'

可以輕鬆整合到自動化工具鏈中。

9. 整合進其他工作流

CI/CD Pipeline 整合

在 GitHub Actions 中新增 step：

1- name: Design Quality Gate
2  run: |
3    npx impeccable detect --fast --json src/ > impeccable-report.json
4    CRITICAL=$(jq '[.findings[] | select(.severity == "critical")] | length' impeccable-report.json)
5    if [ "$CRITICAL" -gt 0 ]; then
6      echo "❌ Found $CRITICAL critical design anti-patterns"
7      jq '.findings[] | select(.severity == "critical")' impeccable-report.json
8      exit 1
9    fi

Pre-commit Hook 整合

1# .husky/pre-commit
2npx impeccable detect --fast $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(html|css|tsx|jsx)$')

與其他 AI Skill 搭配

Impeccable 與其他 AI skill 可以互補：

多 Harness 工作流

團隊中不同成員可能使用不同的 AI tool。Impeccable 的 npx impeccable skills install 自動偵測 harness 並安裝對應版本，確保所有成員使用相同的設計規則，無論底層 AI tool 為何。

10. 重點摘要 Checklist

• 理解定位：Impeccable 是 AI 的「設計品味注入層」，不是 UI framework
• 安裝方式：推薦 npx impeccable skills install，自動偵測 harness
• 三個子系統：Skill（23 指令 + 7 參考）、CLI（反模式偵測）、Extension（瀏覽器面板）
• 核心指令：audit（技術品質）、critique（UX 審查）、polish（最終修飾）、live（即時迭代）
• 偵測引擎：Regex（快速）→ Static HTML（中等）→ Browser/Puppeteer（精準）
• 反模式規則：27 條確定性 + 12 條 LLM critique，無需 API key 即可跑確定性規則
• 設計脈絡：/impeccable init 產生 PRODUCT.md + DESIGN.md，定義專案設計 token
• Live Mode：本地 server + browser 注入，token 認證保護，支援 accept/discard
• CI/CD 整合：npx impeccable detect --fast --json 適合自動化管線
• 跨平台：支援 11 種 AI coding tool，single source of truth 建構
• 安全性：🟢 良好 — 無硬編碼機密、eval 限於 DevTools API、child_process 使用合理
• 授權：Apache-2.0，可商用

11. 進一步閱讀

官方資源

• 官方網站：impeccable.style — 案例研究、下載、文件
• GitHub Repository：github.com/pbakaus/impeccable
• npm 套件：npmjs.com/package/impeccable
• DEVELOP.md：貢獻指南與建構說明

設計參考

• DESIGN.md：Neo kinpaku 設計系統，定義 OKLCH 色彩 token、排版、動態規則
• PRODUCT.md：產品定位與品牌個性定義（expert, decisive, editorial）
• HARNESSES.md：各 AI harness 的 skill 功能支援矩陣
• Agent Skills Specification：agentskills.io/specification — 跨 harness 的 skill 標準規範

相關資源

• Anthropic frontend-design skill：github.com/anthropics/skills — Impeccable 的前身
• OKLCH Color Space：理解 Impeccable 色彩系統的基礎
• Manifest V3 Extension API：Chrome 擴充套件開發參考