@qijenchen/design-system 0.1.0-beta.10 → 0.1.0-beta.13

package/ds-canonical/skills/deep-audit-cross-codex/references/phase-a-workflow.md

@@ -0,0 +1,123 @@
+# Phase A — Claude solo full audit workflow
+
+## A.0 全盤閱讀 file list canonical(禁 sample)
+
+### 治理 home(always-load + path-scoped)
+- `CLAUDE.md` 全文
+- `.claude/rules/meta-patterns.md`(31 active M-rules,M1-M32 with M27/M33/M34/M35 retired)
+- `.claude/rules/spec-rules.md`
+- `.claude/rules/ui-development.md`
+- `.claude/rules/story-rules.md`
+- `.claude/rules/self-verify.md`
+- `.claude/rules/README.md`
+
+### Reference SSOT(快速索引)
+- `.claude/references/ssot-index.md`
+- `.claude/references/ssot-consultation.md`
+- `.claude/references/build-ui-canonicals.md`
+- `.claude/references/naming-conventions.md`
+- `.claude/references/ui-dev-rules.md`(若存在)
+- `.claude/references/props-naming.md`
+- `.claude/references/tailwind-gotchas.md`
+
+### DS spec.md(全部)
+```bash
+# 列舉所有 spec.md
+find src/design-system -name "*.spec.md" -type f
+# 預期 ~60 file:components/* + patterns/* + tokens/*
+```
+
+每個必 Read 全文(spec ≤ 300 lines budget,foundational SSOT ≤ 800-1200)。
+
+### 記憶
+- `~/.claude/.../memory/MEMORY.md`(index)
+- 對 MEMORY.md 列的每個 active project memory file Read 全文(`project_*.md`)
+- 對 feedback memory(`feedback_*.md`)只讀 description 比對 user 提的 topic 是否觸及 → 觸及才 Read 全文
+
+### Output gate
+
+A.0 結束時 output `.claude/planning/<date>-phaseA-preflight.md`(session-local,不 commit):
+
+```markdown
+# Phase A.0 全盤閱讀清單
+
+## 讀完
+- CLAUDE.md(<N> lines)
+- meta-patterns.md(31 active M-rules verify list)
+- spec.md ×<N>(file list)
+- tokens spec.md ×<N>
+- patterns spec.md ×<N>
+- memory active files: <list>
+
+## 預警點(讀過程發現的疑似漂移 / TODO)
+- <spec X 提到 Y 但 src/ 沒實作>
+- <token Z 0 consumer>
+- ...
+```
+
+## A.1 全 dim deep audit chain(per design-system-audit SSOT)
+
+直接 invoke `/design-system-audit --deep`。每 dim sub-agent dispatch prompt 必含:
+
+```
+你是 dim <N> sub-agent。NO-SAMPLE STRICT NO-ESCAPE — 必 DS-wide 全盤掃,
+禁 sample top N / 禁 heavy agent skip。觸發 `check_audit_sample_escape.sh`
+BLOCKER 字串(「sample」「top N」「heavy agent skip」「為節省」「先抽樣」
+「pick representative」)= 立刻撤回 dispatch。
+
+每 finding 必 cite: <file:line> + <引文 quote> + <為何違反 spec / rule>
+
+不確定 → STOP propose,別假答案。
+```
+
+## A.2 Triage rubric
+
+詳 `triage-rubric.md`(scope classifier + propose format)。
+
+## A.3 Autonomous batch 7 軸 optimize 清單
+
+對齊 CLAUDE.md `# 自主執行 canonical`:
+
+1. **言簡意賅** — comment / spec / prop name 短而精
+2. **效率 + 效能** — 避 unnecessary re-render / memoization gap / O(N²) algorithm(可 chain `/performance-audit`)
+3. **SSOT 鐵律** — M17 token / primitive / pattern consume;M23 既有 canonical 優先;M29 anchor preflight;M30 wrapper extends primitive
+4. **易懂 + 維護 + 擴充** — file ≤ budget;function ≤ 80;naming 一致(`# 命名與語言一致性`)
+5. **世界級 + 一致設計語言** — mindset #1 + M8 ≥3 家 cite + M22 inline cite + M26 propose 前 WebFetch
+6. **完整 self-verify** — M20 score / M31 dual-track 5-step / M32 pixel-quantified audit
+7. **自動 self-improve** — M14 5-layer pipeline / M20 best-practice scoring
+
+## A.4 Verify gate(per self-verify.md 4 階段)
+
+| Layer | Cmd | PASS criteria |
+|---|---|---|
+| TypeScript | `npx tsc -b` | 0 errors |
+| Content | `node scripts/audit-content-quality.mjs --check` | ✅ No content drift |
+| Canonical | `node scripts/extract-canonical-rules.mjs` | ✅ All extracted rule keywords covered |
+| Component invariants | `node scripts/data-table-invariants.mjs`(若觸動 DataTable)| PASS |
+| Visual | `/visual-audit --scope=changed` | playwright snapshot diff Δ < 0.1% |
+| Pixel-quantified | M32 audit(若動 alignment / spacing)| `rect.top / left / height` numeric verify |
+
+任一 FAIL → STOP,不可進 Phase B。
+
+## A complete output
+
+```markdown
+# Phase A 完成
+
+## Findings(全 dim per design-system-audit SSOT)
+- P0: <N> 項
+- P1: <M> 項
+- P2: <K> 項
+
+## SSOT-UI/UX(待 user 拍板,中文人話 propose)
+<決策 1-N per triage-rubric.md format>
+
+## Autonomous landed(commit <hash>)
+- <N> 項 spec / hook / story / code 修正
+- file:line diff link
+
+## 不 verify 但 Phase A 結論
+- <列出僅 grep 看到但未跑 visual 的 case>
+
+→ 等 user 拍板 SSOT-UI/UX 後 → 進 Phase B
+```

