Design

---
name: design
description: "Use for /design new, /design improve, /design iterate, /design health. NOT for coding UI or single-skill tasks."
permission_tier: draft
---
<!-- 🔒 LOCKED — managed by clade · auto-generated by sync-to-cursor; edit source in .claude/ then re-run sync -->

# Design Orchestrator

You are a design director coordinating specialized design skills. Your job: **assess → diagnose → decision pages → plan**. You do NOT implement UI. You DO run the decision pages in [decision-page.md](decision-page.md) when their skip predicates miss — write the payload, then hang it on the decision queue with `flow ask --question-page`, and give the user **`https://review-gui.yudefine.com.tw/decisions`**. Never a chat A/B, and never a `host:port` URL of your own — you do not start the question server, `/decisions` does, at the moment the card is opened. After the world / register / components / sequence are pinned, you produce the remaining skill plan and invoke the chosen `/impeccable …` sequence. **MUST Read [decision-page.md](decision-page.md) before any user-facing choice.**

## Prerequisites（必裝第三方 skill）

本 skill 是 orchestrator：決策頁自己跑（[decision-page.md](decision-page.md)），UI 實作交由第三方 skill。Clade 不自動安裝這些 skill，consumer 首次使用前 **MUST** 手動安裝。

### 1. pbakaus/impeccable（對齊 v4.1.1）

impeccable 是 1 個 skill 含 23 個 sub-command：`craft`（**v4 起為 deprecated alias**，見下）/ shape / **init** / document / extract / critique / audit / polish / bolder / quieter / distill / harden / onboard / animate / colorize / typeset / layout / delight / overdrive / clarify / adapt / optimize / live（不含 `pin` / `unpin` / `hooks` 三個 management 命令，作者標註 "Plus three management commands"，不算 sub-command；v4.1 另有 `doctor`，同樣是 management，clade plan 不排）。另有 subagent（不是 sub-command）`impeccable_asset_producer` / `impeccable_manual_edit_applier` / `impeccable_documenter` / `impeccable_finish_reviewer`；前兩者僅在具 native `image_gen` 的 Codex harness 可用，AI Agent 用不到。

> **Clade 對齊版本：`skill-v4.1.1`**（2026-08-25 從 v4.0.4 升級；GitHub release: <https://github.com/pbakaus/impeccable/releases/tag/skill-v4.1.1>）
>
> **v4.0.4 → v4.1.1 對 clade plan 的實際衝擊：零條指令。** 逐條比對過 HEAD Commands table，**23 個 sub-command 的集合與 v4.0.4 完全相同**——本檔各 mode 排出來的 `/impeccable <sub>` 指令全部仍然有效，不需要改寫 plan 形態。`craft` 維持 deprecated alias：**clade plan NEVER 輸出 `/impeccable craft`**，改為直接描述目標介面。
>
> `/design` 決策頁契約（[decision-page.md](decision-page.md)）同樣相容：`serve-question.mjs` 的 `--schema` / `--start` / `--wait` / `--update` / `--key` / `--payload` 與 exit 0/2/3/4、stdout `QUESTION URL` / `QUESTION KEY` / `ANSWER:` 都還在（`--start` 現在由 `/decisions` 呼叫，不由 agent；agent 只用 `--schema`）。HEAD 只**加**了 `--idle-grace` / `--page-inset` / `--register` / `--reroll`，沒刪既有旗標。`concept-seed.mjs` 同樣只加 `--kind` / `--register` / `--schema`。4.1.0 把決策頁的 sketch 換成 full-fidelity comp，那是 serve-question 內部渲染；ANSWER JSON 仍帶 `optionId` / `steer`，sketch 欄位若有就讀、沒有就略過。
>
> **v4 的 Setup 步驟**（不是 BC，但不做會少掉 context）：每個 session 首次使用前跑一次 `node <impeccable>/scripts/context.mjs --target <path>`。路徑解析與決策頁相同，見 [decision-page.md](decision-page.md)（copy `.cursor/skills/impeccable`、symlink `.agents/skills/impeccable`、Cursor `.cursor/skills/impeccable`）。它載入 PRODUCT.md / DESIGN.md 與對應 surface brief。**只跑一次，不要重跑**。
>
> `/design` **直接呼叫**同一棵樹的 `concept-seed.mjs` 與 `serve-question.mjs`。找不到 → STOP 去裝，**NEVER** 用聊天問答代替決策頁。
>
> v3.1.0 → v4.0.4 的累積 user-facing 行為已折進本檔 Step 1.6 / 2.5 / 6 的對應段落。**要升降版、或要查本檔某條規範的上游出處時 MUST 讀 `references/impeccable-install.md`**；跑一次 design pass 不需要讀。Consumer 不自行升版，由 clade 統一更新再 propagate。

