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

package/ds-canonical/fork/skills/bug-fix-rhythm/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: bug-fix-rhythm
+description: Batch-end-verify rhythm + parallel tool batch + user-listed N-rule MUST-ALL + claim runtime verify. Invoke when entering multi-fix session 或 user 列 numbered rules. Replaces M32(c)(d)(h1)(h2) sub-invariants(2026-05-12 split per Knowledge-Prune Checkpoint 2)。
+---
+
+> **⚠️ Fork 工具註記(build 自動加)**:本 skill 提到的 `scripts/*.mjs` 或非標準 `npm run <audit>` 是 **DS-author repo 的機械工具,未隨 fork 套件附帶**(Claude Code 不掃 node_modules,fork 也無這些 executor + dep)。你的 product fork 用本 skill 的**方法論**(human / AI judgment)+ 既有 committed governance hook 的機械強制即可;要 mechanical 腳本層(截圖 / CI gate)請自行設置對應工具,或把該檢查 PR 回 DS repo 跑。
+
+# /bug-fix-rhythm — 多 fix session 的 rhythm canonical
+
+**目的**:當 session 有 ≥ 2 fixes(常見 visual bug session / user 列 N 條 numbered 規則),走 batch-end-verify rhythm,而非 per-fix verify cycle waste。**M32 split 後 (c)(d)(h1)(h2) 的 home**。
+
+**對齊**:
+- CLAUDE.md mindset #6「大原則吸收瑣碎」+ M14「對話結論 AUTO integrate」
+- Bazel incremental-build / GitHub Actions matrix-batch idiom(per-step incremental = waste,batch-end = canonical)
+- Anthropic Claude Code prompt engineering「single-message multi-tool-call」canonical
+- Toyota TPS jidoka(per-station per-item verify,不可 skip 任何 item)
+
+## When to invoke
+
+**強制 auto-chain**:
+- multi-issue session 內 ≥ 2 fix 待處理(visual / behavior / code 任 mix)
+- user 列 numbered N 條規則(「規則 1...規則 N」/「Q1...QN」/ image 標 1234)→ 視作 **MUST-ALL checklist**
+
+**手動 invoke**:user 明言「批 fix」「一次做完」「跑完再驗」「列規則」
+
+**不 invoke**(對齊 Anthropic Best Practice 小修 skip):
+- 單一 surgical fix(無 numbered rule + 無 cross-component)— per-fix verify 即可
+- pure refactor / typo / import cleanup
+- spec.md docs only
+
+## Non-goals
+
+- 不擴展到「audit full-dim」(那是 `/design-system-audit`)
+- 不取代 `/scan-similar-bugs`(那是 fix 後 root-pattern scan;本 skill 是 fix-過程 rhythm)
+- 不動 canonical 語意(走 audit-vs-execute STOP 提議)
+
+---
+
+## Workflow(4 phases)
+
+### Phase 0 — Intake & MUST-ALL checklist 化(原 M32(h1))
+
+讀 user message:
+
+**If user 列 numbered rules**(「規則 1: X / 規則 2: Y / ...」/「Q1 / Q2 / ...」/ image 標號 / bulleted list)→ 抽出 **MUST-ALL checklist**:
+
+```markdown
+## MUST-ALL checklist(per-rule 不可下放)
+- [ ] 規則 1: <verbatim user wording> — 對應 fix: <target>
+- [ ] 規則 2: <verbatim user wording> — 對應 fix: <target>
+- ...
+- [ ] 規則 N: <verbatim user wording> — 對應 fix: <target>
+```
+
+**禁止**:
+- 把 N 條視作 ranked-priority(「先修 1-3,4 之後再說」)
+- 漏 N 條中第 K 條當「做完」report
+- 改寫 user wording 為自己 paraphrase(verbatim 保留)
+
+### Phase 1 — Parallel tool batch(原 M32(d))
+
+Read / Grep / Glob 多檔需求 → **single message multi-tool-call**:
+
+```
+✓ Good: 1 message with [Read A, Read B, Read C, Grep D, Grep E]  (~2s)
+✗ Bad : 5 messages sequential                                       (~10s)
+```
+
+**Heuristic**:任何 tool call 之間**無 dependency**(後一個不需前一個結果) → 必 parallel。
+
+對齊 Anthropic Claude Code best practice:「Maximize use of parallel tool calls where possible」。
+
+### Phase 2 — Batch fix(原 M32(c))
+
+每 fix 用 Edit(不 Write,降風險)。**禁止 per-fix tsc / audit cycle**:
+
+```
+✓ Good: [Edit A] [Edit B] [Edit C] [Edit D] → final tsc + audit + visual (once)
+✗ Bad : [Edit A → tsc → audit → visual] [Edit B → tsc → audit → visual] ...  (5× waste)
+```
+
+例外:某 fix 確實依賴前一 fix 的 type 結果 → sequential 必要時可,但 verify cycle 仍 batch-end-only。
+
+### ⚠️ Checkpoint 1 — Substantive vs surgical 分流
+
+每 fix 落地前 inline 判斷:
+
+- **Surgical**(CLAUDE.md「Scope classifier — Surgical visual bug」):pixel / token / class adjustment, no new SSOT / API / cross-component → AUTO ship 此 fix
+- **Substantive**(audit-vs-execute 分權):新 SSOT / 新 prop / 新 canonical meaning / cross-component semantic → **STOP propose**,等 user verbatim 拍板才 ship
+
+混合 batch:surgical 部分 ship,substantive 部分 propose。**禁止**:substantive 偷渡進 surgical batch。
+
+### Phase 3 — Final batch-end verify(原 M32(c)(h2))
+
+全 fix 完成後**一次性**驗證:
+
+```bash
+npx tsc -b                                    # type
+npm run hooks:test                            # invariant
+node scripts/visual-audit-<target>.mjs        # pixel-quantified per M32(a)
+```
+
+**MUST-ALL re-check**(per Phase 0 checklist):
+
+```markdown
+## MUST-ALL verify report
+- [x] 規則 1: ✓ verified via <tsc | audit script | pixel measurement | playwright>
+- [x] 規則 2: ✓ verified via ...
+- ...
+- [x] 規則 N: ✓ verified via ...
+```
+
+**禁止**(原 M32(h2) claim runtime verify):
+- 寫「不會有問題」「無 side-effect」「verified」「都實作完了」**沒**對應 verify trace
+- code-reading 推論當「verified」
+- ranked-priority 漏 N 條中第 K 條當「做完」
+
+若某條無法 runtime verify → 明撤回 **「規則 K:未驗證,推論而已,user 真機 verify needed」**,不可假宣告。
+
+對齊 M20 claim-verify gap(M20 是 stop-hook 機制;本 skill Phase 3 是 active workflow side)。
+
+---
+
+## ⚠️ Checkpoints(禁止跳)
+
+### Checkpoint 1 — Phase 2 surgical vs substantive(見上)
+
+### Checkpoint 2 — Phase 3 verify trace 缺漏
+若 MUST-ALL N 條有 K 條無 verify trace → STOP report,先補 verify 再報 user。
+
+### Checkpoint 3 — User-listed rule wording 改寫
+若 Phase 0 抽 checklist 時改了 user wording → STOP,重抓 verbatim。
+
+---
+
+## 與其他 skill / hook 的關係
+
+| Tool | Scope | 跟本 skill 關係 |
+|---|---|---|
+| `/scan-similar-bugs` | fix 後 DS-wide root-pattern scan | 本 skill batch-end-verify 後**才** chain `/scan-similar-bugs` |
+| `/visual-audit` | 單次視覺對齊 | Phase 3 sub-step,本 skill 包它 |
+| `/component-quality-gate` | stakeholder gate | 不重疊(stakeholder vs daily bug fix) |
+| `stop_self_audit.sh`(hook) | claim-verify gap 攔 | 本 skill Phase 3 是 active side;hook 是 passive trip-wire |
+| `check_pixel_quantified_audit.sh`(hook) | M32(a) audit script 必 pixel | 本 skill Phase 3 跑該 audit |
+
+**3 層 防線**:
+- **本 skill**(active workflow):MUST-ALL checklist + batch-end-verify rhythm
+- **stop_self_audit.sh / check_codex_collab_5step.sh**(passive hook):claim-verify gap 攔
+- **M20 / M32(a)**(meta-rule):上游 invariant
+
+---
+
+## 世界級對照
+
+- **Bazel `bazel test //...`**:全 target 並行 + final report,而非 per-target sequential
+- **GitHub Actions matrix**:N 個 job 並行,final aggregate verdict
+- **Toyota TPS jidoka**:每 station per-item verify,**但** verify 是 station-end 而非 in-progress checkpoint
+- **Anthropic Claude Code prompt eng**:「Maximize use of parallel tool calls」
+- **Stripe / Linear engineering blog**:「batch deploy + single canary verify」over「per-PR canary」
+
+---
+
+## Self-improvement capture
+
+每次 invoke 完寫:
+- (a) Phase 0 抽 MUST-ALL 時 user wording 是否變形?
+- (b) Phase 2 surgical/substantive 分流是否準確?(false-positive 偷渡記錄)
+- (c) Phase 3 verify trace 有沒有「runtime verify needed」的條目漏標?
+- (d) 新發現 numbered-rule pattern → 加進 Phase 0 抽取 heuristic
+
+回填本 SKILL.md 或 references/。
+
+---
+
+## 歷史 absorbed failures(M32 split 來源)
+
+2026-05-12 4 prior failures absorbed by M32 → split 後本 skill 承接 (c)(d)(h1)(h2):
+1. cell-align audit「Δ=0 ALL PASS」但 user 抓 SKU/Qty 視覺垂直置中於 88px 高 row(audit 沒驗 Field collapse)
+2. divider 2px audit「ALL PASS」但 pinned panel 邊仍 2px(audit 沒驗 pixel overlap)
+3. breadcrumb tooltip audit「ALL PASS」但 user 連抓 hover 不 fire(audit 沒驗 Portal DOM bounding rect)
+4. row-alignment audit「Δ=0 ALL PASS」(attr 對齊,Field collapse 沒抓)
+
+具體 M32(a) pixel-quantified rule 仍在 meta-patterns.md,本 skill 是其 workflow side。