package/ds-canonical/skills/deep-audit-cross-codex/references/phase-b-codex-brief.md

@@ -0,0 +1,165 @@
+# Phase B — Codex parallel audit + 比稿辯論
+
+## B.0 Transport discovery(per codex-collab/SKILL.md Step 0.4)
+
+3-test 順序固定:
+```bash
+ls -la node_modules/.bin/codex && node_modules/.bin/codex --version   # 1 Local CLI(canonical)
+which codex 2>/dev/null && codex --version 2>/dev/null                 # 2 Global(罕見)
+ls -la ~/.codex/auth.json                                              # 3 Auth(sanity)
+```
+
+**Decision**:1 ✅ → local CLI / 1 ❌ + 2 ✅ → global / 1+2 ❌ + 3 ✅ → `npm install` / 全 ❌ → 報 user。**禁 Explore agent 替身**(M31)。
+
+## B.1 Brief template
+
+⚠️ **Faithful relay invariant**(M31 Step 0.05,user-verbatim,不可只送 paraphrase):
+
+```
+## User 原話(verbatim)
+「<user 在本 session 對 deep audit 的原話 quote,中英 / 符號 / 圖文 ref 全保>」
+
+## Claude Phase A 結果摘要
+
+### 全盤閱讀
+- 讀完:CLAUDE.md / 31 active M-rules / spec.md ×<N> / tokens / patterns / memory active
+
+### 全 dim NO-SAMPLE deep audit findings
+- P0: <列具體 file:line + 違反 spec / rule>
+- P1: <同>
+- P2: <同>
+
+### SSOT-UI/UX 已 ASK user
+- <列 N 項>
+
+### Autonomous landed
+- <列 N 項 file:line + commit hash>
+
+### Phase A 結論(不 verify 但抓到)
+- <列 grep 看到 / suspect drift / 未跑 visual>
+
+## 你的任務(Phase B,獨立)
+
+1. **全盤閱讀**(per A.0 file list,不 sample):
+   - CLAUDE.md / `.claude/rules/*` / `.claude/references/*`
+   - `packages/design-system/src/**/*.spec.md` 全部(~60 file)
+   - `packages/design-system/src/tokens/**/*.spec.md` + `packages/design-system/src/patterns/**/*.spec.md`
+   - `~/.claude/.../memory/MEMORY.md` index + active project memory
+
+2. **全 dim deep audit NO-SAMPLE**(對齊 `.claude/skills/design-system-audit/SKILL.md` Group A-P 全 dim per SKILL.md):
+   - 每 dim 全 DS-wide 掃,禁 sample top N
+   - 每 finding 必 cite: <file:line> + <quote> + <違反 spec / rule>
+
+3. **整理完整報告**(P0 / P1 / P2 分類):
+   ```
+   ### Codex Phase B audit
+   - P0: <list>
+   - P1: <list>
+   - P2: <list>
+
+   ### 跟 Claude Phase A 對照
+   - Claude 抓 + 你不同意:<list + cite>
+   - 你抓 + Claude 漏:<list + cite>
+   - 兩邊都漏的盲區:<list + cite>
+
+   ### 真理由 disagreement(必 cite battle)
+   - <題 1>: Claude 立場 / 你立場 / spec.md path:line 引文 / world-class ≥3 家對照
+   ```
+
+4. **禁**:
+   - frame 答案進 Claude 思路(不可 paraphrase Claude 結論)
+   - sample / heavy agent skip(NO-SAMPLE STRICT)
+   - pass-through 共識（必獨立 own report）
+   - 直接給 user verdict（共識由 Claude Phase B.5 synthesize）
+
+## 請獨立解讀 user 原話(per M31 Step 0.05)
+
+User 原話可能跟我 paraphrase 不同。請以「你直接看 user 原話該怎麼解讀」為主,
+不要被 Claude 結論 frame。如果 user 想要的方向你判斷跟我不同,直接寫出來。
+
+## Cite invariant(M22)
+
+每 claim 必附 inline cite:URL / GitHub source path + line / screenshot ref。
+無 cite = unverified rumor,自動降 P2 「pending verification」。
+```
+
+## B.2 Step 4 self-check 必過(M22/M23/M27→M23(c)/M8)
+
+對 codex reply 跑 4 題:
+
+| # | Check | 失敗 → |
+|---|---|---|
+| 1 | M22 cite check — codex 引的 benchmark 有 inline URL / GitHub line? | reply 要求補 cite |
+| 2 | M23 DS-first — codex 建議是否覆蓋 DS 既有 canonical(spec.md / token / variant)? | 必 grep verify DS 既有,有命中 → 拒絕 codex / 修正 |
+| 3 | M23(c) prop namespace — codex prop name 是否撞 DS 既有? | wrap-and-rename |
+| 4 | M8 ≥3 source — codex 只引 1 家? | reply 要求補到 3 家 |
+
+## B.3 Step 4.5 Verify each claim(anti-pass-through)
+
+逐條 codex finding 過:
+
+```
+Finding N: <codex claim 一句話>
+
+Verify:
+1. Grep DS-internal: rg "<keyword>" src/ → <hit / miss + 行號>
+2. WebFetch external(若 cite world-class): URL → <真 quote 對照>
+3. Run invariant script(若 codex 給數字): bash <script> → <實 value vs codex value>
+4. Counter-example scan: grep <pattern> DS-wide → <反例 / 無>
+
+Verdict: ✅ verified / ❌ FALSE / ⚠️ partial
+Reasoning: <一句話>
+```
+
+## B.4 Cite battle template
+
+```
+Disagreement N: <topic>
+
+| Side | Position | Cite | Quote |
+|---|---|---|---|
+| Claude Phase A | <stance> | <file:line / URL> | 「<quote>」 |
+| Codex Phase B | <stance> | <file:line / URL> | 「<quote>」 |
+
+WebFetch external:
+- Polaris: <URL> → 「<quote>」
+- Material: <URL> → 「<quote>」
+- Atlassian: <URL> → 「<quote>」
+
+Verdict: <Claude / Codex / Both / STOP-ask-user>
+Reasoning: <cite + world-class consensus + DS internal canonical alignment>
+```
+
+## B.5 Step 5 比稿 matrix(per finding)
+
+```
+| Finding | Claude v1 | Codex v1 | Verdict | Final synthesized |
+|---|---|---|---|---|
+| <N> | <stance> | <stance> | ✅ accept C / ✅ accept C+ / ✅ accept Claude / 修正 = synthesize / 重啟 | <final 方案> |
+```
+
+**禁** pass-through 直接 paste codex / 「兩邊都對」打太極 / vote without cite。
+
+## Phase B complete output
+
+```markdown
+# Phase B 完成
+
+## Codex independent findings(NO-SAMPLE)
+- P0: <N> / P1: <M> / P2: <K>
+
+## 比稿結果
+- Claude 抓 + Codex 漏: <list>
+- Codex 抓 + Claude 漏: <list>(這些是 Phase A 漏掉的盲區!)
+- Cite battle resolved: <K 題,各題 verdict>
+- Cite battle deferred(evidence 對等): <N 題,STOP 等 user>
+
+## 共識 SSOT-UI/UX(中文人話 propose)
+<決策 1-N per triage-rubric.md format>
+
+## 共識 autonomous landed(commit <hash>)
+- <N> 項
+- file:line + diff link
+
+→ 進 Phase C
+```

