@qijenchen/design-system 0.1.0-beta.3 → 0.1.0-beta.32

package/ds-canonical/hooks/tests/test_stop_passive_logging.sh

@@ -0,0 +1,100 @@
+#!/bin/bash
+# Tests for stop_passive_logging.sh — Stop hook orchestrator(5 internal rules:tsc_sanity / harvest_corrections / capture_metrics / governance_drift / infra_best_practice_score)
+#
+# Orchestrator smoke test only — all 5 internal rules are passive(silent log to .claude/logs/*.jsonl,no stderr / no exit non-zero)。
+# Detailed rule tests are within their original lib hooks(now folded into this dispatcher,unit tests at lib level historically)。
+#
+# 2026-05-23 ship per Phase D4 sub-threshold cleanup(15+1 hook tests batch)。
+
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK="$SCRIPT_DIR/../stop_passive_logging.sh"
+
+if [ ! -x "$HOOK" ]; then
+  echo "FATAL: hook not executable: $HOOK"
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+FAILED_TESTS=""
+
+run_hook() {
+  local payload="$1"
+  STDOUT=$(mktemp); STDERR=$(mktemp)
+  set +e
+  printf '%s' "$payload" | bash "$HOOK" >"$STDOUT" 2>"$STDERR"
+  EXIT=$?
+  set -e
+  STDOUT_TEXT=$(cat "$STDOUT")
+  STDERR_TEXT=$(cat "$STDERR")
+  rm -f "$STDOUT" "$STDERR"
+}
+
+expect_pass_silent() {
+  local name="$1"
+  if [ "$EXIT" = "0" ] && [ -z "$STDOUT_TEXT" ] && [ -z "$STDERR_TEXT" ]; then
+    echo "  PASS  $name"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (exit=$EXIT, stdout='$STDOUT_TEXT', stderr='$STDERR_TEXT')"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+expect_exit_0() {
+  local name="$1"
+  if [ "$EXIT" = "0" ]; then
+    echo "  PASS  $name (exit 0)"; PASS=$((PASS+1))
+  else
+    echo "  FAIL  $name (expected exit 0, got $EXIT)"
+    FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - $name"
+  fi
+}
+
+echo "=== stop_passive_logging tests(orchestrator smoke)==="
+
+# 1. bash -n syntax check
+bash -n "$HOOK"
+if [ $? = 0 ]; then echo "  PASS  1. syntax OK"; PASS=$((PASS+1)); else echo "  FAIL  1. syntax broke"; FAIL=$((FAIL+1)); fi
+
+# 2. empty JSON input → exit 0 silent
+run_hook '{}'
+expect_exit_0 "2. empty JSON input → exit 0"
+
+# 3. session_id only → exit 0
+run_hook '{"session_id":"test-session-abc"}'
+expect_exit_0 "3. session_id input → exit 0"
+
+# 4. transcript_path nonexistent → exit 0(graceful)
+run_hook '{"transcript_path":"/tmp/nonexistent-test-transcript.jsonl","session_id":"test"}'
+expect_exit_0 "4. nonexistent transcript → exit 0 graceful"
+
+# 5. invalid JSON → exit 0(jq fail handled)
+run_hook 'not-valid-json'
+expect_exit_0 "5. malformed JSON input → exit 0"
+
+# 6. valid empty transcript → exit 0
+TMP_TRANSCRIPT=$(mktemp)
+echo '' > "$TMP_TRANSCRIPT"
+run_hook "{\"transcript_path\":\"$TMP_TRANSCRIPT\",\"session_id\":\"test\"}"
+rm -f "$TMP_TRANSCRIPT"
+expect_exit_0 "6. empty transcript file → exit 0"
+
+# 7. realistic Stop event payload → exit 0(R3 capture_metrics may write log file,but exit 0 invariant)
+TMP_TRANSCRIPT=$(mktemp)
+cat > "$TMP_TRANSCRIPT" << 'EOF'
+{"type":"user","message":{"role":"user","content":"test"}}
+{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"reply"}]}}
+EOF
+run_hook "{\"transcript_path\":\"$TMP_TRANSCRIPT\",\"session_id\":\"test-smoke\"}"
+rm -f "$TMP_TRANSCRIPT"
+expect_exit_0 "7. realistic Stop event payload → exit 0"
+
+echo ""
+echo "=== Summary ==="
+echo "Passed: $PASS / $((PASS+FAIL))"
+if [ $FAIL -gt 0 ]; then
+  echo -e "Failed:$FAILED_TESTS"
+  exit 1
+fi