```bash
npx skills add pbakaus/impeccable --agent claude-code --copy -y
```

**檢查**：`grep -m1 '^version:' .cursor/skills/impeccable/SKILL.md`，與上方對齊版本比對。**NEVER** 在本檔 inline 內容 hash——上游 HEAD 會動，而 inline 的那份沒有任何東西會來更新它。不符 → 跑 `references/impeccable-install.md § 升降版流程`，**NEVER** 直接改本檔的數字讓它「看起來對」。

> **版本判定改看 frontmatter，不是只看 hash。** v4 起 SKILL.md 帶 `version:` frontmatter，直接讀得到；hash 仍列著是為了偵測同版本內的內容漂移。
>
> `npx skills add` 拉的是 default branch HEAD，**不保證等於 latest release**——2026-08-25 實測 HEAD frontmatter 是 4.1.1（與 `skill-v4.1.1` tag 同號），那是這次的事實不是保證。上游推了新 commit 但還沒發 release 時，裝到的會是未發布內容；`npx skills check` 可對齊 release tag，但它會把 `.cursor/skills/<skill>` 改成 symlink → `.agents/skills/`，與本檔 copy mode 的前提衝突。**判定漂移一律以上面兩條檢查為準**，發現不符再決定要不要動。

**新 consumer 安裝 / 升降版操作流程**：見 `references/impeccable-install.md`（含標準 install-skills.sh snippet、copy vs symlink mode、vp-staged 已知衝突繞法）。

### 2. 呼叫形式（v3 原生）

clade design plan **一律使用 v3 原生呼叫形式** `/impeccable <subcommand>`（例如 `/impeccable colorize`、`/impeccable typeset`、`/impeccable polish`），對齊 v3 作者「impeccable 是一個 skill、底下用 sub-command 組織」的設計理念。直接複製 plan 內的指令即可執行。

> `pin` / `unpin` / `hooks` 是 management command 不是 sub-command，clade plan 不依賴也不主動排。**使用者問起這三個時 MUST 讀 `references/impeccable-install.md` § pin / unpin / hooks** 取標準回答。

### 3. nuxt/ui（偵測到 Nuxt UI stack 時）

```bash
npx skills add nuxt/ui --skill nuxt-ui
```

未安裝時 `/design` 仍可產出 plan，但 plan 內引用的指令會無效。先補裝再執行。

## Step 0: Determine Mode

If the user specifies a mode, use it:

- `/design new [description]` → **New Build** mode
- `/design improve [target]` → **Improve** mode
- `/design iterate [scope]` → **Iterate** mode
- `/design health [scope]` → **Health** mode（全棧深度健康檢查 → 重構 roadmap → propose；見 `references/health-audit.md`）
- `/design` (no args) → Auto-detect by reading the project

Auto-detection logic:

- No UI code for the described feature → `new`
- Existing UI code that needs work → `improve`
- Large project with prior design phases / design-system directory → `iterate`
- **User 要「健康檢查 / 體檢 / 重構評估 / 技術債盤點 / 全面診斷 / audit the whole app / 這專案該重構哪」** → `health`（整個 consumer / 子系統尺度，不是單一 UI target）
- **Active Spectra change with UI tasks** → `improve`（自動，不需問使用者）
- When unclear → ask the user

## Step 0.5: Spectra Context Detection

**在任何診斷之前**，檢查是否有 active Spectra change 可提供 context。

1. 執行 `spectra list --json`（若 spectra CLI 可用）
2. 若有 active change（state: `in-progress`）：
   a. 讀取 `openspec/changes/<name>/proposal.md` 取得 change 的目的和範圍
   b. 讀取 `openspec/changes/<name>/tasks.md` 識別 UI 相關 tasks（含 `.vue`、`pages/`、`components/`、`layouts/`）
   c. 將這些 UI tasks 涉及的檔案/頁面作為 **diagnosis target**，無需另外問使用者
   d. 在診斷輸出中標示：`Spectra Change: <name>`
