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

package/ds-canonical/fork/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/fork/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 | node_modules/@qijenchen/design-system/src/components/Coachmark/ | onboarding tour 需求 |
+| --chart-accent | node_modules/@qijenchen/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 全景。

package/ds-canonical/fork/skills/performance-audit/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: performance-audit
+description: Performance audit for design-system components and product UI. Checks render count, unnecessary re-renders, memoization gaps, bundle size impact, useEffect chains, context thrashing. Invoke when user says「這元件效能如何」「為什麼很卡」「bundle 變大」「re-render 太多」, auto-invoked by `/component-quality-gate` Phase 4.5 (advanced mode) and `/design-system-audit` Dimension D3.
+---
+
+# Performance Audit — 元件效能稽核
+
+## 存在意義
+
+現有 `/design-system-audit`(全 dim per design-system-audit SSOT,code/spec 層)+ `/visual-audit`(pixel 層)**都不看效能**。render 次數過多、context 亂鋪、useEffect 鏈條過長這類 bug:
+- tsc 過、eslint 過、視覺正常
+- production 卡
+- 日常 dev 看不出來,到 stakeholder demo 才爆
+
+本 skill 作為稽核 6 維度的 **D3 元件效能** canonical home。
+
+## 觸發時機(對齊 CLAUDE.md 稽核 canonical)
+
+| 情境 | 模式 | 本 skill 跑什麼 |
+|------|------|----------------|
+| 新元件 merge 前 | 進階強制 | 全面(render count / memo / bundle) |
+| 元件新功能 | 進階強制 | 全面 scoped to 新 prop / variant |
+| 產品 demo 前 | 進階強制 | scoped to URL(常用頁 route) |
+| 日常 dev | 高效 | tsc pass + bundle diff 門檻即可 |
+| Release cut | 進階 + 全 DS scope | 全 DS render / memo / bundle 全跑 |
+
+## Preconditions
+
+- 元件 folder 存在於 `node_modules/@qijenchen/design-system/src/components/{Name}/`
+- `node_modules` 已安裝
+- Storybook 可啟動(用於 render-count 測量)
+
+## Workflow
+
+### Phase 0 — Scope 判定(一致性類必先全掃)
+
+- 若 scope = 單元件 → 走 Phase 1-3 對該元件
+- 若 scope = 全 DS / URL → **先全掃列出所有 hot path**(render 過多元件 / bundle 大元件 / context 亂鋪元件),Phase 1-3 按 impact 排序逐一 audit
+
+### Phase 1 — Render & re-render
+
+查 4 項:
+1. **Unnecessary re-render**:consumer 改 prop / state 時,本元件是否 re-render?`React.memo` 是否需要?
+2. **Inline 物件 / 函式 prop**:`style={{ ... }}` / `onClick={() => ...}` 每 render 造新 ref → child memo 失效
+3. **Context 粒度**:`<ThemeProvider value={theme}>` 若含頻繁變動 field(e.g. `openMenuId`)→ 整個 subtree 重渲。Context 必切分粒度或用 selector
+4. **Key 穩定性**:list items 用 `key={index}` 導致無意義 remount
+
+**工具**:
+- React DevTools Profiler record → 看 flame graph
+- `why-did-you-render` dev dep 觸發警告(未來可加)
+- 直接 grep pattern(inline style / arrow onClick)
+
+### Phase 2 — Memoization / dependency
+
+查 3 項:
+1. **useMemo / useCallback dep array**:遺漏 dep(stale closure)/ 多 dep(無效 memo)
+2. **useEffect dep array**:同上;特別注意 object / array dep(每 render 新 ref → 無限迴圈或無效 cleanup)
+3. **Computed value in render**:重計算 heavy op(sort / filter / 轉換) → 必 `useMemo`
+
+### Phase 3 — Bundle size
+
+查 3 項:
+1. **Direct heavy import**:`import * as Icons from 'lucide-react'`(全庫入 bundle) vs `import { Check } from 'lucide-react'`
+2. **Lazy-loadable portion**:Dialog / Sheet / Coachmark 等 rare-use overlay,可 `React.lazy` 減首屏
+3. **Duplicate dep**:`framer-motion` vs `motion/react` / 不同版本 react-day-picker 等
+
+**工具**:
+- `npx vite build --report`(vite bundle visualizer)
+- bundle-size CI check(未來可加)
+
+### Phase F — Report(必 STOP,對齊分權 canonical)
+
+產出:
+
+```markdown
+# Performance Audit — {Scope} — {YYYY-MM-DD}
+
+## Summary
+- Render issues: N
+- Memoization gaps: M
+- Bundle impact: K KB
+
+## Findings(按 impact 排序)
+### P0: {title}
+- 位置: {file:line}
+- 現況: {render count / bundle contribution}
+- 建議: {具體修法}
+- 是 canonical 修實作(auto),還是原則待討論(STOP)?
+
+## 提議討論(待 user sign-off)
+- {若發現 canonical 本身有問題,列於此,不自改}
+```
+
+**STOP 點**:report 寫完**不自動修**。分權對齊 CLAUDE.md `# 稽核 canonical`(內含「Audit-vs-execute 分權」inline rule)。
+
+## Non-goals
+
+- 不改 code / spec(純 read-only report)
+- 不做 micro-benchmark(10ms 以下差異不 report,噪音太多)
+- 不處理 network / backend(純前端 render / bundle)
+
+## 相關
+
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/design-system-audit/SKILL.md` — 全 dim 統籌(per design-system-audit SSOT);本 skill 是 D3 補位
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/visual-audit/SKILL.md` — pixel 層(D5)
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/ux-audit/SKILL.md` — UX 行為層(D4)
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/component-quality-gate/SKILL.md` — Phase 4.5 進階模式 chain 本 skill