package/ds-canonical/hooks/tests/test_stop_self_audit.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+# Smoke + behavior test for stop_self_audit.sh
+# 2026-04-30:升 BLOCKER 行為(Mechanism 1 claim-verify gap)後加 case 2-4
+set -u
+HOOK="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../stop_self_audit.sh"
+[ -x "$HOOK" ] || { echo "FATAL: hook not executable"; exit 1; }
+
+PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+TMPDIR=$(mktemp -d)
+trap 'rm -rf "$TMPDIR"' EXIT
+
+PASS=0; FAIL=0
+run_test() {
+  local name="$1"; local expect_block="$2"; local transcript_content="$3"
+  local transcript="$TMPDIR/transcript-$$.jsonl"
+  printf '%s\n' "$transcript_content" > "$transcript"
+  local input
+  input=$(printf '{"transcript_path":"%s","session_id":"test"}' "$transcript")
+  # Reset state to avoid block-once dedup interference
+  rm -f "$PROJECT_DIR/.claude/logs/.last-blocked-claim.txt" 2>/dev/null
+  local stdout; stdout=$(echo "$input" | bash "$HOOK" 2>/dev/null)
+  if [ "$expect_block" = "1" ]; then
+    if echo "$stdout" | grep -q '"decision":"block"'; then
+      echo "  PASS  $name (blocked as expected)"; PASS=$((PASS+1))
+    else
+      echo "  FAIL  $name (expected block, got: ${stdout:0:120})"; FAIL=$((FAIL+1))
+    fi
+  else
+    if echo "$stdout" | grep -q '"decision":"block"'; then
+      echo "  FAIL  $name (unexpected block: ${stdout:0:120})"; FAIL=$((FAIL+1))
+    else
+      echo "  PASS  $name (no block)"; PASS=$((PASS+1))
+    fi
+  fi
+}
+
+echo "Test 1: minimal payload → no crash"
+out=$(echo '{}' | bash "$HOOK" 2>&1); exit_code=$?
+[ "$exit_code" -le 2 ] && echo "  PASS exit=$exit_code" && PASS=$((PASS+1)) || { echo "  FAIL exit=$exit_code"; FAIL=$((FAIL+1)); }
+
+# Test 2: claim「verified」+ no tsc → BLOCK
+# NOTE(2026-05-01): hook find last 真 user prompt(role=user 且 content
+# 非 tool_result),fixtures 必有 user msg 在 assistant 之前反映真實
+# transcript 結構。
+USER_MSG='{"message":{"role":"user","content":[{"type":"text","text":"幫我修 bug"}]}}'
+
+T2="$USER_MSG
+"'{"message":{"role":"assistant","content":[{"type":"text","text":"已修完,verified ✓ 全部 done"}]}}'
+run_test "Test 2: claim+no-verify → block" 1 "$T2"
+
+# Test 3: claim「verified」+ tsc 跑過 → no block
+T3="$USER_MSG
+"'{"message":{"role":"assistant","content":[{"type":"text","text":"已修完,verified"}]}}
+{"message":{"role":"assistant","content":[{"type":"tool_use","name":"Bash","input":{"command":"npx tsc -b"}}]}}'
+run_test "Test 3: claim+tsc → no block" 0 "$T3"
+
+# Test 4: claim「verified」+「撤回 claim」escape → no block
+T4="$USER_MSG
+"'{"message":{"role":"assistant","content":[{"type":"text","text":"先前 verified 說錯,撤回 claim,實際未修好"}]}}'
+run_test "Test 4: claim+retract escape → no block" 0 "$T4"
+
+# Test 5: 純對話無 claim → no block
+T5="$USER_MSG
+"'{"message":{"role":"assistant","content":[{"type":"text","text":"我來看看這個 bug 是怎麼回事"}]}}'
+run_test "Test 5: no claim → no block" 0 "$T5"
+
+# Test 6: claim-denial「明確不 claim verified」preemptive denial → no block
+T6="$USER_MSG
+"'{"message":{"role":"assistant","content":[{"type":"text","text":"我這次明確不 claim verified,只 tsc 過,實際 browser 行為要 user 驗"}]}}'
+run_test "Test 6: preemptive claim denial → no block" 0 "$T6"
+
+# Cleanup state file
+rm -f "$PROJECT_DIR/.claude/logs/.last-blocked-claim.txt" 2>/dev/null
+
+echo "Results: $PASS PASS, $FAIL FAIL"
+[ "$FAIL" -eq 0 ] || exit 1