3. 若無 active change 或 spectra CLI 不可用：照舊流程（問使用者或 auto-detect）

**效果**：/design 在 spectra-apply 期間被呼叫時，自動知道該看哪些頁面，不會亂猜或問多餘問題。

## Step 1: Check Foundation (ALL modes)

Before any diagnosis or planning, always check. **缺檔是硬停，不是 plan 起手項。**

- **`PRODUCT.md` 存在且非空、非 placeholder**（`[TODO]` 或 <200 chars 視同缺）— 若無：**立刻**跑 `/impeccable init`（v3.5 前叫 `teach`，仍為 alias）。補正完成前 **NEVER** 繼續診斷、Fidelity、Decision Gates（Register 在 init 寫入 `register` 後才判 skip）、Skill sequence、Health wave；**NEVER** 把缺 md 寫進 plan checklist 當「先做 init」就過關；**NEVER** 把缺 md 當 health finding 過關。
- **`DESIGN.md` 存在且非空** — 已有 UI code 且缺檔：**立刻**跑 `/impeccable document`（或由 init 一併產出）。不得標「強烈建議」後繼續。無 UI code 時由 init 產出即可。
- 補正完成的可觀察 predicate：`node <impeccable>/scripts/load-context.mjs`（或 `context.mjs --target`）顯示 `hasProduct: true`；有 UI code 時還要 `hasDesign: true`。未過 → **STOP**，不得恢復原 mode。
- Design system tokens 檔（`design-system/MASTER.md` 或 `app.config.ts` 的 `ui` 區塊）— 用於 iterate 模式追蹤跨 phase 一致性
- **Tech stack** — detect and lock（見 Tech Stack Detection）
- **Register** — brand vs product（見 Step 1.5）

This applies to every mode. Skip the rest of `/design` only if foundation is confirmed.

### Fidelity Checkpoint Extraction

若 `PRODUCT.md` 與 `DESIGN.md` 皆已通過 Step 1 硬閘門，**必須**讀取並提取以下 8 個 fidelity checkpoint 維度，供後續 Step 2.5 比對使用：

| 維度                        | 主要來源                  | 提取重點                                                                  |
| --------------------------- | ------------------------- | ------------------------------------------------------------------------- |
| **Color System**            | `DESIGN.md`               | 所有 color roles、tokens、OKLCH/hex 值、color strategy（restrained/committed/full palette/drenched） |
| **Typography**              | `DESIGN.md`               | 字體名稱、sizing 規則、特殊設定（如 tabular-nums）、line length cap        |
| **Spacing & Layout Tokens** | `DESIGN.md`               | 間距慣例（page padding、card gap、form gap 等）                            |
| **Component Conventions**   | `DESIGN.md`               | Nuxt UI 元件清單、自訂元件清單（StatCard、EmptyState 等）                  |
| **Interaction Patterns**    | `PRODUCT.md` + `DESIGN.md`| 各介面的互動規範（CRUD sort/filter/pagination、empty state CTA 等）         |
| **Layout Architecture**     | `DESIGN.md`               | 各介面的 layout 規格（desktop sidebar+breadcrumb、auth centered card 等）  |
| **Design Principles**       | `PRODUCT.md`              | strategic principles（如「數據是主角」、「路徑最短」等）                    |
| **Brand & Anti-references** | `PRODUCT.md`              | brand voice、tone、anti-references（過度裝飾、冰冷金融風、遊戲化等）        |

這些 checkpoint 是後續 Fidelity Check 的**唯一比對來源**——不使用 PRODUCT.md / DESIGN.md 以外的假設。

### Tech Stack Detection

Detect the project's UI tech stack to ensure all design skills produce compatible output:

1. **Check `DESIGN.md`** — if it specifies a stack, use it（DESIGN.md 通常含 component library 與 styling 系統）
2. **Check project files:**
   - `nuxt.config.ts` or `nuxt.config.js` exists → **Nuxt project**
     - If `@nuxt/ui` in `package.json` dependencies → Stack = **Nuxt UI** (use `<UButton>`, `<UCard>`, etc.)
     - If no `@nuxt/ui` → Stack = **Tailwind CSS** (with Vue/Nuxt conventions)
   - Otherwise → Stack = **Tailwind CSS** (default)
3. **Propagate to all skills** — when the plan references new-work build、`/impeccable colorize`、`/impeccable typeset` 等，include the detected stack so output uses the correct component library and conventions

| Detected Stack   | Component Style                         | Color System                                    | Skill Integration                                                       |
| ---------------- | --------------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------- |
| **Nuxt UI**      | `<UButton>`, `<UCard>`, `<UTable>` etc. | `primary`/`neutral`/`error` via `app.config.ts` | Run `/nuxt-ui` alongside design skills; use Nuxt UI's built-in variants |
| **Tailwind CSS** | Plain HTML + Tailwind utility classes   | Custom CSS variables or Tailwind config         | Standard impeccable workflow                                            |

**When Nuxt UI is detected:**

- `/impeccable colorize` and `/impeccable typeset` recommendations must map to Nuxt UI's theme system (`app.config.ts` → `ui` key), not raw CSS
- `/impeccable polish` checks against Nuxt UI component conventions and design tokens
- new-work build produces `<UComponent>` markup, not raw HTML+Tailwind
- Include `/nuxt-ui` skill knowledge when building or reviewing components

### Step 1.5: Register Detection

每個 design task 強制分類成兩種 register，影響所有 sub-command 的判斷基準：

| Register    | 適用情境                                            | 設計取向                              |
| ----------- | --------------------------------------------------- | ------------------------------------- |
| **brand**   | marketing、landing、campaign、long-form content、portfolio — 設計**就是**產品 | 視覺優先、風格大膽、可全 palette 或 drenched |
| **product** | app UI、admin、dashboard、tool — 設計**服務**產品   | 任務優先、restrained 預設、克制陳述     |

**判斷優先序**（first match wins）：

1. 任務文字本身的線索（"landing page" → brand；"dashboard" → product）
2. 焦點頁面 / 檔案 / route（`pages/landing.vue` → brand；`pages/admin/*.vue` → product）
3. `PRODUCT.md` 的 `register` 欄位（推薦明確標註）

若 PRODUCT.md 缺 `register` 欄位，推論結果當 assigned，**開 Register 決策頁**（見 [decision-page.md](decision-page.md) § Register）。有 `register` 欄位 → skip 該頁。**NEVER** 只推論不開頁。

**為什麼 clade design 也要管 register**：plan 內推薦的 skill 序列在 brand vs product 不同——例如 brand 模式下 `/impeccable overdrive` 是合理 hero 選項；product 模式則幾乎永遠是 over-design。register 進 plan rationale，能避免推錯方向。

### Step 1.6: Register × Command Matrix

每個 sub-command 對 brand vs product register 的取向（plan 決策時逐條對照）：

| Sub-command | brand register | product register | 備註 |
| --- | --- | --- | --- |
| `/impeccable bolder` | ✅ 預設 | ⚠ 慎用（限 hero / landing 區塊） | brand 場景的 amplification 工具；product 全頁 bolder 易壓垮可讀性。**v3.9**：有 DESIGN.md / token 時 bolder 改用 hierarchy / proportion / density / copy 讓既有語言更果斷，不新造 color / gradient / effect — product 端更安全 |
| `/impeccable quieter` | ⚠ 慎用 | ✅ 預設 | product UI 的 retreat 工具；brand 全 quieter 通常喪失亮點 |
| `/impeccable colorize` | ✅ 自由（full palette / drenched 皆可） | ⚠ restrained / committed 為主 | product 預設 restrained；brand 可上 full palette |
| `/impeccable overdrive` | ✅ 限 hero | ❌ 幾乎永遠 over-design | product overdrive = 雜訊 |
| `/impeccable distill` | ⚠ 視內容 | ✅ 預設 | product 任務優先，先簡化；brand long-form 不一定要 distill |
| `/impeccable harden` | ⚠ 限 form / CTA / payment | ✅ 必要 | product CRUD/data 非常需要；brand 主要在 form/CTA 邊界 |
| `/impeccable onboard` | ⚠ 限 trial flow / signup | ✅ 預設 | product 的 first-run、empty state、activation hint 必備 |
| `/impeccable delight` | ✅ 自由（personality 載體） | ⚠ 微量（只在轉場/成功 CTA） | product 過多 delight = 干擾任務 |
| `/impeccable layout` / `/impeccable typeset` / `/impeccable polish` / `/impeccable audit` / `/impeccable clarify` / `/impeccable animate` / `/impeccable optimize` / `/impeccable adapt` / `/impeccable critique` / `/impeccable extract` / `/impeccable live` / `/impeccable shape` / `/impeccable init` / `/impeccable document` / new-work build | ✅ 通用 | ✅ 通用 | 兩個 register 都需要；只是調強度而非取向 |

