@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

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

@@ -0,0 +1,69 @@
+# 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 邏輯改)
+
+## 提案紀律(format / gate / 7 軸)→ 全走主檔,不在此重述
+
+本檔曾把這幾項抄成舊的 4-Q(漏最關鍵的 Q0)+ 指向已刪檔 = 漂移實證;一律以主檔為準,改一處不會漏改別處:
+
+- **中文人話 propose format + 禁用 jargon 對照表** → SSOT `.claude/memory/feedback_propose_discipline.md`(hook `check_propose_discipline.sh(r1,2026-06-11 merge)` 機械強制)
+- **Propose 前必過 7-Q gate**(Q0 先驗「問題是否真存在」/ Q1 cite / Q1' DS canonical 優先 / Q2 SSOT consume / Q3 Rule-of-3 / Q4 下游吸收 / Q5 issue 100% mapped)→ SSOT `.claude/skills/propose-options/SKILL.md`(hook `check_propose_pre_grep_verify.sh` 機械強制 Q0);M18 為 meta anchor
+- **Non-SSOT autonomous 7 軸 optimize 操作清單** → `phase-a-workflow.md` A.3;SSOT `CLAUDE.md` `# 自主執行 canonical`(檔案大小上限以該主檔為準,本檔不重述數字)
+
+## 收斂判準 — 何時停止 rerun(Phase C.0,2026-06-01 codify)
+
+**Why**:deep-audit 是 LLM 對抗式稽核 = **non-deterministic + 生成式永遠找得到東西 + 高假陽性**。同一份沒改的 code,每次 rerun 都會吐「新問題」——多數是措辭 nit 或誤判。盲目 **auto-rerun-to-zero = 追不到的跑步機**,且假陽性會誘發你「修」出 regression。但**過早宣稱遞減**也錯(漏掉真 material)。
+
+**停止判準**(每跑完一輪 audit,先過此 gate 再決定要不要再跑):
+
+> 迭代到某輪「**adversarial 二次驗證後,真 material 或 regression = 0**」(只剩 marginal nit + false-positive)→ **STOP**。既不追零、也不過早收手。
+
+**每 finding 必三分類 + adversarial 二次驗證**(filter audit 高估):
+
+| 類別 | 定義 | 處置 |
+|---|---|---|
+| **material** | 影響使用者 / contract / a11y / 真 regression(spec 改了但 tsx meta / story 漏跟)| 修(non-SSOT → autonomous;SSOT-UI/UX → propose)|
+| **marginal** | 措辭 nit / 缺一欄非必要 doc / 風格偏好 | 記錄,**不修**(低於 materiality threshold)|
+| **false-positive** | 讀 .tsx + wrap lib source 後證實宣稱錯(audit 誤判)| 駁回 + 標 evidence |
+
+每個 raw finding 跑 **adversarial 二次驗證**(讀 source 逐句比對,不信第一輪結論)再歸類——audit 第一輪系統性高估(本 session Avatar 硬互斥 / FileViewer listbox / DropdownMenu child-only / Input naked 全 over-flag,二驗後降級)。
+
+**「改一處看 N 處」doc-alignment 紀律**:一個 component 有多面向（spec frontmatter / tsx meta / props 表 / Inspector argTypes / ColorMatrix / ModeMatrix / Accessibility prose / principles / showcase / jsDoc）——改一處要**全掃同步**,否則 reruns 一直抓這缺口(本 session 2-4 輪全在清這個）。
+
+**實證**(本 session,沒改 code 反覆 rerun):material **7→3→2→2→0**(5 輪)—— 第 1 輪抓我引入的 regression、2-4 輪清 doc 傳播缺口、第 5 輪歸零 STOP。
+
+**收斂真正靠**:決定性 CI gate(`tsc` / invariant script / hook BLOCKER）+ **寫入時紀律**,**不是** audit loop。deep-audit 是**週期性工具**(release / SSOT 大改 / 季度),不該對「沒變的內容」反覆跑。對齊 Linux kernel `checkpatch.pl` deterministic pre-submit / Toyota TPS Jidoka(機器發現異常自停,非人工反覆巡）。
+
+## 共識決策(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/deep-audit-cross-codex/references/upstream-directives-r-mapping.md

@@ -0,0 +1,33 @@
+# Upstream context / framing + user-verbatim directives + R18-R26 mechanical-mapping(deep-audit-cross-codex SKILL.md 抽出)
+
+## SSOT integrity invariant + 生態位 + 上游 canonical 全繼承
+
+> **SSOT integrity invariant**(2026-05-18 user-mandated):本 skill 的 audit dim list **完全 chain `/design-system-audit --deep` SSOT**(`.claude/skills/design-system-audit/SKILL.md` `## The N audit dimensions` 段)。
+>
+> **禁** hardcode dim count(`46 dim` / `53 dim` 等具體數字)— 用「全 dim」/「Group A-P」/「per design-system-audit SSOT」表達。新增 / 刪除 / 修改稽核項目 → **只動 design-system-audit/SKILL.md**,本 skill 自動繼承。
+>
+> Mechanical 強制:hook `check_dim_count_drift.sh` 攔 Edit 寫死數字。
+
+**生態位**:`/design-system-audit --deep` 是 Claude solo 全 dim 稽核 SSOT;本 skill 是**雙 model 完整 sweep**(Claude solo → codex parallel → 比稿辯論共識 → 落地),chain 既有 audit dim 不 fork。
+
+**上游 canonical 全繼承**(per user「避免膨脹但別漏」):本 skill chain CLAUDE.md 全 mindset + meta-patterns 全 active M-rules + 治理 8-home / 自主執行 / 命名 SSOT canonical,**不重述、不 hardcode count(避 R19 膨脹),全靠 reference**。
+
+## 上游 user-verbatim directives + R18-R26 對齊
+
+對齊 mindset #1「不取巧省工」+ M31 dual-track + 用戶 2026-05-18 directive(verbatim):
+
+> 「完整深度進階稽核整個 design system」+「codex 跑相同的完整深度進階稽核」+「跟 codex 討論辯論出共識」+「SSOT-UI/UX 增刪改需要用中文具體人話言簡意賅地講給我聽讓我判斷決策,其他的決策基本上就是不以省工為前提...自主自動自發地做到完整、完美」
+
+**+ 用戶 2026-05-29 directive(verbatim,permanent codify)**:
+
+> 「你應該要確保任何 infra 包括各種 Claude.md, skills, hooks 等在 ds repo, template repo, fork template 的 repo, 都能正常順利如預期的運作達到預期的效果, 且流程都正確無誤,且該維持 SSOT 的部分又能完全維持」+「我們的工作流程就是用 claude code 直接連去 repo 進行各種增刪改, 然後要可以部署出來讓人驗證, 驗證完成之後再推去 main」+「確保環境建置是能夠全雲端的, 且該自動化的就自動化, 真的無法自動化的要有具體的言簡意賅的中文明確引導」+「確保所有原則都是足夠泛化可以用來舉一反三的原則, 避免原則無限膨脹, 沒有多餘重複的且是 SSOT, 並確保所有 infra 都是最佳有效率的 claude code 實務, 並確保 infra 能夠產出世界級的設計並符合我們一致的設計語言和確保 ssot, 然後所有程式碼都是乾淨簡潔易懂好維護好管理的, 且是會有大腦地自動優化不斷改善, 確保自己永遠符合上述原則」
+
+**機械強制 R18-R26 對齊**:
+- R18 泛化 / 舉一反三 → 上游 mindset #6 + meta-patterns velocity ≤ 3/quarter(`/knowledge-prune`)
+- R19 避免膨脹 → 上游治理 canonical 行數預算 + `/knowledge-prune` 季度
+- R20 無多餘重複 SSOT → 上游 Rule-of-3(`/knowledge-prune` D1 + ensure-canonical Phase 3)
+- R21 最佳 Claude Code 實務 → 上游「世界級對照」section
+- R22 世界級 + 一致設計 → 上游 mindset #1 + A.3 7 目標 simultaneous
+- R24 code clean → chain `/code-quality-audit`(Phase A.4 verify chain)
+- R25 大腦自動 self-improve → chain `/ensure-canonical` Phase F + M14
+- R26 永遠符合 → M19 trigger phrase auto-pipeline(`stop_self_audit.sh` 機械強制)

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

package/ds-canonical/skills/delivery-handoff/references/flow-diagram.md

@@ -0,0 +1,180 @@
+# Flow Diagram — Mermaid UI Flow 指引
+
+---
+
+## 為什麼用 Mermaid
+
+- **Text-based**:可 git diff / review / version control
+- **Storybook 支援**:`mdx` 可直接 render;純 `tsx` story 用 `<pre>` 包 mermaid source + 指引
+- **世界級工具支援**:GitHub / Notion / GitLab / Confluence 都 render
+- **Export**:可 export PNG / SVG / PDF 交付給不進 Storybook 的 stakeholder
+
+---
+
+## 基本語法
+
+### flowchart(最常用)
+
+```mermaid
+flowchart TD
+  Start([使用者進入 checkout]) --> Cart[Cart Review]
+  Cart -->|修改| Edit[Edit Item Dialog]
+  Edit --> Cart
+  Cart -->|確認| Pay[Payment Step]
+  Pay -->|信用卡| Card[Card Form]
+  Pay -->|轉帳| Bank[Bank Info]
+  Card --> Confirm[Confirm Dialog]
+  Bank --> Confirm
+  Confirm -->|下單| Success([訂單成立])
+  Confirm -->|取消| Cart
+```
+
+Nodes:
+- `[Text]` = rectangle(主 screen / modal)
+- `([Text])` = stadium(流程起點 / 終點)
+- `{Text}` = rhombus(決策點)
+- `((Text))` = circle(特殊節點,如 async operation)
+
+Edges:
+- `-->` arrow
+- `-->|label|` arrow with label(e.g., 條件)
+- `-.->` dashed(非主路徑 / optional)
+- `==>` thick(強調 / primary 路徑)
+
+### sequenceDiagram(互動時序)
+
+```mermaid
+sequenceDiagram
+  User->>UI: 點「套用」
+  UI->>API: POST /discount
+  API-->>UI: 200 + discount data
+  UI->>UI: 更新 state
+  UI-->>User: 顯示「已套用」
+```
+
+適合:非同步互動 / API 時序 / 多 actor 流程。
+
+### stateDiagram(狀態機)
+
+```mermaid
+stateDiagram-v2
+  [*] --> Idle
+  Idle --> Loading: click apply
+  Loading --> Applied: 200
+  Loading --> Error: 4xx/5xx
+  Applied --> Idle: click clear
+  Error --> Idle: dismiss
+```
+
+適合:元件 / feature 的狀態機(idle / loading / success / error)。
+
+---
+
+## 世界級 reference
+
+對標世界級設計 handoff 的 flow 品質:
+
+- **Shopify Polaris Pattern pages**: 每 pattern 有 `flow` section 用 SVG,我們用 Mermaid
+- **Material Design Guidelines**: 流程圖 + 截圖並列
+- **Stripe Documentation**: Payment Flow 用 Mermaid + inline code
+- **Figma Design Process blog posts**: Journey map + flow 混合
+
+---
+
+## 原則
+
+### 1. 一張圖涵蓋一個 feature,不超過 20 個 nodes
+
+> 20+ nodes → 拆成多個 sub-flow diagram。
+
+### 2. 標示 **error path**(非 happy path)
+
+> 只畫 happy path = handoff 失真。user 也要知道錯誤 / 邊界 case 流向何處。
+
+### 3. 決策點標清楚
+
+> 用 `-->|label|` 寫條件,避免邊無敘述。
+
+### 4. Start / End 用 stadium node
+
+> `([Start])` / `([End])` 讓讀者知道邊界。
+
+### 5. 搭配 spec sheet 引用
+
+> Node text 應對應 spec sheet 的 screen / modal 名稱,讀者一眼看出對應。
+
+---
+
+## 範本 — Checkout 完整 flow
+
+```mermaid
+flowchart TD
+  Start([進入 /checkout]) --> AuthCheck{已登入?}
+  AuthCheck -->|否| Login[Login Screen]
+  Login --> Start
+  AuthCheck -->|是| CartCheck{購物車有 item?}
+  CartCheck -->|否| Empty[Empty Cart Screen]
+  Empty -->|回去購物| End1([exit to /products])
+  CartCheck -->|是| Review[Cart Review Screen]
+
+  Review -->|點 item| Edit[Edit Item Dialog]
+  Edit -->|save| Review
+  Edit -->|cancel| Review
+
+  Review -->|輸入折扣| Discount{折扣有效?}
+  Discount -->|否| DiscountError[顯示 error]
+  DiscountError --> Review
+  Discount -->|是| Review
+
+  Review -->|下一步| Payment[Payment Selection]
+  Payment -->|信用卡| CardForm[Card Form]
+  Payment -->|轉帳| BankInfo[Bank Instructions]
+  Payment -->|超商| StoreInfo[Store Instructions]
+
+  CardForm --> Validate{valid?}
+  Validate -->|否| CardError[Inline errors]
+  CardError --> CardForm
+  Validate -->|是| Confirm[Confirm Dialog]
+
+  BankInfo --> Confirm
+  StoreInfo --> Confirm
+
+  Confirm -->|確認下單| Submit[POST /order]
+  Submit --> SubmitCheck{success?}
+  SubmitCheck -->|是| Success([訂單成立 / 跳 /orders/:id])
+  SubmitCheck -->|否| RetryToast[Toast: 請稍後再試]
+  RetryToast --> Confirm
+
+  Confirm -->|取消| Payment
+```
+
+---
+
+## Edge case 節點命名慣例
+
+- `XxxError` = 錯誤狀態(顯示 Alert / Notice)
+- `XxxEmpty` = 空狀態(顯示 Empty 元件)
+- `XxxLoading` = 載入中
+- `XxxRetry` = 可重試狀態
+- `XxxSkipped` = 跳過(optional flow)
+
+讓讀者一眼看出節點是 happy 還是 edge。
+
+---
+
+## 集成 Storybook
+
+Storybook 8+ 支援 MDX,可直接寫 mermaid code block:
+
+````mdx
+# Checkout Flow
+
+```mermaid
+flowchart TD
+  Start --> End
+```
+````
+
+純 tsx story 可用 `<pre>{mermaidSource}</pre>` + 外部 render tool,或用 `mermaid.js` npm lib runtime render。
+
+一般推薦 MDX 方式,Storybook 原生支援。

package/ds-canonical/skills/delivery-handoff/references/handoff-template.md

@@ -0,0 +1,177 @@
+# Handoff Template — Storybook page + Markdown spec
+
+---
+
+## Storybook Handoff Page 結構
+
+位置: `src/app/features/{feature-slug}/{feature-slug}.handoff.stories.tsx`
+
+Title: `Features/{Feature Name}/Handoff`
+
+每個 handoff page 5 個 story(5 tab):
+
+```tsx
+const meta: Meta = {
+  title: 'Features/Checkout/Handoff',
+  parameters: { layout: 'fullscreen' },
+}
+export default meta
+
+export const Overview: Story = {
+  name: '0. Overview',
+  render: () => <OverviewPage />,
+}
+
+export const UIFlow: Story = {
+  name: '1. UI Flow',
+  render: () => <FlowDiagram />,  // Mermaid render
+}
+
+export const Inventory: Story = {
+  name: '2. Inventory',
+  render: () => <InventoryTables />,  // Component / Token / a11y
+}
+
+export const Screens: Story = {
+  name: '3. Screens',
+  render: () => <ScreenGrid />,  // 每 screen 的 preview + link
+}
+
+export const SpecSheets: Story = {
+  name: '4. Spec Sheets',
+  render: () => <SpecTabs />,  // per-screen detail
+}
+```
+
+---
+
+## Per-screen Markdown Spec 範本
+
+每 screen 一份,組合為完整 feature 的 spec sheet:
+
+```markdown
+# Screen: {Name}
+
+**Storybook**: `Features/{Feature}/{Screen}`
+**Source**: `src/app/features/{slug}/{Screen}.tsx`
+**Route**: `/{path}`
+
+## 用途(Why)
+
+{1-2 sentence 敘述 user 會在此頁做什麼}
+
+## 進入條件(Entry conditions)
+
+- {e.g., 已登入 + 購物車有 ≥1 item}
+- {e.g., 付款方式已選擇}
+
+## 主要元件(Components used)
+
+| Component | Count | Purpose |
+|-----------|-------|---------|
+| Button | 3 | CTA + 次要 action |
+| Input | 1 | 折扣碼輸入 |
+| ... | | |
+
+## 狀態(States)
+
+### default
+{正常載入後的畫面描述 + 截圖}
+
+### empty
+{無資料時的 fallback}
+
+### error
+{錯誤情境處理}
+
+### loading
+{載入中 skeleton / spinner}
+
+## 互動(Interactions)
+
+| Action | Element | Result |
+|--------|---------|--------|
+| 點 Apply | Button | POST /discount |
+| 按 Esc | 任何 Dialog | 關閉 |
+| ... | | |
+
+## A11y
+
+- ✓ icon-only 元件均有 aria-label
+- ✓ Dialog 有 DialogTitle + DialogDescription
+- ✓ keyboard tab order 正確
+- ⚠ {如有未達標項,明列 + 說明}
+
+## 邊界(Edge cases)
+
+- {e.g., 折扣碼超過總額 → capped}
+- {e.g., 網路斷線 → toast + retry}
+- {e.g., 超過 N items → 分頁}
+
+## 業務規則(Business rules)
+
+- {e.g., VIP 折扣上限 30%}
+- {e.g., 免運門檻 NT$1000}
+
+## Related
+
+- Next step: [Screen Y]
+- Alternative: [Screen Z]
+- Design source: [Explorations/ folder](...)
+```
+
+---
+
+## Overview story render 範本
+
+```tsx
+function OverviewPage() {
+  return (
+    <div className="max-w-4xl mx-auto p-8 flex flex-col gap-6">
+      <h1 className="text-h1 font-medium">Checkout Feature Handoff</h1>
+      <p className="text-body-lg text-fg-secondary">
+        使用者從購物車到下單的完整結帳流程。包含 3 screens、4 modals、支援信用卡 / 銀行轉帳 /
+        超商付款 3 種付款方式。
+      </p>
+
+      <div className="border-t border-divider pt-6">
+        <h2 className="text-h2 font-medium mb-3">Audience</h2>
+        <ul className="list-disc pl-5 text-body">
+          <li>工程團隊:實作參考 + test case 來源</li>
+          <li>QA:邊界 case checklist</li>
+          <li>PM:業務規則確認</li>
+        </ul>
+      </div>
+
+      <div className="border-t border-divider pt-6">
+        <h2 className="text-h2 font-medium mb-3">Status</h2>
+        <div className="grid grid-cols-3 gap-3">
+          <StatCard label="元件消費" value="12" caption="既有 DS" />
+          <StatCard label="新元件" value="0" caption="零污染" />
+          <StatCard label="A11y" value="✓" caption="WCAG AA" />
+        </div>
+      </div>
+
+      <div className="border-t border-divider pt-6">
+        <h2 className="text-h2 font-medium mb-3">Navigation</h2>
+        <ul className="list-disc pl-5 text-body">
+          <li>Tab 1: UI Flow — Mermaid diagram</li>
+          <li>Tab 2: Inventory — 元件 / token / a11y 報告</li>
+          <li>Tab 3: Screens — 每 screen preview + link</li>
+          <li>Tab 4: Spec Sheets — per-screen detail</li>
+        </ul>
+      </div>
+    </div>
+  )
+}
+```
+
+---
+
+## 設計原則
+
+1. **target audience driven**: 語氣深度因 audience 調整。工程語氣精準 / PM 語氣情境 / 設計語氣對標
+2. **每段可獨立被引用**: per-screen spec 可單獨丟給 team member,不需看其他頁
+3. **不重複 DS spec**: 元件的行為 / variant 由 `components/*/spec.md` owning,handoff 只寫 **feature-level** 使用
+4. **截圖 / preview 是 Storybook render 即可**: 不要 mockup,直接看真實 code 的 output
+5. **Edge case 必寫**: handoff 不寫 edge case = 實作 + QA 會踩坑