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

package/ds-canonical/fork/codex/agents/skills/prototype/references/proposal-template.md

@@ -0,0 +1,230 @@
+> **Product-role projection(build 自動)**:本 skill 的執行步驟已只保留本 product repo 實際存在的指令。DS-author-only executor 會被改寫為 browser/manual/product-CI 等價驗證,不得在 product 中嘗試不存在的腳本。
+# Proposal Template — explorations/ 結構 + Storybook 編排
+
+Phase 3 每個 shortlisted candidate 建一個 story + 共用 notes.md。
+
+---
+
+## 目錄結構(對齊 shared governance「Exploration 規則」)
+
+```
+src/explorations/{topic-slug}/
+├── notes.md                              # 本 topic 的 source of truth
+├── {CandidateA-name}.stories.tsx         # 候選 A 原型(1 檔內 3+ stories 各場景)
+├── {CandidateB-name}.stories.tsx
+├── {CandidateC-name}.stories.tsx
+└── _shared/                              # 僅此 topic 內共用的 helper(可選)
+    └── mock-data.ts
+```
+
+### 檔名慣例
+
+- **Topic slug**:kebab-case,描述問題(`onboarding-tour` / `bulk-action-confirm` / `empty-state-first-visit`)
+- **Candidate stories filename**:kebab-case + 描述性名稱(`linear-quick-filter.stories.tsx`)—**不用 `CandidateA/B/C`**(違反 shared governance「範例必須真實」mindset)
+
+### Storybook title 慣例(不與 Components/ 衝突)
+
+```tsx
+title: 'Explorations/{Topic Title}/{Candidate Name}'
+```
+
+範例:
+- `Explorations/Bulk Filter/Linear Quick-Filter`
+- `Explorations/Bulk Filter/Notion Command Palette`
+- `Explorations/Bulk Filter/Stripe Step Wizard`
+
+---
+
+## notes.md 範本
+
+```markdown
+# {Topic Title}
+
+## 問題定義(Phase 0 framing)
+
+**誰**:{primary user persona,如「Sales Ops 主管」}
+**想**:{jobs-to-be-done,如「在 50+ 筆 leads 中快速 filter 這週要跟進」}
+**解決**:{解除的痛點,如「現在得滾一頁找 tags,誤點率高」}
+**Constraints**:{mobile?a11y?時程?}
+
+## Phase 2 評估摘要
+
+見 Phase 2 完整評分表(略)。Shortlist 3 個:
+
+| Candidate | 核心機制 | 評分 | Phase 3 檔案 |
+|-----------|---------|------|-------------|
+| Linear Quick-Filter | Popover + checkbox + saved | 14/15 | `linear-quick-filter.stories.tsx` |
+| Notion Command Palette | modal Cmd-K + query | 11/15 | `notion-command-palette.stories.tsx` |
+| Stripe Step Wizard | Dialog + 3 步 fine-grained | 12/15 | `stripe-step-wizard.stories.tsx` |
+
+## Phase 3.0 Object Map(全 candidate 共享)
+
+本 feature 的 canonical object model,由 Phase 1 benchmark 的 OOUX 分析收斂 + Phase 0 framing 收敛而成。**3 個 candidate 共享此 Object Map**,差異只在 UI shape + CTAs 順序。
+
+**Objects**(core nouns):
+- {Object A}(核心名詞 1)
+- {Object B}(核心名詞 2)
+- {Object C}(若有)
+
+**Attributes per object**:
+
+| Object | Core attributes | Metadata | Identifying |
+|--------|----------------|----------|-------------|
+| {A} | ... | ... | ... |
+| {B} | ... | ... | ... |
+
+**Relationships(NOM)**:
+
+| From → To | Relationship |
+|-----------|-------------|
+| {A} → {B} | belongs to / has many / ... |
+| ... | ... |
+
+**CTAs per role per object**:
+
+| Role | {A} CTAs | {B} CTAs |
+|------|----------|----------|
+| Admin | Create / Edit / Delete | ... |
+| Member | View / Comment | ... |
+
+**UI Shape → DS 元件映射**:
+
+| Object | List | Card | Detail | Inline |
+|--------|------|------|--------|--------|
+| {A} | MenuItem / DataTable row | Card / FileItem | Page + Tabs | Tag / Chip |
+| {B} | ... | ... | ... | ... |
+
+完整 ORCA 方法與範本見 [`ooux-template.md`](ooux-template.md)。
+
+## 候選獨立說明
+
+### Linear Quick-Filter
+
+- **positioning**:面向重度 power user,shortcut-first
+- **適合場景**:
+  - Sales Ops 每日追蹤 leads(frequency=high,repeat task)
+  - Project Manager bulk status update
+  - Support 團隊 ticket triage
+- **不適合**:
+  - 新手 user(沒 onboarding 不知道 shortcut)
+  - 行動裝置(shortcut 無對應)
+- **新元件需求**:無(既有 Popover + Checkbox + Button 就夠)
+
+### Notion Command Palette
+
+- **positioning**:開放式 query,unified search
+- **適合場景**:
+  - 多維 filter(人 + tag + date)同時作用
+  - 可 memory 用戶的自訂 query
+- **不適合**:
+  - 情境簡單(2-3 filter)會 overkill
+  - 首次 user onboarding 負擔重
+- **新元件需求**:**可能需 `CommandPalette` 新元件**(本 DS 目前有 `Command` 但無全站 palette 結構)。若採用此 candidate,Checkpoint 3 討論是否升級。
+
+### Stripe Step Wizard
+
+- **positioning**:流程化,降低誤操作
+- **適合場景**:
+  - 破壞性 bulk action(delete 多筆)
+  - 需 audit trail 的金流 / 合規 action
+- **不適合**:
+  - 高頻日常操作(步驟拖慢速度)
+- **新元件需求**:無(既有 Dialog + Steps + Checkbox)
+
+## 下一步
+
+Phase 4 summary 整理完畢後,stakeholder 決定採用,走 graduation 流程:
+- 採用者遷移到 `node_modules/@qijenchen/design-system/src/`(若有新元件)或直接 app-level UI
+- 未採用者:留 `explorations/{topic-slug}/` 或移 `_archive/`(保紀錄)
+
+## 參考
+
+- Phase 1 research 連結(略)
+- Phase 2 評估完整表(略)
+- Storybook 路徑:`Explorations/{Topic Title}/*`
+```
+
+---
+
+## Candidate story 範本
+
+每個 `{candidate-name}.stories.tsx` 建議結構:
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react'
+// 從 DS import 既有元件
+import { Popover, PopoverContent, PopoverTrigger } from '@/design-system/components/Popover/popover'
+import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
+// ...
+
+const meta: Meta = {
+  title: 'Explorations/Bulk Filter/Linear Quick-Filter',
+  parameters: { layout: 'padded' },
+}
+export default meta
+
+type Story = StoryObj
+
+// Story 1:positioning 說明(不可互動也 OK)
+export const Positioning: Story = {
+  name: '1. Positioning',
+  render: () => (
+    <div className="max-w-lg flex flex-col gap-3">
+      <h3 className="text-body-lg font-medium">Linear Quick-Filter</h3>
+      <p className="text-body text-fg-secondary">
+        shortcut `Cmd+Shift+F` 開 Popover,checkbox 多選,支援 saved filter 組合。
+        面向 sales ops 每日場景:速度 > 引導。
+      </p>
+      <div className="border-t border-divider pt-3">
+        <a href="..." className="text-info">Linear 原始參考 →</a>
+      </div>
+    </div>
+  ),
+}
+
+// Story 2-4:具體情境(3 個以上,對齊 Mindset #4)
+export const SalesOpsDaily: Story = {
+  name: '2. Sales Ops 每日追蹤 leads',
+  render: () => { /* 完整互動 prototype */ },
+}
+
+export const ProjectBulkStatus: Story = {
+  name: '3. PM bulk status update',
+  render: () => { /* */ },
+}
+
+export const SupportTriage: Story = {
+  name: '4. Support ticket triage',
+  render: () => { /* */ },
+}
+
+// Story 5(可選):edge case / failure mode(讓 stakeholder 看弱點也是成熟的設計溝通)
+export const NewbieOnboardingConcern: Story = {
+  name: '5. ⚠️ 新手首次遇到(知識死角)',
+  render: () => (
+    <div>
+      {/* 示範新手沒 shortcut 知識時看到什麼 */}
+    </div>
+  ),
+}
+```
+
+---
+
+## DS 使用鐵律(per shared governance)
+
+Phase 3 建 exploration 時:
+
+1. **優先用既有元件** `node_modules/@qijenchen/design-system/src/components/`,不自創
+2. **Layout primitives 消費**(per shared governance 清單):Empty / item-layout / overlay-surface / ScrollArea / AspectRatio
+3. **Token 紀律**:只用 semantic token,不硬寫 hex / rgb / shadow-sm
+4. **token 防線 the installed immutable governance checker 5-check**:shadcn alias / v4 shorthand / hardcoded shadow / primitive-color-as-utility / native overflow — 5 項全過
+5. **新元件需求**:**notes.md 明文標示**,不偷偷 add 到 Components/(Checkpoint 3 專屬)
+
+---
+
+## Non-goals
+
+- Pixel-perfect 不是目標(Phase 3 看 pattern 可行性)
+- 不做完整 test coverage(exploration 不上 prod)
+- 不覆寫 DS 元件 props(若需 override, 代表這個 candidate 不適合既有 DS)

package/ds-canonical/fork/codex/agents/skills/scan-similar-bugs/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: scan-similar-bugs
+description: Auto-invoke after fix commits — extracts root-cause anti-pattern, greps DS-wide for same pattern, runs visual verify, batches related fixes. Closes M10 mechanical gap. Invoke via /scan-similar-bugs.
+---
+
+<!-- _generated: canonical provider skill projection; source: skills/scan-similar-bugs/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 中嘗試不存在的腳本。
+
+# /scan-similar-bugs — Fix-time DS-wide Exhaustive Scan
+
+**目的**:任何 bug fix 提交後,**機械化掃 DS-wide 找同 pattern**,而非靠 model 記得 M10。
+
+**對齊**:
+- `node_modules/@qijenchen/design-system/ds-canonical/rules/meta-patterns.md` M10 「Proactive exhaustive scan」mechanical 落地
+- mindset #1「不取巧」+ #2「優先消費既有」+ #6「meta 抽象」
+- 對齊 IDE「find similar / find references」+ Chrome DevTools「find usages」+ GitHub Copilot「related code」3+ 家世界級 idiom
+
+**對位其他 skill**:
+- `/design-system-audit` 是**定期 batch** full-dim audit
+- `/visual-audit` 是**單次視覺對齊** check
+- 本 skill 是 **batch-end-only root-pattern scan**(2026-05-12 independent review 抓 infra conflict 重構:per-fix → batch-end,對齊 `/bug-fix-rhythm` Phase 2-3 batch fix + single end-verify canonical;M32 split 後 batch-end home 移至 bug-fix-rhythm skill)
+
+## When to invoke
+
+**強制(auto-chain)— batch-end only**(2026-05-12 重構,per independent review):
+- multi-issue session 結束後**一次**(不是每 fix 一次)
+- session 內 ≥ 2 fix commit 觸發批次 root-pattern scan
+- session_start_governance_check.sh Check 6 偵測 24h 內 ≥1 fix commit 且 skill-invokes log 24h 無 scan-similar-bugs invoke → soft 提醒
+
+**手動 invoke**:
+- user 明言「掃同類 bug / 看其他元件有沒有 / 全 DS scan」
+- multi-issue batch session 結束想驗 root-pattern DS-wide
+
+**不 invoke**(對齊 provider-neutral best practice 小修 skip plan):
+- **Surgical visual bug**(user 列 N 個 visual defects + 無 canonical / API / cross-component → 批 fix + final verify only,不必 scan-similar)
+- pure refactor(無 bug 修復語義)
+- spec.md / docs only commit
+- 純 typo / import cleanup
+
+## Non-goals
+
+- 不擴展 scope 到「audit full-dim品質」(那是 `/design-system-audit`)
+- 不做視覺 regression baseline diff(那是 `/visual-audit`)
+- 不在本 skill 擴張成 full canonical redesign；工程治理 canonical remediation 轉交 audit 自主處理，只有產品／UI／UX SSOT 真取捨才是 human boundary
+
+---
+
+## Workflow(5 phases)
+
+### Phase 0 — 抓 root-cause anti-pattern
+
+```bash
+# 讀 last fix commit message + diff
+git log -1 --format='%s%n%n%b'
+git show HEAD --stat
+```
+
+從 commit message + diff 抽出 grep-able pattern。常見類型:
+
+| Bug 類型 | Anti-pattern grep target |
+|---|---|
+| Padding / sizing 公式錯 | `calc((var(--field-height-X) - <num>px) / 2)` etc |
+| Token leak / shadcn alias | `bg-popover / text-muted-foreground / bg-accent` |
+| 硬寫 magic number | `text-[14px] / shadow-[0_2px_8px_...]` |
+| API mis-use(prop combo)| `iconOnly + endIcon` / `loading + disabled` |
+| a11y missing | `<button>` 無 `aria-label` 又無 children |
+| Symbol mis-import | `from 'shadcn/ui/X'` |
+| CSS w/h asymmetric | SVG 量測 width !== height |
+
+**Output**: `ANTI_PATTERN`(grep regex / Playwright assertion)。
+
+### Phase 1 — DS-wide grep / visual scan
+
+選最適合的 detection:
+
+**Static grep**(快,適合 token / class / API mis-use):
+```bash
+grep -rnE "$ANTI_PATTERN" node_modules/@qijenchen/design-system/src/ --include="*.tsx" \
+  | grep -v "test_\|stories\|node_modules"
+```
+
+**Playwright visual scan**(慢,適合 geometry / a11y / interaction):
+```bash
+use the active browser/Storybook screenshot workflow and preserve visual evidence
+# 或 base 同 pattern 自寫 dim-specific scan
+```
+
+**Output**:候選清單(file:line + 樣本)。
+
+### Phase 1.5 — Authority classification + triage receipt
+
+產出:
+```
+Phase 1 found N candidates of same anti-pattern:
+- node_modules/@qijenchen/design-system/src/components/A/a.tsx:42  > grep match
+- node_modules/@qijenchen/design-system/src/components/B/b.tsx:18  > grep match
+- node_modules/@qijenchen/design-system/src/components/C/c.tsx:55  > 視覺 14×16
+
+Execution:
+- deterministic fix → Auto-fix all confirmed N
+- engineering judgment → 依 owning spec + highest certified capability 逐檔收斂；task／deliverable 明確要求時才加 independent review
+- 不屬 frozen scope → Backlog with evidence；不得用 defer 逃避 scope 內修復
+- 會改產品／UI／UX SSOT 且仍有真取捨 → batch-at-end human-only decision
+```
+
+不可 silent 跳過 confirmed scope；影響 N 檔是工程 blast radius，不是 user approval gate。必記錄 scope、evidence、tests 與 rollback。
+
+### Phase 2 — 批量 / 個別 fix
+
+按 Phase 1.5 authority classifier 執行。每修一檔:
+- 用 Edit(不 Write,降風險)
+- 修完 grep 該 anti-pattern 應 0 match
+- npx tsc --noEmit 必過
+
+### Phase 3 — Visual / unit verify
+
+- Visual:跑 `use the active browser/Storybook screenshot workflow and preserve visual evidence` 或 dim-specific scan
+- Unit:跑 `npm run governance:check`
+- TSC:`npx tsc -b`
+- 全綠才繼續
+
+### Phase 4 — Final report + memory + new defense
+
+```markdown
+## Scan-similar-bugs report
+
+### Root cause(來自 last fix commit `<hash>`)
+- Pattern:{ANTI_PATTERN}
+- Origin file:{first detected location}
+
+### DS-wide impact
+- {N} candidates found
+- {M} fixed this run
+- {K} deferred(spec rationale 已記)
+
+### New defense layer(防 future regression)
+- 加 canonical hook:the installed immutable governance checker(若 pattern 易 grep)，再由 generator 投影到各 provider；禁止直接新增 provider-owned hook。
+- 加 visual test:the product-specific verification workflow (when configured)(若需 Playwright)
+- 加 spec rule:{spec.md anchor}
+
+## Self-improvement capture
+- 新 anti-pattern 加進本 skill 的 Phase 0 「Bug 類型 → grep target」表
+- M10 fire 紀錄(commit 後本 skill invoke vs not)
+```
+
+寫進:
+- 對應 commit message
+- `memory/` 若是 cross-session pattern
+- 本 skill `references/` 若是 reusable detection 公式
+
+---
+
+## Authority gates(禁止跳 classifier)
+
+### Gate 1 — Phase 1 後 Triage
+N 個 candidate 的修法 scope由 agent 依 frozen scope、canonical、tests 與 rollback 自行收斂；檔案數量不構成人類工程核准門檻。
+
+### Gate 2 — 動 canonical
+若 N candidates 都 violate 同 canonical,但 canonical 本身可能 outdated → 走 audit 重訂。工程／治理決策 AUTO；只有重訂會改產品／UI／UX SSOT 且存在真取捨才停。
+
+### Gate 3 — Backlog
+只有不屬 frozen scope 的 improvement 才放 Backlog，必寫 memory + evidence + reason；Scope 內可修復項不得因 milestone 或工程偏好 defer。
+
+---
+
+## 對位其他 skill / hook
+
+| Tool | scope | 跟本 skill 關係 |
+|---|---|---|
+| `/design-system-audit` | full-dim batch audit | 本 skill 抓不到的 architectural pattern audit 補位 |
+| `/visual-audit` | 單次視覺對齊 | Phase 3 verify 用 |
+| `/scan-similar-bugs`(本) | **immediate-after-fix grep + verify** | M10 mechanical 落地 |
+| `/knowledge-prune` | 季度 governance prune | 不重複 |
+| the installed immutable governance checker E.2(hook;原 check_l3_primitive_import.sh folded 折入,P0 BLOCK) | L3 primitive import 違規 | 即時 detect,本 skill 是 batch retro scan |
+| the installed immutable governance checker(retired 2026-06 → canonical the installed immutable governance checker history;新 file / M-row 治理由 the installed immutable governance checker + the installed immutable governance checker 現役防線接手)| 新 file / M-row | 不重複 |
+
+**3 層 防線**:
+- Hook(pre/post tool):**寫的瞬間** detect
+- 本 skill(fix-time):**修完瞬間** scan DS-wide
+- `/design-system-audit`(periodic):**季度** full-dim sweep
+
+---
+
+## 世界級對照
+
+- **Chrome DevTools "find references"**:單元件變更後找其他 consumers
+- **VS Code "find similar code"**:AI-powered same-pattern scan
+- **GitHub Copilot Workspace**:fix 後自動 propose related changes
+- **WebStorm "Inspect Code → Similar Patterns"**:同 pattern detect
+
+我們對齊 4 家但加 **DS-domain-specific anti-pattern table**(Phase 0 列表),是 generic IDE 沒做到的。
+
+---
+
+## Self-improvement capture
+
+每次 invoke 完寫:
+- (a) 新發現 anti-pattern → 加到 Phase 0 表(grep target template 更新)
+- (b) Detection false positive → 修 grep regex 或加 allowlist 註解 pattern
+- (c) Phase 1 漏掃 location → 補 grep scope(extend 到 hooks/ / scripts/ etc)
+
+回填 SKILL.md 或 references/ 形成累積資產。

package/ds-canonical/fork/codex/agents/skills/ux-audit/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: ux-audit
+description: UX behavior audit for design-system components and product UI. Checks keyboard navigation, focus management, ARIA correctness, animation timing, interaction canonical (hover/click/drag/zoom), error/loading states, empty states. Invoke when user says「鍵盤用不了」「focus 跑飛」「動畫怪怪的」「無障礙檢查」, auto-invoked by `/component-quality-gate` Phase 4.5 (advanced mode) and `/design-system-audit` Dimension D4.
+---
+
+<!-- _generated: canonical provider skill projection; source: skills/ux-audit/SKILL.md; provider: codex; do not edit this adapter view. -->
+
+# UX Audit — UX 行為稽核
+
+## 存在意義
+
+現有 `/design-system-audit`(code/spec)+ `/visual-audit`(pixel)+ `/performance-audit`(render)**都不看行為**。interaction canonical、keyboard nav、focus trap、animation timing 這類 bug:
+- 視覺正常 / code 正常 / 效能正常
+- **Keyboard only user 完全卡關** / screen reader 讀不到 / focus 不回到 trigger / zoom wheel 跳大步
+
+本 skill 是稽核 6 維度的 **D4 UX 行為** canonical home。
+
+## 觸發時機(對齊 shared governance 稽核 canonical)
+
+| 情境 | 模式 | 本 skill 跑什麼 |
+|------|------|----------------|
+| 新元件 merge 前 | 進階強制 | 全面(kb / focus / ARIA / animation / interaction) |
+| 元件新功能 | 進階強制 | scoped to 新 interaction 路徑 |
+| 產品 demo 前 | 進階強制 | 全流程 keyboard-only walkthrough |
+| 日常 dev | 高效 | 主要 kb path 手動過一次 |
+| Release cut | 進階 + 全 DS | 全 DS 的 a11y / interaction 全掃 |
+
+## Preconditions
+
+- 元件 folder 存在於 `node_modules/@qijenchen/design-system/src/components/{Name}/`
+- Storybook 可啟動(用於互動驗證)
+- 若稽核產品頁:URL 可訪問
+
+## Workflow
+
+### Phase 0 — Scope 判定
+
+- 單元件 scope → Phase 1-4 對該元件
+- 全 DS / URL scope → **先全掃列 interactive 元件清單**,按 interaction 複雜度(overlay > form > row > leaf)排序逐一 audit
+
+### Phase 1 — Keyboard navigation
+
+查 7 項:
+1. **Tab order**:DOM order = 視覺 reading order?`tabIndex` 不濫用(`tabIndex > 0` 禁用)
+2. **Focus visible ring**:所有 tabbable 元素 focus 有清楚 ring(用 `focus-visible` 非 `focus`)
+3. **Activation key**:Button/Link 回應 Enter + Space;menuitem / checkbox / radio 有特定 key 規則
+4. **Arrow key navigation**:list / menu / tabs / segmented control 在 group 內用方向鍵,不用 Tab
+5. **Escape 關閉 overlay**:Dialog / Popover / Sheet / DropdownMenu 按 Esc 關閉
+6. **Focus trap**:modal overlay 內 focus 不跑出 modal 外
+7. **Focus restore**:overlay 關閉後 focus 回 trigger
+
+### Phase 2 — Focus management(across state transitions)
+
+查 4 項:
+1. **Route change / async load**:新內容載入,focus 應指向新內容開頭(main landmark / first heading)
+2. **Error / validation**:form 送出驗證失敗,focus 應回第一個 invalid field + screen reader 讀 error
+3. **Dynamic content**:可折疊 section 展開後,focus 應維持在 trigger(非跳到內容)
+4. **List item removal**:刪除 item 後 focus 應移到**相鄰** item(不跳到文件頂)
+
+### Phase 3 — ARIA correctness
+
+查 6 項:
+1. **role** 正確:`role="button"` on <div> / 正確使用 `role="dialog"` / `role="menu"` / `role="grid"`
+2. **aria-label / aria-labelledby**:icon-only button 必有 aria-label;icon + text 不重複宣告
+3. **aria-expanded / aria-haspopup**:有 overlay 的 trigger 必宣告
+4. **aria-selected / aria-checked / aria-pressed**:狀態元件必正確 sync
+5. **aria-live**:動態訊息(validation / toast)用 `aria-live="polite"` 或 `"assertive"`
+6. **aria-hidden**:裝飾 icon 必 `aria-hidden`;隱藏內容不能 keyboard focus
+
+### Phase 4 — Animation / interaction canonical
+
+查 5 項:
+1. **Animation duration**:< 200ms(micro)或 200-400ms(macro);超過 400ms 主畫面 → 可能 block 輸入
+2. **Reduce-motion respect**:`@media (prefers-reduced-motion: reduce)` 下動畫減到 0 或極短
+3. **Wheel zoom step 細緻**:> 10% 離散 = 非世界級(對齊 Figma / Preview.app ~3-5%)
+4. **Hover delay**:tooltip / hover-card 的 open delay(500ms for tooltip, 700ms for hover-card,per `tokens/motion/motion.spec.md` 三層 tier SSOT)
+5. **Drag / pan**:pointer capture 正確;release on blur
+
+### Phase 5 — Data / state coverage 五態(2026-04-24 擴充,補 24-checklist #23 edge case gap)
+
+查 5 項 + null-safety + rapid-interaction:
+
+1. **Null-safety**:`null / undefined` label/value/children 不 crash(e.g. `{label}` 為 undefined render 空字串,不 `Cannot read properties of undefined`);空 array `.map()` 不 crash;emoji / 超長單字 / RTL 字元不爆版
+2. **Empty**:顯示 `<Empty>` 或對應 placeholder,非 blank;empty 有 CTA 讓使用者知道下步
+3. **Loading**:視語境用 CircularProgress / Skeleton / ProgressBar;aria-busy 宣告;**不阻斷可編輯狀態**(Input loading 仍可打字 per spec);**rapid-click / double-submit 有防護**(button loading 期間 disabled OR 靠上游 idempotent)
+4. **Error**:用 DS `<Notice>` 或 inline `<FieldError>`;配合 aria-live 通知 AT;error message 不吞(e.g. async rejection 有 fallback UI 非 silent swallow)
+5. **Success**(新加):成功 state 有視覺確認(toast / inline checkmark / state transition),讓使用者知道動作 landed,非 silent success
+
+**Edge case corollary**(現實髒資料):
+- Children 為 `null` / 為空 array / 元素數量極大(超 50 筆)
+- Option 重複 id / selected option 被移除後仍保留 value(stale selection)
+- disabled 時仍收到外部 value 更新(controlled forced update)
+- 從 uncontrolled 中途變 controlled(React warning 必出,或元件明文不支援)
+- Modal 關閉瞬間 async 回調仍 setState(unmount 後 setState warning)
+
+### Phase F — Report and route
+
+產出:
+
+```markdown
+# UX Audit — {Scope} — {YYYY-MM-DD}
+
+## Summary
+- Keyboard: PASS / N fails
+- Focus: PASS / M fails
+- ARIA: PASS / K fails
+- Animation: PASS / L fails
+- Three states: PASS / P fails
+
+## Findings(按 severity 排序)
+### P0(完全 block a11y)
+### P1(嚴重影響 UX)
+### P2(建議改善)
+
+## Authority classification
+- P2E:{工程／治理 finding，交 canonical owner 自主修復}
+- P2H:{只有真正產品／UI／UX SSOT 取捨才列 exact target-bound decision}
+```
+
+本 skill 保持 read-only，report 是 evidence receipt；caller／canonical owner 對 P2E 直接接續
+修復與驗證，不把 read-only skill boundary 誤當 user checkpoint。只有 P2H 或
+shared-governance human-only boundary 才停止。
+
+## Non-goals
+
+- 不改 code / spec(純 read-only report)
+- 不做視覺稽核(走 `/visual-audit`)
+- 不做 code-level audit(走 `/design-system-audit`)
+
+## 相關
+
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/design-system-audit/SKILL.md` — 全 dim 統籌(per design-system-audit SSOT);本 skill 是 D4 補位
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/visual-audit/SKILL.md` — pixel 層(D5)
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/performance-audit/SKILL.md` — 效能層(D3)
+- `node_modules/@qijenchen/design-system/ds-canonical/skills/component-quality-gate/SKILL.md` — Phase 4.5 進階模式 chain 本 skill