**規則**：plan 草擬完成後，逐條 sub-command 對照本表 — 若選擇與 register 衝突（如 product 模式選 `/impeccable overdrive`），rationale 必須額外說明為何此 case 例外（通常是 brand-style hero 嵌在 product app 中、或 product 內的 marketing 頁面）。

### Step 1.7: Copy Tone Lock（強制）

**所有** plan target 若涉及 user-facing string（labels / buttons / errors / empty states / help text / placeholder / toast / modal / confirm dialog 等）**MUST** 套用文案語氣硬性規則：

> **Golden rule**：UI 顯示給終端使用者的英文 / 技術詞，若屬軟體開發範疇（HTTP / auth / DB / system internals / dev concepts）→ **一律避免**；若屬該產品行業的專業詞且目標使用者熟悉 → 可保留。
>
> 「目標使用者熟悉」的判定依據是 **`PRODUCT.md` 的 Users 欄位**，不是開發者直覺。

完整黑名單、替換範例、行業白名單、判定流程：見 `references/copy-tone.md`。

**propose 套用方式**：

- diagnosis 階段 — 若 `Copy` 維度觸發任一 engineering jargon signal，標 ★★☆☆☆ 以下，列入 Core Plan
- Core Plan 排 `/impeccable clarify [target]` 在 DRIFT 修復之後、其他 skill 之前
- brief `/impeccable clarify` **MUST** 註明 "follow `references/copy-tone.md`; eliminate engineering jargon; preserve only domain-appropriate terms per PRODUCT.md Users"
- Register 嚴格度：**product** ★★★ 嚴格 / **brand** ★★ 中等 / **DX product**（使用者就是工程師）★ 寬鬆

**Block 條件**：未通過 Copy Tone Check 的 plan **不得**進 ship phase — Exit Criteria 不算完成。例外需在 plan 顯式標註 `Copy Tone Exception` 區塊（理由必引 PRODUCT.md Users 欄位佐證），詳見 copy-tone.md「Exception 機制」。

### Step 1.8: Modern Web Baseline Query（強制）

對應規約：`~/.cursor/rules/modern-web-mcp.mdc`（user-level rule）+ cookbook：`~/offline/clade/vendor/snippets/modern-web-guidance/README.md`。

**所有** plan target 若涉及以下任一主題，plan 起手 **MUST** 先 query `GoogleChrome/modern-web-guidance` skill，把 query 結果 inline 寫進 plan：

- **UI / Layout**：modal / dialog、popover / tooltip、dropdown / menu、tab bar、accordion、form 驗證 UX、container queries、`:has()`、scrollbar 樣式
- **Scroll / Motion**：View Transitions、scroll-driven animations、parallax、scroll-snap
- **Performance**：LCP / INP / CLS、`content-visibility`、`fetchpriority`、image / font 優化、long task 拆分、speculation rules
- **Security**：CSP、WebAuthn / Passkey、Trusted Types、COOP/COEP
- **Legacy migration**：把既有 `<div role="dialog">` / portal-tooltip / JS-driven carousel / IntersectionObserver 視差**升級到** modern API

**Plan 寫入格式**：

