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

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 會踩坑

package/ds-canonical/skills/delivery-handoff/references/inventory-checklist.md

@@ -0,0 +1,196 @@
+# Inventory Checklist — 元件 / token / a11y grep pattern
+
+Phase 1 inventory 生成的具體 grep + 統計方法。
+
+---
+
+## Component Inventory
+
+### 步驟 1: grep 所有 import
+
+```bash
+grep -rhnE "^import.*@/design-system/components/" {target} | \
+  sed -E 's/.*components\/([A-Z][a-zA-Z]+)\/.*/\1/' | \
+  sort | uniq -c | sort -rn
+```
+
+輸出:每個 DS 元件被 import 幾次。
+
+### 步驟 2: count JSX usage
+
+每個 component 精確使用次數(非 import):
+
+```bash
+for comp in Button Input Dialog Empty ScrollArea ...; do
+  count=$(grep -rhnE "<$comp\b" {target} | wc -l)
+  echo "$comp: $count"
+done
+```
+
+### 步驟 3: 輸出 table
+
+```markdown
+## Components Used (12)
+
+| Component | Count | Files |
+|-----------|-------|-------|
+| Button    | 12    | Checkout.tsx, Summary.tsx, ... |
+| Input     | 3     | PaymentForm.tsx |
+| Dialog    | 2     | ConfirmDialog.tsx, EditDialog.tsx |
+| Empty     | 1     | EmptyCart.tsx |
+| ProgressBar | 1   | UploadingBanner.tsx |
+| ScrollArea | 1    | ItemList.tsx |
+| ...       |       |       |
+```
+
+---
+
+## Token Inventory
+
+### CSS variable usage
+
+```bash
+grep -rohnE 'var\(--[a-z-]+\)' {target} | \
+  sort | uniq -c | sort -rn
+```
+
+### Semantic token utility class
+
+```bash
+grep -rohnE '\b(bg|text|border|fill|stroke|ring)-(primary|primary-hover|primary-subtle|primary-text|info|info-hover|info-subtle|info-text|error|error-hover|error-subtle|error-text|success|success-hover|success-subtle|success-text|warning|warning-hover|warning-subtle|warning-text|foreground|fg-secondary|fg-muted|fg-disabled|neutral-hover|neutral-active|neutral-selected|surface|surface-raised|canvas|muted|secondary|border|border-hover|divider|overlay|tooltip|notification|chart-[1-5])\b' {target} | \
+  awk -F: '{print $NF}' | sort | uniq -c | sort -rn
+```
+
+### 輸出 table
+
+```markdown
+## Tokens Used (24)
+
+| Token | Usage | Primary consumer |
+|-------|-------|------------------|
+| --primary | 8 | 主 CTA |
+| --fg-secondary | 14 | 次要文字 |
+| --error | 3 | 錯誤狀態 |
+| --surface-raised | 5 | Dialog / Popover bg |
+| ... | | |
+```
+
+---
+
+## Layout primitives 消費報告
+
+每類 primitive 用了幾次 + 哪些地方:
+
+```bash
+# Empty
+grep -rhnE '<Empty\b' {target} | wc -l
+
+# ScrollArea
+grep -rhnE '<ScrollArea\b' {target} | wc -l
+
+# AspectRatio
+grep -rhnE '<AspectRatio\b' {target} | wc -l
+
+# item-layout (MenuItem etc.)
+grep -rhnE '<(MenuItem|TreeItem|SidebarMenuButton|ItemIcon|ItemAvatar|ItemLabel|ItemSuffix)\b' {target} | wc -l
+
+# overlay-surface (Dialog/Popover auto consume)
+grep -rhnE '<(DialogHeader|DialogBody|DialogFooter|PopoverHeader|PopoverBody|PopoverFooter)\b' {target} | wc -l
+```
+
+輸出:
+
+```markdown
+## Layout primitives used
+
+| Primitive | Count | Note |
+|-----------|-------|------|
+| Empty     | 1     | EmptyCart.tsx |
+| item-layout | 5   | via MenuItem(3) / TreeItem(2) |
+| overlay-surface | 4 | via Dialog sub-components |
+| ScrollArea | 1    | ItemList.tsx |
+| AspectRatio | 0   | 本 feature 無 media container |
+| Horizontal-overflow | 0 | 本 feature 無水平溢出 |
+| Field-wrapper | 3  | via Input(3) |
+```
+
+---
+
+## A11y Checklist
+
+### 自動掃描(visible)
+
+```bash
+# icon-only 無 aria-label
+grep -rnE '(iconOnly|startIcon=\{)' {target} | \
+  xargs -I {} sh -c 'echo {} | grep -v "aria-label"'
+
+# 非 button 綁 onClick
+grep -rnE '<(div|span)[^>]*onClick=' {target}
+
+# Dialog 是否有 DialogTitle
+grep -rlE '<DialogContent>' {target} | \
+  xargs -I {} grep -L 'DialogTitle' {}
+```
+
+### 人工 review(本 skill AI 無法判)
+
+| Check | Status | Note |
+|-------|--------|------|
+| Color contrast WCAG AA | ? | 需 Storybook 視覺 + axe plugin |
+| Keyboard navigation tab order | ? | 需實際操作 |
+| Screen reader announce 正確 | ? | 需 VoiceOver / NVDA 測試 |
+| Focus trap 在 Modal 內 | ✓ | Radix 自動處理 |
+| Esc 關閉 Modal | ✓ | Radix 自動處理 |
+
+輸出:
+
+```markdown
+## A11y Status
+
+### Auto-scanned (visible issues)
+
+| Check | Status |
+|-------|--------|
+| icon-only 有 aria-label | ✓ 全過(12/12) |
+| 非 button 綁 onClick | ✓ 無 |
+| Dialog 有 Title | ✓ 2/2 |
+
+### Manual review needed
+
+- [ ] Color contrast(run axe in Storybook)
+- [ ] Keyboard navigation test
+- [ ] Screen reader test
+```
+
+---
+
+## 新增的元件 / token
+
+若 feature 過程中**新增**到 design-system/,在 inventory 特別標示:
+
+```markdown
+## New additions to DS (本 feature 過程新增)
+
+| Added | File | Motivation |
+|-------|------|-----------|
+| Coachmark | packages/design-system/src/components/Coachmark/ | onboarding tour 需求 |
+| --chart-accent | packages/design-system/src/tokens/color/semantic.css | data viz 擴充 |
+```
+
+讓 stakeholder 看得出「這 feature 帶動了 DS 擴充」的成本。
+
+---
+
+## 範本輸出順序
+
+inventory 結果編排:
+
+1. **Overview**(feature 規模:X screens / Y modals)
+2. **Components Used**(按 count 由高至低)
+3. **Tokens Used**(按 count 由高至低,分色 / 字 / 間距 / shadow 四類)
+4. **Layout primitives**(全表)
+5. **A11y**(auto + manual two tables)
+6. **New additions**(若有)
+
+如此 stakeholder 一分鐘可掃完,三分鐘可讀懂 feature 全景。