package/ds-canonical/skills/deep-audit-cross-codex/references/triage-rubric.md

@@ -0,0 +1,91 @@
+# Triage rubric — SSOT-UI/UX vs Non-SSOT scope classifier
+
+## Scope classifier(critical 第 1 步)
+
+### SSOT-UI/UX substantive(必 ASK user)
+
+任一命中 → **STOP propose 等 user A/B**:
+
+- 動 `packages/design-system/src/components/<X>/<X>.tsx` 的 cva variant / size / state(視覺 surface)
+- 動 spec.md 的「視覺結構 / canonical / SSOT / 何時用 / 何時不用 / 邊界案例 / Layout Family」段落 substantive meaning
+- 加 / 刪 / 改 token(`tokens/**/*.css` / `*.spec.md`)
+- 加新 prop / 重命名 prop / 改 prop default value(API contract)
+- 跨元件 design language 改動(同類 row primitive 重新訂 padding / dismiss canonical 跨元件改)
+- 新 family 宣告 / 改 family 歸屬
+- 新 pattern 加入 `patterns/` 或既有 pattern scope 改變
+
+### Non-SSOT(AUTO 整批做完,M33 anti-defer)
+
+- Bug fix(spec 既有 canonical + code 跑掉 → 對齊 spec)
+- Code clean(unused import / dead export / typo / 排版)
+- Refactor 不動行為(extract helper / rename internal symbol / consolidate condition)
+- 命名一致對齊既有 canonical(per `# 命名與語言一致性`)
+- Test / audit / verify(playwright / invariant script / hook regex 加廣)
+- Audit dim / hook 加廣(對齊 spec wording 廣度,M34)
+- Pointer / cross-link 補完整(reciprocal Dim 3 / SSOT pointer)
+- Spec typo / markdown layout / 標點
+- Memory file rotate(已 absorb → demote)
+- Governance / hook / skill 內部 refactor(無 BLOCKER 邏輯改)
+
+## SSOT-UI/UX propose 中文人話 format(per `feedback_propose_in_plain_chinese.md`)
+
+```
+### 決策 N:<一句話標題,zero jargon>
+
+**現況**:
+- <目前 spec / code 行為,具體一句話人話>
+- 證據:<file:line>
+
+**影響**:
+- 不改:<具體後果>
+- 改了:<具體後果>
+
+**選項**:
+- A. <做法 1>
+  - 後果:<好處 / 代價>
+  - 涉及檔案:<count + file 列表>
+- B. <做法 2>
+  - 後果:<好處 / 代價>
+  - 涉及檔案:<count + file 列表>
+- C. 不動
+  - 後果:<漂移持續累積 / 或維持現況的成本>
+
+**我推**:<A / B / C> 因 <理由>
+```
+
+### 4-Q gate(propose 前必 inline 跑,失敗 → 不列 option)
+
+| Q | Check | 失敗 → |
+|---|---|---|
+| Q1 M22 cite | 3-column owner table(spec path:line / canonical sentence / conflicting code)| 撤回 propose,先補 anchor |
+| Q2 M17 SSOT | 既有 token / primitive / pattern 列消費清單 | 撤回,先 consume 既有 |
+| Q3 Rule-of-3 | 同概念 ≥ 3 處 → 選 SSOT 其他 pointer | 撤回,選 SSOT home |
+| Q4 M10 下游 | 修上游 ≥ 3 處下游 redundant 可清 | 提案加上「下游 N 處同步 retire」 |
+
+### 禁用 jargon list(propose 內 zero tolerance)
+
+❌ `L1-L7` / `canonical` / `primitive` / `SSOT` / `consume` / `traits` / `M-rule` / `cva` / `tier` / `tokens` / `wrapper`
+✅ 翻成:`主檔` / `設計原則` / `共用零件` / `通用基底` / `共用設計來源` / `沿用` / `行為類型` / `規則 N` / `樣式拼裝表` / `層級` / `設計變數` / `外殼`
+
+## Non-SSOT autonomous 7 軸 simultaneous optimize
+
+每次動 code 前 mental check:
+
+1. **言簡意賅** — comment / spec 文字短而精;禁長 docstring;禁不必要 comment(per CLAUDE.md `# Tone and style`)
+2. **效率 + 效能** — 避 unnecessary re-render / memo gap / O(N²) algorithm / context thrashing
+3. **SSOT 鐵律** — 動 visual decision 前 grep DS 既有 token / variant / pattern(M23)/ spec.md owner(M29)/ wrapper extends primitive(M30)/ token 而非 hardcode(M17)
+4. **易懂 + 維護 + 擴充** — file size budget(governance ≤ 200/300/500/800)/ function ≤ 80 / naming 一致 / public API 穩定
+5. **世界級 + 一致設計語言** — mindset #1(Polaris / Material / Atlassian / Ant / Carbon / Apple HIG ≥ 3 cite)+ M22 inline cite + M26 propose 前 WebFetch ≥ 3 source
+6. **完整 self-verify** — M20 best-practice score ≥ 80 / M31 5-step(Layer A own + Layer C codex 比稿)/ M32 pixel-quantified audit
+7. **自動 self-improve** — M14 5-layer pipeline(對話結論 → spec / hook / SKILL / CLAUDE.md / memory 該動的全動)+ M20 stop hook auto-score
+
+任一軸明顯 degrade → 撤回方案重來,**禁** 「先這樣 / 之後優化」defer keyword(M33 BLOCKER)。
+
+## 共識決策(Phase B.5)同 format
+
+Phase B 共識(Claude + Codex 雙 verify PASS)走相同 propose / autonomous 分流:
+
+- SSOT-UI/UX 共識 → 中文人話 propose user 拍板
+- Non-SSOT 共識 → autonomous batch(7 軸 optimize)
+
+**禁** Phase B 共識降回 Phase A 已 ASK 的同 decision 重 ASK(浪費 user 時間)。已 ASK 的 → 等 user 拍板;新發現(Phase B 抓的 Phase A 漏)→ 新 propose。