```markdown
### Modern Web Baseline Check

涉及主題：modal / popover  ← 從上面清單挑命中項目

Query 結果摘要：
- `dialog` use case：`<dialog>` element + `showModal()` / `close()`，Widely available，無需 polyfill
- `popover` use case：Popover API (`popover` attr) + Anchor Positioning，Newly available，舊瀏覽器 fallback 用 `position-try`

Baseline 決策：
- Modal 用 `<dialog>`（Widely → 無 fallback）
- Popover 用 Popover API + Anchor Positioning（Newly → 含 fallback positioning）

若改既有 anti-pattern：
- 既有 `<div role="dialog">` modal 同步升級到 `<dialog>`（trade-off：略增 migration cost，但獲 native focus trap + ESC + a11y）
```

**Block 條件**：plan 涉及上述主題但缺 Modern Web Baseline Check 區塊 → **不得**進 build / ship phase。例外需在 plan 顯式標註 `Modern Web Exception` 區塊（理由：例如「目標瀏覽器矩陣含 IE11，必須降級」），但極少數情況才會用到。

**為什麼是強制 step**：模型訓練資料對 modern web API 的記憶幾乎一定過時，憑記憶寫 modal / popover / animation / vitals optimization 看起來合理但 runtime 偏差或低於現代基線。query skill 是**plan 階段的強制動作**，不是「想到才查」的 advisory — 對應 user 偏好「不是想到的時候才主動調用」。

cookbook 內有 4 大類典型場景 → query keyword → baseline 對照表，省去你重 derive。

### Step 1.9: Component Candidates（強制，偵測到 Nuxt UI stack 時）

**MUST Read [references/component-candidates.md](references/component-candidates.md) before proceeding** —— 三件事的完整判準（query / 列 ≥2 候選 / 開 Component 決策頁讓 user 選）、plan 寫入格式、block 條件，以及 `/impeccable live` 在 Nuxt 專案的正確接法（走靜態 HTML mockup，**NEVER** 改 `app.vue` 掛 live）都在該檔。

Step 1.8 管 platform API 基線，這一步管**元件選擇**。**NEVER** 憑訓練記憶列元件；**NEVER** 只列一個候選就寫進 plan；**NEVER** 代選。plan 涉及 UI surface 但缺 Component Candidates 區塊、該區塊只列一個候選、或沒開決策頁 → **不得**進 build / ship phase。

---

## Decision Gates

Foundation 與 mode 診斷做完後、輸出剩餘 plan 之前，**每一個**命中的 gate 都開決策頁。loop / 路徑 / payload / skip 的 SoT 是 [decision-page.md](decision-page.md) — **MUST Read before the first page**。

```
Register → Direction → Component → Skill sequence
```

Shape brief 在 Skill sequence ANSWER 之後、且選中序列含 `/impeccable shape` 時才開。`health` 只開 Health wave 頁。meta 問題不開頁。Skill sequence 頁的 ANSWER 就是執行授權——**NEVER** 再問「要進入 Plan Mode 逐步執行這些改進嗎？」。

---

## Mode-Specific Procedures

確定 mode 後，**MUST** Read 對應的 reference 檔取得完整流程、plan 模板和 exit criteria，再開始診斷。Decision Gates 的 skip 由各 mode 檔覆寫，loop 不複製。

| Mode | Reference | 一句話摘要 |
| --- | --- | --- |
| `new` | **MUST Read [mode-new.md](mode-new.md) before proceeding** | 從零建 UI：foundation → 決策頁 → new-work build → enhance → ship |
| `improve` | **MUST Read [mode-improve.md](mode-improve.md) before proceeding** | 診斷既有 UI：8 維度 rubric + Fidelity Check → 決策頁 → targeted plan |
| `iterate` | **MUST Read [mode-iterate.md](mode-iterate.md) before proceeding** | 多 phase 專案：scoped assessment + design system drift check → Skill sequence 頁 |
| `health` | **MUST Read [mode-health.md](mode-health.md) before proceeding** | 全棧深度體檢：苛刻 8 維度 → refactor waves → Health wave 決策頁 → propose |

---

## Output Rules