package/ds-canonical/fork/skills/code-quality-audit/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: code-quality-audit
+description: Clean code 量化稽核 — `any` 使用 / dead export / file size / long function / circular dep / magic number。補 `/design-system-audit` 只管「design canonical」的缺口。Invoke via /code-quality-audit scope=all(release / 季度)OR scope=changed(daily)OR scope=component:X(focused)。Auto-chain by `/design-system-audit --deep` Dim 27 + `/component-quality-gate` Ship phase + `/new-component` Phase 4.5。
+---
+
+> **⚠️ Fork 工具註記(build 自動加)**:本 skill 提到的 `scripts/*.mjs` 或非標準 `npm run <audit>` 是 **DS-author repo 的機械工具,未隨 fork 套件附帶**(Claude Code 不掃 node_modules,fork 也無這些 executor + dep)。你的 product fork 用本 skill 的**方法論**(human / AI judgment)+ 既有 committed governance hook 的機械強制即可;要 mechanical 腳本層(截圖 / CI gate)請自行設置對應工具,或把該檢查 PR 回 DS repo 跑。
+
+# Code Quality Audit — Clean Code 量化稽核
+
+Scope:**tsx / ts code hygiene**,跟 design canonical 正交。
+
+## 為什麼要這 skill
+
+`/design-system-audit`(全 dim per design-system-audit SSOT)管 design / spec / canonical correctness。但 **clean code 面向**(`any` 濫用 / dead export / 函式爆長 / circular dep / 檔案超標)**無任何 dim 覆蓋**。每次建元件 / audit / ship 都該跑這層。
+
+## 6 個 check
+
+| # | Check | Severity | 如何判定 |
+|---|-------|---------|---------|
+| 1 | `any` 使用 | P0 | grep `: any` / `as any` / `<any>` / `any[]` / `Record<X, any>`;支援 `// any-allow: {rationale}` 逃生口(同行或上一行) |
+| 2 | File size(.tsx)| P0 > 800 / P1 > 500 | `wc -l`;budget 500 / transition cap 800;spec 同 `check_file_size_budget.sh` policy |
+| 3 | Long function | P1 > 80 行 | naive:`function`/`const` 宣告到 matching `}` indent 行距 |
+| 4 | Dead export | P1 | `export` 名稱在其他 src/ 檔無出現;exempt `*Props/Options/Config/Args/Context/Variants/Value` 型別 API 慣例 |
+| 5 | Circular dep | P0 | DFS import graph,找 cycle |
+| 6 | Magic number | P1 | 覆蓋不完整 → 由 token 防線(`lib/_token_hygiene.sh` + `check_opacity_token_usage.sh`)層負責(primitive color / shadow / Tailwind v4 `[--foo]`);本 skill 不重複 |
+
+## When to run
+
+- **Daily**:`/code-quality-audit --scope=changed`(git diff)
+- **Component ship**:`/component-quality-gate` Ship phase auto-chain
+- **New component**:`/new-component` Phase 4.5 auto-chain
+- **Release / 季度**:`/code-quality-audit --scope=all`
+- **Focus one component**:`/code-quality-audit --scope=component:<Name>`
+- **CI gate**:`node scripts/code-quality-audit.mjs --check`(P0 violation → exit 1)
+
+## Workflow
+
+1. Run `node scripts/code-quality-audit.mjs [--scope=<scope>]`
+2. Triage findings into P0 / P1 / P2
+3. Auto-fix trivial(unused imports,trivial `any` casts with obvious type)
+4. STOP for user decision on:
+   - File-size P0(大 component architectural split)
+   - Circular dep(需設計層面重組)
+   - 無法 auto-type 的 `any`(需 design judgment 訂 proper type)
+
+## 禁止
+
+- 禁 silent 吞 `any`(必加 `// any-allow: {rationale}`)
+- 禁把 dead export 直接刪(可能是 planned API surface);flag → user 決策
+- 禁把 long function 硬拆(拆錯比爆長還糟);只提議,user sign-off
+
+## Integration points
+
+| Skill / Hook | How |
+|---|---|
+| `/design-system-audit` Dim 27 | `--deep` 必 chain 本 skill scope=all |
+| `/component-quality-gate` Ship | chain 本 skill scope=component:{Name} |
+| `/new-component` Phase 4.5 | 元件建完必跑 scope=component:{Name} |
+| Hook `check_code_quality.sh` | PostToolUse Edit/Write on src/ — 只跑 any + file-size(quick) |
+
+## References
+
+- `scripts/code-quality-audit.mjs` — 實作
+- `.claude/hooks/check_code_quality.sh` — per-edit lite check
+- 相關:token 防線 `lib/_token_hygiene.sh` + `check_opacity_token_usage.sh`(正交 — token 紀律 vs code 紀律)

package/ds-canonical/fork/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/fork/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 原生支援。