package/ds-canonical/skills/delivery-handoff/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: delivery-handoff
+description: Generate stakeholder-ready handoff documentation when a product / feature is confirmed final. Produces Storybook handoff page + UI flow diagram + component usage inventory + token consumption report + a11y checklist + per-screen spec — a Figma-like inspectable delivery package. Invoke via /delivery-handoff when user says「要交付」「handoff」「交付文件」「給 X 團隊的文件」「產品確認要上線了」. **只在產品確認 final 後才 invoke**,非 prototype 階段。
+---
+
+# Delivery Handoff Workflow
+
+Purpose: 產品 / feature 通過 prototype → audit → stakeholder 決策後確認 final,需要產 **Figma-like inspectable handoff documentation** 給工程 / PM / QA / 其他 stakeholder。
+
+本 skill **不是** prototype 階段文件(那是 `/prototype` 的 notes.md),而是**正式交付包**。
+
+## When to run
+
+**明確觸發**:
+- User 說「要交付」「handoff」「交付文件」「給 X 團隊的文件」
+- User 說「產品確認要上線了」「final 了做 handoff」「給工程交接」
+- Final decision 已下 + product-ui-audit P0 都修完
+
+**不觸發**:
+- Prototype 階段(走 `/prototype`,產 exploration notes)
+- Audit 階段(走 `/product-ui-audit`)
+- DS 本身的 spec 維護(不走任何 skill,直接在 `.spec.md` 編)
+- 要跑 audit 檢查 DS 用對不對 → `/product-ui-audit`
+
+## 生態位
+
+```
+  /prototype           → exploration + shortlist
+  /product-ui-audit    → QA gate
+  [stakeholder decides final]
+  [P0 fixed, P1 resolved]
+  /delivery-handoff    ← 本 skill,只在 final confirmed 後
+```
+
+## Preconditions
+
+- 產品 / feature 已 final(stakeholder 書面或對話確認)
+- `/product-ui-audit` Zero P0(必要)/ P1 有計畫 resolve(建議)
+- 代碼已 merge 或即將 merge 到 main branch
+- 有明確 **target audience**(給工程? 給 PM? 給設計 review? 給跨團隊交接?)— AI 在 Phase 0 clarify
+
+---
+
+## 5-Phase Workflow
+
+### Phase 0 — Scope & audience
+
+**clarify with user**:
+1. 交付**哪個 feature**?(single screen? full flow? 整個 module?)
+2. **給誰**?
+   - 工程團隊(實作參考 / QA test case)
+   - PM / BA(業務理解 / 邊界 case)
+   - 設計 review(世界級評估)
+   - 跨團隊(onboarding 他們使用)
+3. **format 需求**:
+   - Storybook 原生頁(最推薦)
+   - Markdown 可 export PDF
+   - Mermaid diagram(UI flow)
+   - Screenshot / mockup 用 Storybook render
+
+### Phase 1 — Inventory 生成
+
+scan 目標 feature 的 code,自動 inventory:
+
+1. **Component 清單**(哪些 DS 元件被此 feature 消費):
+   ```
+   | Component | Count | Consumer files |
+   |-----------|-------|----------------|
+   | Button    | 12    | Checkout.tsx, Summary.tsx, ... |
+   | Dialog    | 2     | Confirm.tsx, Edit.tsx |
+   | Empty     | 1     | NoItems.tsx |
+   ```
+
+2. **Token 使用報告**:
+   ```
+   | Token | Usage | Files |
+   |-------|-------|-------|
+   | --primary | 8 hits | ... |
+   | --fg-secondary | 14 hits | ... |
+   | --error | 3 hits | ... |
+   ```
+
+3. **Layout primitives 消費**: Empty / item-layout / overlay-surface / ScrollArea / AspectRatio 各幾次。
+
+4. **A11y checklist**(先掃再人工 review):
+   - aria-label 齊全
+   - role / keyboard
+   - Dialog title
+   - color contrast(此層 AI 報 visible,人工 review 判 final)
+
+### Phase 2 — UI flow 圖生成
+
+用 **Mermaid** 產 flow(Storybook 支援 render,也可 export PDF)。
+
+範本:
+
+```mermaid
+flowchart TD
+  Start([進入 Checkout]) --> Review[結帳 Review]
+  Review -->|修改| Edit[編輯 Cart Dialog]
+  Edit --> Review
+  Review -->|確認| Payment[付款方式 Step]
+  Payment -->|信用卡| Card[Card Form]
+  Payment -->|轉帳| Bank[Bank Instructions]
+  Card --> Confirm[確認 Dialog]
+  Bank --> Confirm
+  Confirm -->|確定| Success([訂單成立])
+  Confirm -->|取消| Review
+```
+
+AI 根據 code(route / onClick / navigation)auto-generate,user review 後微調。
+
+### Phase 3 — Per-screen spec sheet
+
+每個 screen / modal / flow step 一頁 spec(Storybook 的 Handoff story,或 Markdown 章節):
+
+```markdown
+## Screen: Checkout Review
+
+**Storybook**: `Features/Checkout/Review`
+**File**: `src/app/features/checkout/Review.tsx`
+
+### 用途
+使用者進入結帳後,第一屏預覽購物車 + 小計 + 折扣碼輸入。
+
+### 主要元件
+- DataTable(訂單 items)
+- Input(折扣碼)
+- Button(套用)
+- Dialog(編輯 item 彈出)
+- Empty(購物車空狀態)
+
+### States
+- **default**: 載入後正常顯示(≥1 item)
+- **empty**: 購物車無 item — 顯示 Empty 元件 + 「回去繼續購物」CTA
+- **error**: 折扣碼無效 — Input error state + Alert 說明
+
+### Interactions
+- 點擊 item → open Edit Dialog
+- 輸入 discount → debounce 500ms → auto-validate
+- 按 Apply → post /discount API
+
+### A11y
+- ✓ 所有 icon-only 有 aria-label
+- ✓ Dialog 有 title + description
+- ✓ keyboard 可 tab 所有互動
+- ✓ color contrast 通過 WCAG AA
+
+### 邊界 case
+- 折扣碼已套用:顯示 "已套用 {code}",Apply Button 變 Clear
+- 網路錯誤:顯示 Alert + retry button
+- 折扣超過總額:capped 折扣 = 總額,顯示說明
+```
+
+### Phase 4 — Handoff Storybook page
+
+在 Storybook 建立 `Features/{Feature}/Handoff` page,內含:
+
+- **Overview**: feature 一句話重述
+- **UI Flow**: Mermaid diagram(Storybook 支援 render)
+- **Inventory**: 元件 / token / a11y 報告
+- **Screens**: 每個 screen 可點進去的 story link + inline preview
+- **Spec table**: per-screen spec 嵌入
+
+Storybook title: `Features/{FeatureName}/Handoff`
+
+此 page 就是「Figma-like 的 inspectable 交付」— stakeholder 打開就看到全景。
+
+### ⚠️ Checkpoint — User review handoff package
+
+Phase 4 產出後 pause,讓 user review:
+
+```
+📦 Handoff Package Ready
+
+Scope: {feature}
+Audience: {engineering / PM / designer / cross-team}
+Package:
+- Storybook page: Features/{Feature}/Handoff
+- Inventory: {N components / M tokens}
+- UI Flow: Mermaid diagram ({N nodes})
+- Spec sheets: {N screens}
+- A11y checklist: {N passed / M needs review}
+
+Export formats:
+- Storybook URL: {link}
+- Markdown(可 export PDF): {path}
+
+請 review:
+(a) 通過,準備 share 給 {audience}
+(b) 需要修改: ...
+(c) 還缺 ... 補齊
+(d) Audience 換人,調整語氣 / 深度
+```
+
+---
+
+## 世界級 handoff 標準(reference)
+
+本 skill 對標:
+- **Figma Dev Mode** — inspectable 元件 + token + spacing
+- **Zeplin** — per-screen spec + asset export
+- **Shopify Polaris Pattern pages** — 完整 flow + usage + edge cases
+- **Material Design Showcase** — UI + spec + code sample 三欄
+
+我們的 Storybook handoff page 整合上述 3 個 tool 的優勢到一頁。
+
+---
+
+## Non-goals
+
+- 不替代工程 code review(本 skill 是 **設計 handoff**,不是 code 品質審核)
+- 不寫實作 / fix bug(已經 audit 過,final 了才 invoke 本 skill)
+- 不生成業務需求文件(那是 PM 職責)
+- 不管 release scheduling / branching strategy(那是 DevOps)
+
+## Common failure modes
+
+- **Audience 不清**: user 說「要 handoff」但沒說給誰 → Phase 0 必 clarify,否則 format 錯
+- **UI flow 過度簡化**: flow 圖少 error path / loading / edge case → 讓 handoff 失真
+- **Component inventory 漏掉 hidden consumption**:e.g., 內部某 function 呼叫 Toast → 需 grep 所有 imports
+- **A11y checklist 自動判 pass**:checklist 只能「visible hits」,color contrast / keyboard 實測需人工
+- **Spec sheet 寫成 code comment 複製**:spec 應該是 design 語言而非 code 描述,翻譯為 UX 詞彙
+
+## References
+
+- [references/handoff-template.md](references/handoff-template.md) — Storybook Handoff page 結構 + Markdown spec 範本
+- [references/flow-diagram.md](references/flow-diagram.md) — Mermaid UI flow 指引 + 世界級 reference
+- [references/inventory-checklist.md](references/inventory-checklist.md) — 元件 / token / a11y 清單 + grep pattern