1. **Always read code first** — never plan blind
2. **Be specific** — name files, components, line ranges
3. **3-6 skills per plan** — split overflow into "Follow-up" or "Carry-Forward", never dump all 23
4. **Explain exclusions** — "skipping /impeccable animate — this is a data-entry form where motion distracts"
5. **Check mutual exclusivity** — see `references/skill-map.md` "Mutual Exclusivity" section. Never recommend `/impeccable bolder` + `/impeccable quieter` together; pick one direction. Run `/impeccable distill` before `/impeccable bolder`, not alongside.
6. **Follow canonical order** — deviations need explicit justification
7. **End with /impeccable polish** — it's always the last step
8. **Respect time** — if 1-2 skills suffice, say so. Don't over-prescribe.
9. **Decision pages, then execute** — `/design new|improve|iterate` 的 user 授權是 Skill sequence 決策頁的 ANSWER，不是聊天問句。選完直接開始 invoke 選中序列。**NEVER** 輸出「要進入 Plan Mode 逐步執行這些改進嗎？」。meta/strategy 問題（"should we adopt X"、"what's the difference between Y and Z"）不開頁，直接答。
10. **Cite references** — When recommending design systems or patterns, cite specific examples from `references/design-systems.md`. Include industry-specific benchmarks and maturity assessments from `references/diagnosis.md`.
11. **Copy tone enforcement** — 任何 plan 涉及 user-facing string 時，**MUST** 套用 Step 1.7 Copy Tone Lock 規則：(a) Core Plan 排 `/impeccable clarify` 並 brief 引用 `references/copy-tone.md`；(b) Exit Criteria 必含「Copy Tone Check passed」；(c) 例外保留的開發英文必有 `Copy Tone Exception` 標註並引 PRODUCT.md Users 佐證。違反 = plan 無效。
12. **Component candidate enforcement** — 偵測到 Nuxt UI stack 且 plan 涉及 UI surface 時，**MUST** 套用 Step 1.9：(a) 每個 surface 有 Component Candidates 區塊；(b) **候選 ≥2 個**，單一候選視同未做比較；(c) 每個候選的元件與 slot / variant 出自 `nuxt-ui-remote` query 而非記憶；(d) 開 Component 決策頁讓 user 選，agent NEVER 代選。違反 = plan 無效。
13. **Foundation hard gate** — 缺 `PRODUCT.md`（空 / placeholder 同缺）或有 UI 卻缺 `DESIGN.md` 的輸出 **不算** `/design`。必須立刻 init / document；把缺檔寫進 plan checklist、skip Fidelity、或當 health finding 過關 = 違反。

## Diagnostic Skills (assess without changing code)

Three standalone diagnostic / iteration tools sit **outside** the production pipeline. Invoke as needed — they are inputs to planning or interactive 探索, not steps in execution.

| Tool | Produces | When to use |
|---|---|---|
| `/impeccable critique [target]` | UX evaluation with persona testing: hierarchy, IA, emotional resonance, cognitive load. Qualitative + quantitative score。v3.1+ **每次跑會寫快照到 `.impeccable/critique/<ts>__<slug>.md`**（含 P0/P1 計數 + 全報告），後續 `/impeccable polish` 同 target 會自動讀作 input。`.impeccable/critique/ignore.md` 是 user-curated「不要再 raise」清單（plain markdown，每行一條）。 | **Early** — as part of `improve` mode Step 2 to surface directional issues before the structural rubric. Also useful when you don't trust your own read of the design. |
| `/impeccable audit [target]` | Severity-rated issue list: a11y, performance, theming drift, responsive. Critical/High/Medium breakdown. v3.9 detector 共 41 deterministic rules（v3.5 加 14 條，引擎換 `htmlparser2` ~20x 快）。 | **Late** — right before `/impeccable polish` to verify readiness. Also as a periodic health check during `iterate`. |
| `/impeccable live` | 在 dev server 瀏覽器中 hover/挑元素，當下生成多個視覺變體並挑選 → 寫回原始碼。 | **互動探索** — 對特定元件想試多種風格但難以言述時。Vite/Next React/TSX、Nuxt、純 HTML 都支援。需 dev server 運作中。 |

`/impeccable critique` tells you **whether the design works** as an experience. `/impeccable audit` tells you **whether the implementation is production-safe**. `/impeccable live` lets you **iterate visually instead of textually**. They rarely substitute for each other.