package/ds-canonical/hooks/tests/test_stop_tsc_sanity.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+# Smoke test for stop_tsc_sanity.sh
+set -u
+# Cluster B merge(2026-05-10):stop_tsc_sanity.sh fold 進 stop_passive_logging.sh dispatcher R1。
+HOOK="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../stop_passive_logging.sh"
+[ -x "$HOOK" ] || { echo "FATAL"; exit 1; }
+echo "Test 1: minimal payload → no crash"
+STDOUT=$(echo '{}' | bash "$HOOK" 2>&1); EXIT=$?
+[ "$EXIT" -le 2 ] && echo "  PASS exit=$EXIT" || { echo "  FAIL exit=$EXIT out=${STDOUT:0:100}"; exit 1; }
+echo "Results: 1 PASS, 0 FAIL"

package/ds-canonical/references/README.md

@@ -0,0 +1,43 @@
+# .claude/references/ Charter
+
+## 這裡只收:**agent infrastructure reference**(非 product canonical)
+
+Agent 在執行時按需讀的深度 reference 檔 — audit protocol / FP 記憶 / workflow recipe / lookup tables。**不是 product design canonical**(那該進 spec.md / CLAUDE.md)。
+
+## 當前居民(15 檔,2026-05-18 update)
+
+| Ref | 用途 |
+|-----|------|
+| `audit-coverage-vs-24-checklist.md` | 業界 24-checklist 對照 + 為何不平行 audit 24 dim rationale |
+| `build-ui-canonicals.md` | 建 UI 前 12 情境 + 8 layout primitive lookup |
+| `cva-patterns.md` | cva 適用 / 不適用 + 例外清單(跟 CLAUDE.md shadcn 規範互補) |
+| `drag-canonical.md` | 世界級 drag impl 對照 + dnd-kit collision strategy + Phase 1/2 fix plan |
+| `item-anatomy-recipe.md` | 7 步建立新 row primitive workflow + audit grep guard |
+| `naming-conventions.md` | 命名詳表 + 禁止清單(CLAUDE.md # 命名一致性 pointer) |
+| `principle-dim-map.json` | M-rule / trait / hook → audit dim explicit mapping(SSOT for dim coverage) |
+| `props-naming.md` | Props callback / Badge / icon canonical 詳表 |
+| `spec-rules.md` | SSOT 機制 / 邊界案例 scope default 詳展 |
+| `ssot-consultation.md` | SSOT 消費完整對照表 |
+| `ssot-index.md` | High-risk interface ownership map(propose 前 grep 找 owner) |
+| `structural-token-retention.md` | 6 類結構性保留 token canonical(audit Dim 48 triple-verify) |
+| `tailwind-gotchas.md` | Tailwind v4 / tailwind-merge 技術陷阱深展 |
+| `ui-dev-rules.md` | flex slot 幾何 / 數值前先查 / Padding 三層 / Icon size 三類 |
+
+## 這裡**不收**(反例 + 正確去處)
+
+| 疑似要放這但其實不是 | 正確去處 | 為什麼 |
+|---------------------|---------|--------|
+| 設計 canonical judgment(non-programmable)| `spec.md` 或 CLAUDE.md | 2-home 架構:spec / tsx 才是 canonical home。AI 做產品時**必讀** spec,不會必讀 references |
+| 實作值 / 計算公式 | tsx / cva / CSS | programmable rule 進 code |
+| 跨 session 狀態 | `memory/` | references 不是 state 檔 |
+| 多步驟 workflow + checkpoint | `.claude/skills/` | skill 管 workflow,reference 是 skill 按需讀的 |
+
+## 新 reference 的 criteria
+
+1. **Audit / skill 按需查的 lookup data**(表格 / 詳細對照 / 反例清單)
+2. **不含 canonical judgment**(判斷 rule 在 spec / CLAUDE.md)
+3. **被 ≥ 1 skill / CLAUDE.md / spec cite**(orphan file 不收,定期 prune 會 retire)
+
+## 2026-04-24 Lesson
+
+前曾把 canonical judgment(24px threshold / disabled state 策略 / primitive exposure 3 題)錯搬到 references,違反 2-home 架構(spec 該是 canonical home 讓 AI 做產品時讀)。Restored 回 spec。references 現在嚴格只收 agent-use lookup。

package/ds-canonical/references/audit-coverage-vs-24-checklist.md

@@ -0,0 +1,74 @@
+# Audit 覆蓋 vs 業界 24 節 checklist —— 對照 + 決策
+
+**Date**: 2026-04-24
+**Trigger**: User 問「我們稽核缺了哪些?」→ 用業界通用 24 節 checklist 做 gap 分析
+**本 doc 目的**: 釘住「為什麼不補某些項」的 rationale,避免下次又被誤認為缺口
+
+---
+
+## 核心洞察 — Dim 9 是 multiplier
+
+**「符合 shadcn / Radix primitive 框架」這條 audit(`/design-system-audit` Dim 9)驗過 → 自動吃掉 24 節中 8 節大部分**。
+
+這是 M1「SSOT」+ mindset #2「優先消費既有」在 meta 層的體現:shadcn + Radix = 我們的 framework SSOT,它一致 = 下游一致,不必平行補 24 dim。
+
+| 24-checklist # | 被 Dim 9 / Radix 吸收的原因 |
+|---|---|
+| #4 Ref | shadcn 強制 `forwardRef` + `displayName`,Dim 9 必驗 |
+| #5 Composition | shadcn 強制 `asChild` + Slot + `{...props}` spread |
+| #6 HTML 語意 | Radix primitive 用對 `<button>` / `<a>` / `[role]` |
+| #7 A11y 核心 | Radix 內建 keyboard / ARIA / SR |
+| #8 state 大半 | Radix forwards `data-state="open/closed/checked"` |
+| #11 Overlay focus trap / portal | Radix DialogPortal / Popover 內建 |
+| #12 form native props | `{...props}` spread 到 native input |
+| #1 native HTML attributes | `{...props}` spread 解 |
+
+## 被 tsconfig + Vite + ESM 架構吸收
+
+| 項目 | 吸收者 |
+|---|---|
+| #2 TS 大半 | `strict / noUnusedLocals / noUnusedParameters / noFallthroughCasesInSwitch / noUncheckedSideEffectImports` |
+| #19 Package export | `type: module` + Vite dev/build + 無 barrel |
+| #16 SSR | **不適用**(Vite SPA 不是 Next/Remix) |
+| #14 unmount / listener cleanup 大半 | React strict mode dev 雙 mount + tsc useEffect deps |
+
+## 刻意不補 — 架構決策
+
+| 項目 | 不補的 rationale |
+|---|---|
+| #17 unit test | 走 **story-as-test + visual-regression**(stories + `/visual-audit` Layer A + M11 interactive state walk)。補 unit = 重複 story 覆蓋,`/story-writing` earn-existence 原則視其為 noise |
+| #19 CJS 輸出 | 內部 DS 非發 npm package,CJS 是 dead requirement |
+| #22 cross-browser full matrix | Firefox / IE 不是我們受眾;iOS Safari 有 Radix ensures 大半。補全 matrix = 過度 |
+| #20 CVE 全套 | 內部 DS 非 public npm,補 `npm audit` weekly cron 夠 |
+
+## 真缺 + 已補(2026-04-24)
+
+| 真缺項 | 補的形式 | Commit |
+|---|---|---|
+| #13 i18n 硬寫字串 | `.claude/hooks/check_hardcoded_strings.sh` PostToolUse,flag DS primitive tsx(非 stories)CJK ≥ 3 chars / 英文 sentence-case label;支援 `// i18n-allow: {rationale}` 白名單 | 本次 session |
+| #3 Controlled / Uncontrolled + #12 Form dual-mode | `design-system-audit` Dim 26(新 Group J)— 掃 form + overlay 元件 value/defaultValue / open/defaultOpen / checked/defaultChecked 的 pair 完整性;V1-V4 violation types | 本次 session |
+| #23 edge case(null / empty / rapid / success) | `/ux-audit` Phase 5 從 3 態 → 5 態 + null-safety + rapid-interaction + edge case corollary | 本次 session |
+
+## 未補 — 以後真需要再補
+
+| 項目 | trigger 條件 |
+|---|---|
+| #22 cross-browser 抽測 | 第一個 Safari-specific bug 落地 → 建 weekly Playwright Safari smoke test |
+| #20 `npm audit` cron | 第一次 dep CVE 被通知 → schedule `npm audit` weekly report |
+| RTL 支援 | 第一個 RTL 產品需求 → 補 RTL audit dim + 測 logical properties |
+| Next.js / Remix 整合 | DS 要發 npm 時 → 補 `use client` boundary + SSR 測試 |
+
+## 為什麼不寫成 24 dim 平行 audit
+
+**`/design-system-audit` 若膨脹成 24 dim** → 平行跑 24 個 sub-agent 每個吐 400-字 report → user cognitive load 爆 + 重複判斷(e.g. #4 Ref / #5 Composition 都是 shadcn 已驗的)。正確姿態:
+
+1. **Framework audit(Dim 9)嚴格化** = 一條驗過 cascade 吸收 8 節
+2. **新 dim 只為真無法從 framework 推導的 gap**(i18n / controlled-uncontrolled / edge case 三個)
+3. **FAQ / 常被問到但已覆蓋的項**寫本 doc,下次 user 問「我們缺 X 嗎」先讀本 doc 再答
+
+## Cross-link
+
+- CLAUDE.md `# 稽核 canonical` 3-tier × 6-dim
+- CLAUDE.md Meta-Pattern M1(SSOT)+ M8(benchmark)+ M10(exhaustive scan)
+- `.claude/skills/design-system-audit/SKILL.md` Groups A-J
+- `.claude/skills/ux-audit/SKILL.md` Phase 5

package/ds-canonical/references/build-ui-canonicals.md

@@ -0,0 +1,69 @@
+# 建立 UI 前的 DS canonical 對照(從 CLAUDE.md 拆出的完整對照)
+
+本檔是 `.claude/rules/ui-development.md`「建立 UI 前必讀」的**完整對照表**。Rule 主章只留「超級規則 + 自我檢查腳本」,遇到具體情境要查對照時讀本檔。
+
+---
+
+## 既有 DS 元件 / primitive 優先消費(完整表)
+
+**超級規則**:**`ls packages/design-system/src/components/` + `ls packages/design-system/src/patterns/` 看一次。任何視覺 / 行為命中既有元件 → 必消費,不 hand-craft raw HTML 繞過**。
+
+### 常見手刻 vs canonical 對照
+
+| 情境 | ❌ anti-pattern(手刻) | ✅ canonical(用 DS) |
+|------|---------------------|---------------------|
+| Select / 下拉選單 | `<Popover><PopoverContent><button className="flex items-center px-2">...</button></PopoverContent></Popover>` | `<Select options={...} />` or `<DropdownMenu><DropdownMenuItem>` |
+| Input 欄位 | `<input className="h-field-sm w-20 pl-3 pr-7 border ..." />` | `<Input size="sm" />` or `<NumberInput />` |
+| 列表項目 row(icon + text + action) | `<div className="flex items-center gap-2"><Icon/><span/><Button/></div>` | `<MenuItem>` + slot components(`<ItemIcon>` / `<ItemLabel>` / `<ItemSuffix>`) |
+| 資料表格(含 header / sorting / sticky) | `<table><thead>...</thead><tbody>...</tbody></table>` | `<DataTable columns={...} data={...} />` |
+| 檔案上傳列表 | `<div>filename</div><ProgressBar /><Paperclip />` | `<FileItem mode="compact" />` or `<FileUpload>` |
+| 表單欄位(label + control + error) | `<label>...</label><input/><span className="text-error">...</span>` | `<Field><FieldLabel>...<Input />...<FieldError/>` |
+| 全頁 / 區域 loading | `<div className="absolute inset-0 flex center"><Spinner /></div>` | `<Empty icon={<CircularProgress />} description="..." />` |
+| 確認對話框 | raw `<div className="fixed inset-0 bg-black/50">...<button>OK</button>` | `<Dialog>` + `<DialogHeader>` etc |
+| 分隔線 | `<hr className="..." />` or `<div className="h-px bg-..."/>` | `<Separator />`(必要時)or CSS border(見 separator.spec) |
+| 標籤分類 / 狀態 chip | `<span className="inline-flex px-2 py-0.5 bg-... rounded">...</span>` | `<Tag variant="..." />` or `<Badge />` |
+| 使用者頭像 | `<img className="w-8 h-8 rounded-full" />` | `<Avatar>` |
+| 浮層(彈出資訊) | `<div className="absolute bg-white shadow p-3">...</div>` | `<Popover>` / `<HoverCard>` / `<Tooltip>`(視語義選) |
+| 浮層 media + title + description + actions | 自組 `<div>` 結構 | `<Coachmark>` 或 `<Dialog>`(視是否阻斷) |
+
+**Story 特別提醒**:**stories 也是 code**。如果 story 在 label / comment 說「DataTable cell 用法」「Table 配額」「Menu 選單」等,**要 render 真的該元件 demo,不可用 raw `<table>` / raw `<button>` 假裝**。否則 story 教壞 consumer、自己也在破壞 DS 訓練資料。
+
+`check_story_anatomy.sh` hook 會在 Write/Edit 階段攔下這類手刻;allowlist `// @anatomy-exempt: <reason>`(檔首)/ `// @anatomy-exempt-next`(下一行)可豁免教學用 raw primitive。
+
+---
+
+## Layout primitive 特別子集(建立 pattern-level 新元件前 mechanical 掃)
+
+以下是 **pattern-level** primitives(跨元件共用的視覺結構),建立新元件前必查。若新元件的視覺結構命中任一 row 的 pattern → **必消費該 primitive**,不自己重寫一套。漏掉 = 雙邊漂移 bug(改一邊另一邊失效)。
+
+| 視覺 pattern | 既有 primitive | 典型觸發情境 |
+|------|---------|---------|
+| 單列 row:prefix(icon/avatar) + content + suffix(action) | `patterns/element-anatomy/item-anatomy.*` — `<MenuItem>` canonical + slot components | 任何「列表項目」元件(Menu/Tree/Sidebar/TableRow/StepItem/FileItem...) |
+| 浮層容器的 Header + Body + Footer(border-b/t + padding token) | `patterns/overlay-surface/` — `SurfaceHeader/Body/Footer` | Dialog / Popover / Drawer / Sheet / 任何 elevation-200 浮層的結構化 sub-components |
+| **垂直居中 icon + title + description(+ action)** | `components/Empty/` — `<Empty>` 元件 | **「告訴使用者狀態」的 surface**:空資料 / 拖放邀請(FileUpload)/ 錯誤 / 首次引導 / 無權限 / 載入佔位(非 Skeleton)|
+| 橫向操作按鈕列（gap-2 分組）| `patterns/action-bar/` | Toolbar、page header actions、form footer buttons |
+| 水平溢出處理(捲動/收合,**隱藏捲軸+ fade-mask** UX)| `patterns/horizontal-overflow/` | Tabs / ChipGroup / 未來 Steps 的溢出(刻意隱藏 scrollbar) |
+| **跨 OS 一致 overlay 捲軸(顯示捲軸但不吃寬度)** | `components/ScrollArea/` | DataTable 水平捲動 / Sheet / Dialog body / Sidebar 長 nav 等需要使用者知道有捲軸又要跨 OS 視覺一致 |
+| **固定長寬比容器(防 CLS 坍塌,多張圖統一 ratio)** | `components/AspectRatio/` | Coachmark media / Carousel item image / Card thumbnail / Chart container(override default 16:9) |
+| Field wrapper（border + padding + startIcon + endAction 結構) | `components/Field/field-wrapper.tsx` + `field-controls.spec.md` | 所有單行可編輯欄位元件 |
+
+### 自我檢查腳本(CLAUDE.md 保留這節的精簡版,完整對照在本檔上表)
+
+- 新元件有 icon+text 垂直堆疊? → 用 `<Empty>`,不自己畫 icon + title + desc
+- 新元件有橫向 row 結構(prefix/content/suffix)? → 用 `element-anatomy/item-anatomy` 的 `<MenuItem>` + slot components(`<ItemIcon>` / `<ItemAvatar>` / `<ItemLabel>` / `<ItemSuffix>` / `<ItemInlineAction>`)
+- 新元件是浮層 + 有 header/body/footer? → 用 `overlay-surface`
+- 新元件內容**可能溢出容器且需要使用者捲動**? → 用 `ScrollArea`(跨 OS 一致 overlay 捲軸);若是刻意隱藏捲軸 + fade-mask → 用 `horizontal-overflow` pattern
+- 新元件有**圖像 / media 容器需要鎖定長寬比**(防 CLS、統一多張圖比例)? → 用 `AspectRatio` primitive,不硬寫 `aspect-video` / `aspect-square` class
+- 以上都沒命中 → 才可自建,但 **建完要立刻回來加行**(防下一個人又重造輪子)
+- **本規則同樣適用 story / consumer / exploration code**:不 hand-craft 已有 prop 能做的事(如 Input loading 走 `loading` prop 不自刻 `<div className="relative"><input/><div className="absolute">` / 全頁 loading 走 `<Empty icon={<CircularProgress/>}/>` 不自刻 `absolute inset-0`)。遇缺口**回元件 spec 擴 API**,不自刻繞過 — hand-craft 視覺對齊 bug 上游
+
+具體 anti-pattern signals → `/design-system-audit` Dim 21;pixel-level 視覺 regression(API 用對但視覺仍跑掉)tech debt → memory `project_pending_tasks`。
+
+---
+
+## overflow 使用三規則(避免跨 OS 跑版)
+
+1. Design-system 元件 `.tsx` 內**禁止** raw `overflow-auto / overflow-scroll / overflow-{x,y}-{auto,scroll}`(hook `check_token_hygiene.sh` check #4 守衛)
+2. 需捲軸且跨 OS 一致 → 用 `ScrollArea`
+3. 刻意隱藏捲軸 + fade-mask → 用 `horizontal-overflow` pattern
+4. 例外:`overlay-surface` spec 明文允許 Dialog body `flex-1 overflow-y-auto`(viewport-fill 特殊 context);若未來此場景需跨 OS 一致,遷移 ScrollArea 再更新 spec

package/ds-canonical/references/cva-patterns.md

@@ -0,0 +1,41 @@
+# cva 適用範圍 完整對照(從 CLAUDE.md 拆出)
+
+`.claude/rules/ui-development.md`「shadcn 元件規範」 留判斷法 + 禁止一句話;完整對照表和 documented 例外在本檔。
+
+---
+
+## 變體 × 實作模式對照
+
+`cva()` 是系統管理 **className 變體**的標準工具,但**不是所有變體都該用 cva**。合法的**非 cva** 實作模式:
+
+| 變體類型 | 實作方式 | 範例 |
+|---------|---------|------|
+| className 變體(bg / text / border / size / state) | **`cva()`** | Button / SegmentedControl / Chip / Tag / Field Controls 等絕大多數 |
+| **Style prop 驅動的 variant**(需要 `style={{ backgroundColor: 'var(--...)' }}`)| **Object map / lookup table**(world-class:Material / Ant / Polaris 同樣做法) | **Avatar** 的 color variants 驅動 inline style;cva 無法產 style object |
+| **結構性變體**(不同 mode 是不同 layout,不只 class swap) | **Conditional rendering / sub-components** | **FileItem** 的 `compact / rich` mode 有不同 flex 結構 |
+
+---
+
+## 當前系統 documented 例外
+
+- **`Avatar`**:color variants 用 object map(原因:inline style prop;cva 無法產 style object)
+- **`FileItem`**:mode variants 用 if-branches(原因:結構性差異,不是 class swap;compact vs rich 是不同 flex 樹)
+
+---
+
+## 新增例外判斷法
+
+要加例外(= 某元件變體不用 cva)前先問:
+1. 變體差異 **真的需要 inline style** 嗎?(有些看似需要其實可用 CSS variable + data attribute 解)
+2. **結構性差異**夠大嗎?(只差一個 slot 可以 cva + `data-mode` 選擇器;不同 root layout 才算結構)
+3. 世界級 DS(Material / Ant / Polaris)怎麼處理同類變體?
+
+若答案 3 題都指向「非 cva」,加 documented 例外 + 更新本檔。否則先嘗試 cva。
+
+---
+
+## 禁止
+
+- ❌ 為了「一律用 cva」硬把 style prop 變體塞進 cva(無法優雅產出 style object)
+- ❌ 為了「一律用 cva」把不同結構的 mode 強制壓到同一棵 JSX 配 className 切換(code 會長滿 `{mode === 'rich' && ...}` hacks)
+- ❌ 「新例外」沒寫進本檔的 documented 例外清單(= 隱性 drift)