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

package/ds-canonical/fork/codex/agents/skills/delivery-handoff/SKILL.md

@@ -0,0 +1,244 @@
+---
+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 階段。
+---
+
+<!-- _generated: canonical provider skill projection; source: skills/delivery-handoff/SKILL.md; provider: codex; do not edit this adapter view. -->
+
+> **Product-role projection(build 自動)**:本 skill 的執行步驟已只保留本 product repo 實際存在的指令。DS-author-only executor 會被改寫為 browser/manual/product-CI 等價驗證,不得在 product 中嘗試不存在的腳本。
+
+# 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 生成
+
+**Deterministic 源優先(2026-07-07 治理進化收尾:本 skill 原「幾乎零機械依賴」列冊補強)**:
+- Component / story 母集 = `inspect the installed package public exports and shipped stories` 產出的 manifest(禁憑記憶列)
+- Token 使用 = `rg -o -- '--[a-z][a-z0-9-]*' <feature files> | sort | uniq -c`(機械計數,非印象;字元類含 0-9 — DS token 名 46% 含數字如 `--chart-1`/`--black-a02`,缺數字會截斷合併成假 key)
+- 消費統計交叉驗 `search product token usage and compare it with the installed token documentation` 的消費通道邏輯(同一套 5 通道定義)
+
+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，並以 source/readback 驗證。
+若 flow 可由既有 requirement 與實作唯一重建，直接修正 evidence drift；只有仍存在會改變
+產品／UI／UX SSOT 的真實 flow 取捨才 P2H。
+
+### 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 — Handoff evidence/readback receipt
+
+Phase 4 產出後記錄並驗證:
+
+```
+📦 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}
+
+Readback:
+- requirement／source coverage: {complete / findings}
+- links／screens／states／a11y evidence: {verified / findings}
+- audience binding: {source / exact requirement}
+```
+
+可由 requirement、source、tests 與既有 audience 唯一判定的 finding 由 agent 自主修正並
+繼續。只有 handoff 揭露新的產品／UI／UX outcomes 取捨，或對外分享會構成無法從既有
+requirement 推導的 business commitment，才停在 shared governance 定義的 human-only
+boundary；handoff milestone 本身不是 user engineering-approval gate。
+
+---
+
+## 世界級 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/codex/agents/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/fork/codex/agents/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 會踩坑