> **v3.1 critique snapshot vs clade design-review.md 邊界**：
>
> - `.impeccable/critique/<ts>__<slug>.md`（impeccable 自管）= impeccable runtime 內部 state；給 `/impeccable polish` 讀回 P0/P1 backlog 用，user 一般不直接看
> - `openspec/changes/<name>/design-review.md`（clade Step 6 寫）= spectra change deliverable；給 archive gate / reviewer / spectra-ingest 用，會 commit
>
> 兩者並存不衝突。clade Step 6 寫 design-review.md 時可在 「Planned Skills」 段提一句「v3.1 critique snapshot 位於 `.impeccable/critique/`，包含本輪 P0/P1 細節」當 cross-reference，但不要把 critique 快照內容塞進 design-review.md（會重複、且 critique 自己會 supersede）。

## Canonical Skill Order (production pipeline)

When executing a multi-skill plan, follow this sequence (skip what's not needed):

```
/impeccable init                ← foundation：建立 PRODUCT.md + DESIGN.md（缺則硬停補正，不是 plan 起手）｜v3.5 前叫 teach（alias）
/impeccable document            ← (alt) 已有 code 但無 DESIGN.md 時，從 code 反推 DESIGN.md
/impeccable shape                          ← (optional) 寫 code 前需求釐清 — 見 `new` mode 判準；確認走 Shape brief 決策頁
  ↓
Decision Gates                  ← Register / Direction / Component / Skill sequence（skip 見 decision-page.md）
new-work build                  ← 描述目標介面，走 impeccable new-work；**NEVER** 輸出 `/impeccable craft`
/impeccable distill                        ← simplify (if cluttered)
  ↓
/impeccable layout                         ← structure & layout
/impeccable typeset                        ← typography
/impeccable colorize | /impeccable bolder | /impeccable quieter  ← color & intensity (pick one direction)
  ↓
/impeccable animate                        ← motion
/impeccable clarify                        ← copy & messaging
/impeccable delight                        ← personality & joy
/impeccable overdrive                      ← (optional) ambitious wow-factor — brand register only
/impeccable harden                         ← resilience, edge cases
/impeccable onboard                        ← first-run flows、empty states、activation
  ↓
/impeccable optimize                       ← performance
/impeccable adapt                          ← cross-platform (if needed)
/impeccable extract             ← consolidate patterns into design system (if applicable)
  ↓
/impeccable audit                          ← diagnostic verification (Critical must = 0)
/impeccable polish                         ← always last (final pass + design-system alignment)
```

**This order is mandatory.** Rationale: fix structure before visuals, visuals before experience, everything before hardening, audit → polish always final. If you need to deviate, state why in the plan.

## Step 6: Persist Evidence（Spectra 整合）

若偵測到 active Spectra change（Step 0.5），完成診斷和計劃輸出後 **MUST Read [persist-evidence.md](persist-evidence.md) § design-review.md template** 並寫入 `openspec/changes/<name>/design-review.md`。此檔案是 `pre-archive-design-gate.sh` hook 的主要檢查依據。

## Reference Resources

### Internal References (always consult)

- `references/design-systems.md` — Industry-categorized design system index (209 systems)
- `references/skill-map.md` — Issue → Skill mapping + library recommendations
- `references/diagnosis.md` — 8-dimension diagnostic rubric + maturity model
- `references/copy-tone.md` — UI 文案語氣規則：避免軟體開發範疇英文、保留行業共識專業詞（Step 1.7 Copy Tone Lock 的權威來源）
- `decision-page.md` — 決策頁路徑、loop、exit code、六個 gate 的 skip / payload / unattended default（任何 user-facing 選擇前 MUST 讀）
- `references/health-audit.md` — `health` 模式全棧深度體檢方法論：苛刻校準原則、8 維度 rubric + codebase-memory-mcp query recipe、Impact×Effort×Risk wave 排序、propose funnel、輸出模板（執行 `/design health` 前 MUST 讀）

### When to Cite External References

| Mode              | Citation Pattern                             |
| ----------------- | -------------------------------------------- |
| `/design new`     | Cite similar industry systems as inspiration |
| `/design improve` | Cite mature systems as benchmarks            |
| `/design iterate` | Cite maturity model for progression tracking |

### Key External Resources

- [awesome-design-systems](https://github.com/alexpate/awesome-design-systems) — Comprehensive index
- [Design Systems Repo](https://designsystemsrepo.com/) — Searchable database
- [Component Gallery](https://component.gallery/) — UI pattern reference