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

package/ds-canonical/hooks/check_app_shell_primary_header_consistency.sh

@@ -1,68 +0,0 @@
-#!/usr/bin/env bash
-# check_app_shell_primary_header_consistency.sh — PreToolUse Edit/Write
-#
-# 2026-05-21 ship per user directive「該程式化的就程式化」+「確認當有 global header 時,
-# sidebar 內的 header 應該要拿掉」+ world-class GitHub/Gmail/Figma 共識。
-#
-# Detects 2 violations in AppShell consumer code:
-#   V1) `layout="primary-header"` without `globalHeader=...` prop
-#       → 缺 globalHeader 而 layout=primary-header 是邏輯矛盾(per app-shell.spec.md
-#         「primary-header = primary-sidebar + 一條 global header」)
-#
-#   V2) `layout="primary-header"` + 任何 `<SidebarHeader>...</SidebarHeader>` 在同 file
-#       → WorkspaceBrand 已該在 globalHeader,sidebar 內不該再有 SidebarHeader
-#         (per app-shell.spec.md「WorkspaceBrand 放置 SSOT」+ world-class GitHub/Gmail/Figma 一致)
-#
-# 對齊 .claude/rules/self-verify.md「Pre-edit」階段 + check_chrome_header_handcraft.sh /
-# check_overlay_handcraft.sh 等既有 SSOT-enforcement hook idiom。
-# Exception escape:`// @app-shell-primary-header-allow: <reason>` 檔頭。
-
-set -uo pipefail
-source "$(dirname "$0")/_log-fire.sh"
-
-# 只看 Edit / Write tool
-TOOL_NAME=$(echo "${CLAUDE_TOOL_INPUT:-}" | python3 -c "import sys,json; d=json.load(sys.stdin) if sys.stdin.isatty()==False else {}; print(d.get('tool_name',''))" 2>/dev/null || echo "")
-if [[ "$TOOL_NAME" != "Edit" && "$TOOL_NAME" != "Write" ]]; then exit 0; fi
-
-TARGET=$(echo "${CLAUDE_TOOL_INPUT:-}" | python3 -c "import sys,json; d=json.load(sys.stdin) if sys.stdin.isatty()==False else {}; print(d.get('tool_input',{}).get('file_path',''))" 2>/dev/null || echo "")
-# 只查 .tsx / .stories.tsx consumer file
-if [[ ! "$TARGET" =~ \.(tsx)$ ]]; then exit 0; fi
-if [[ ! -f "$TARGET" ]]; then exit 0; fi
-
-# 排除 spec / test / SSOT 檔
-case "$TARGET" in
-  *.spec.md|*test*|*/AppShell/app-shell.tsx) exit 0 ;;
-esac
-
-# Escape allowlist
-if grep -q "@app-shell-primary-header-allow:" "$TARGET"; then exit 0; fi
-
-# 偵測 layout="primary-header"
-if ! grep -q 'layout="primary-header"\|layout={["\047]primary-header["\047]}' "$TARGET"; then exit 0; fi
-
-VIOLATIONS=()
-
-# V1:layout="primary-header" 但無 globalHeader=
-if ! grep -q 'globalHeader\s*=' "$TARGET"; then
-  VIOLATIONS+=("V1 缺 globalHeader prop:layout=\"primary-header\" 必傳 globalHeader 否則邏輯矛盾(per app-shell.spec.md「primary-header = primary-sidebar + 一條 global header」)")
-fi
-
-# V2:layout="primary-header" + <SidebarHeader> 同 file → WorkspaceBrand 該在 globalHeader 不重複
-if grep -q '<SidebarHeader' "$TARGET"; then
-  VIOLATIONS+=("V2 Sidebar 內含 SidebarHeader:primary-header mode WorkspaceBrand 該在 globalHeader,sidebar 內不該重複(per spec.md「WorkspaceBrand 放置 SSOT」+ world-class GitHub/Gmail/Figma 共識)。若 sidebar header 是其他內容(非 brand),加 escape allowlist `// @app-shell-primary-header-allow:` 並說明 reason")
-fi
-
-if [[ ${#VIOLATIONS[@]} -gt 0 ]]; then
-  echo "🚨 AppShell primary-header consistency violation" >&2
-  echo "Target: $TARGET" >&2
-  for v in "${VIOLATIONS[@]}"; do echo "  • $v" >&2; done
-  echo "" >&2
-  echo "修法:" >&2
-  echo "  (a) 傳 globalHeader prop / 撤掉 SidebarHeader" >&2
-  echo "  (b) 改 layout=\"primary-sidebar\"(若不需要 global header)" >&2
-  echo "  (c) Escape 允許:檔首加 \`// @app-shell-primary-header-allow: <rationale>\`" >&2
-  log_fire "check_app_shell_primary_header_consistency"
-  exit 2
-fi
-
-exit 0

package/ds-canonical/hooks/check_chrome_header_handcraft.sh

@@ -1,70 +0,0 @@
-#!/bin/bash
-set -uo pipefail
-# Header canonical Layer 3 ChromeHeader consumption enforcement(per header-canonical.spec.md Layer 3):
-#   Production chrome header 必消費 `<ChromeHeader>` primitive,
-#   不可自寫 `h-[var(--chrome-header-height)] border-b border-divider px-loose` 那一套 className。
-#
-# PreToolUse(Edit / Write)hook —— 編輯 `packages/design-system/src/components/**/*.tsx`(非 stories)時掃:
-#   檔內若有完整手刻 chrome header className signature → P1 soft warning(stderr,exit 0)。
-#   Migration 完成後升 P0 BLOCKER(exit 2)。
-#
-# 當前期(2026-05-17 land Phase 2):Sidebar / FileViewer 已 migrate 完,其他元件若新加 chrome
-# header 自刻 = drift,本 hook 攔。
-#
-# Allow escape:檔頭 `// @chrome-header-handcraft-allow: <reason>` 豁免(Tabs cva-on-pattern 等
-# 不適合用 primitive 的 case);本 hook 本身與 ChromeHeader / SurfaceHeader / SidebarHeader.tsx
-# 不攔(那些是 primitive 自己)。
-
-source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
-
-set -euo pipefail
-
-INPUT=$(cat)
-TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
-
-case "$TOOL" in
-  Edit|Write|MultiEdit) ;;
-  *) exit 0 ;;
-esac
-
-case "$FILE_PATH" in
-  */packages/design-system/src/components/**/*.tsx) ;;
-  *) exit 0 ;;
-esac
-
-# Skip stories
-case "$FILE_PATH" in
-  *.stories.tsx|*.anatomy.stories.tsx|*.principles.stories.tsx) exit 0 ;;
-esac
-
-# Skip primitive home(SidebarHeader 內部消費 ChromeHeader,但仍有 className signature 引用)
-case "$FILE_PATH" in
-  */ChromeHeader/*|*/header-canonical/*|*/overlay-surface/*) exit 0 ;;
-esac
-
-NEW_CONTENT=$(echo "$INPUT" | jq -r '
-  if .tool_input.new_string then .tool_input.new_string
-  elif .tool_input.content then .tool_input.content
-  else "" end
-')
-
-# Allow escape
-if echo "$NEW_CONTENT" | grep -qE '@chrome-header-handcraft-allow:'; then
-  exit 0
-fi
-
-# Detect handcraft signature: h-[var(--chrome-header-height)] paired with border-b border-divider
-HANDCRAFT_HIT=$(echo "$NEW_CONTENT" | grep -cE 'h-\[var\(--chrome-header-height\)\][^"]*border-b[^"]*border-divider' || true)
-
-if [ "$HANDCRAFT_HIT" -gt "0" ]; then
-  printf '⚠️ CHROME HEADER HANDCRAFT(soft P1,Phase 3 將升 P0):\n' >&2
-  printf '   File: %s\n' "$FILE_PATH" >&2
-  printf '   偵測到自刻 `h-[var(--chrome-header-height)] ... border-b border-divider`\n' >&2
-  printf '\n  SSOT: patterns/header-canonical/header-canonical.spec.md Layer 3\n' >&2
-  printf '  修方向: import { ChromeHeader } from "@/design-system/patterns/header-canonical/chrome-header"\n' >&2
-  printf '          替換 <div className="..."> → <ChromeHeader withTabs? lockDensity?>\n' >&2
-  printf '  Escape: 檔頭加 // @chrome-header-handcraft-allow: <rationale>\n' >&2
-fi
-
-exit 0

package/ds-canonical/hooks/check_header_with_tabs_border.sh

@@ -1,87 +0,0 @@
-#!/bin/bash
-# Header canonical W1 Border ownership enforcement(per header-canonical.spec.md W1):
-#   Header 含 Tabs(`<Tabs>` / `<TabsList>` child)→ 必標 `withTabs` prop 讓 border auto-suppress。
-#
-# PreToolUse(Edit / Write)hook:
-#   讀 post-edit 完整 content(disk + new_string merge)→ count(header) ≥ 1 + count(tabs) ≥ 1
-#   時要求 count(withTabs) ≥ count(header)。違反 = BLOCKER。
-#
-# 2026-05-17 Round 3:用 simple grep counting(per-instance awk 在 macOS bash 環境不穩定)。
-# 在「同 file 一 header 一 withTabs」常規 case 抓得到;edge case(混用 instance)需 audit dim 52
-# batch verify 補。
-#
-# Allow escape:檔頭 `// @header-withtabs-allow:` 整檔豁免。
-
-source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
-
-INPUT=$(cat)
-TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
-
-case "${TOOL:-}" in
-  Edit|Write|MultiEdit) ;;
-  *) exit 0 ;;
-esac
-
-case "${FILE_PATH:-}" in
-  */packages/design-system/src/**/*.tsx) ;;
-  *) exit 0 ;;
-esac
-
-# Skip stories
-case "${FILE_PATH:-}" in
-  *.stories.tsx|*.anatomy.stories.tsx|*.principles.stories.tsx) exit 0 ;;
-esac
-
-NEW_CONTENT=$(echo "$INPUT" | jq -r '
-  if .tool_input.new_string then .tool_input.new_string
-  elif .tool_input.content then .tool_input.content
-  else "" end
-')
-
-DISK_CONTENT=""
-if [ -f "$FILE_PATH" ]; then
-  DISK_CONTENT=$(cat "$FILE_PATH")
-fi
-
-FULL_CONTENT=$(printf '%s\n%s' "${DISK_CONTENT:-}" "${NEW_CONTENT:-}")
-
-if echo "${FULL_CONTENT:-}" | grep -qE '@header-withtabs-allow:'; then
-  exit 0
-fi
-
-# GAP 2 fix(2026-05-18 M34 codify):broaden hardcoded 6-name allowlist 到 generic [A-Z]*Header pattern。
-# 對齊 header-canonical.spec.md「任何 header 含 Tabs」+「未來 Drawer / Card / Table header」前瞻
-HEADERS=$(echo "$FULL_CONTENT" | grep -cE '<[A-Z][a-zA-Z]*Header[[:space:]>]' 2>/dev/null)
-HEADERS=$(echo "${HEADERS:-0}" | head -1)
-TABS=$(echo "$FULL_CONTENT" | grep -cE '<(Tabs|TabsList|TabsTrigger)[[:space:]>]' 2>/dev/null)
-TABS=$(echo "${TABS:-0}" | head -1)
-WITHTABS=$(echo "$FULL_CONTENT" | grep -cE 'withTabs([[:space:]]*=|[[:space:]]*[}>]|[[:space:]]*$)' 2>/dev/null)
-WITHTABS=$(echo "${WITHTABS:-0}" | head -1)
-
-# 若無 header 或無 tabs → 不適用
-if [ "${HEADERS:-0}" -lt 1 ] 2>/dev/null || [ "${TABS:-0}" -lt 1 ] 2>/dev/null; then
-  exit 0
-fi
-
-# 要求 withTabs 出現 ≥ 1 次(寬鬆檢查;per-instance precise 留 Dim 52 batch verify)
-if [ "${WITHTABS:-0}" -lt 1 ] 2>/dev/null; then
-  printf '🚨 HEADER + TABS WITHTABS BLOCKER(header-canonical.spec.md W1):\n' >&2
-  printf '   File: %s\n' "$FILE_PATH" >&2
-  printf '   檔含 %s 個 header JSX + %s 個 Tabs JSX,但 withTabs prop 出現 0 次。\n' "$HEADERS" "$TABS" >&2
-  printf '   Header `border-b` + TabsList `border-b border-border` 會雙線。\n' >&2
-  printf '\n  SSOT: patterns/header-canonical/header-canonical.spec.md W1\n' >&2
-  printf '  修方向: <ChromeHeader withTabs> 或 <SurfaceHeader withTabs>\n' >&2
-  printf '  Escape: 檔頭加 // @header-withtabs-allow: <rationale>\n' >&2
-  exit 2
-fi
-
-# 警告(per-instance 精度不夠 — 若 header > withTabs,某 instance 可能漏):
-if [ "${WITHTABS:-0}" -lt "${HEADERS:-0}" ] 2>/dev/null; then
-  printf '⚠️ HEADER WITHTABS COUNT MISMATCH(W1 soft warn):\n' >&2
-  printf '   File: %s\n' "$FILE_PATH" >&2
-  printf '   header instance %s 個 / withTabs prop %s 個 — 可能有 instance 漏 prop\n' "$HEADERS" "$WITHTABS" >&2
-  printf '   ⚠️ 寬鬆模式 exit 0(不 block);Dim 52 batch verify 補 per-instance 精度\n' >&2
-fi
-
-exit 0

package/ds-canonical/hooks/check_tab_lg_chrome_header_equal.sh

@@ -1,66 +0,0 @@
-#!/bin/bash
-set -uo pipefail
-# Header canonical W3 Token alignment enforcement(per header-canonical.spec.md W3):
-#   --tab-height-lg(uiSize.css)與 --chrome-header-height(globals.css)必像素相等。
-#   兩 token scope 不同(uiSize 是 component-size reset / chrome-header-height 是 app-density)
-#   不該 CSS alias(綁死兩個不同 scope)— 改用 assert: parse 兩檔 md/lg 值對等。
-#
-# PreToolUse(Edit / Write)hook —— 編輯 `packages/design-system/src/tokens/uiSize/uiSize.css` 或
-# `src/globals.css` 時 assert 兩值仍相等。動一方未同步 = BLOCKER。
-#
-# 對齊 M31 codex 比稿 Step 5「保留 duplicated literals + audit hook assert equality」decision。
-
-source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
-
-set -euo pipefail
-
-INPUT=$(cat)
-TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
-
-case "$TOOL" in
-  Edit|Write|MultiEdit) ;;
-  *) exit 0 ;;
-esac
-
-case "$FILE_PATH" in
-  */packages/design-system/src/tokens/uiSize/uiSize.css|*/src/globals.css) ;;
-  *) exit 0 ;;
-esac
-
-PROJECT_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
-UISIZE_CSS="$PROJECT_ROOT/packages/design-system/src/tokens/uiSize/uiSize.css"
-GLOBALS_CSS="$PROJECT_ROOT/src/globals.css"
-
-# Extract value of --tab-height-lg in md context(default :root block)
-TAB_LG_MD=$(grep -oE '\--tab-height-lg:[[:space:]]*[0-9.]+rem' "$UISIZE_CSS" | head -1 | grep -oE '[0-9.]+')
-# Extract --tab-height-lg in lg density override(2nd occurrence)
-TAB_LG_LG=$(grep -oE '\--tab-height-lg:[[:space:]]*[0-9.]+rem' "$UISIZE_CSS" | sed -n '2p' | grep -oE '[0-9.]+')
-
-# Extract --chrome-header-height md(1st occurrence)
-CH_MD=$(grep -oE '\--chrome-header-height:[[:space:]]*[0-9.]+rem' "$GLOBALS_CSS" | head -1 | grep -oE '[0-9.]+')
-# Extract --chrome-header-height lg(2nd occurrence in lg override)
-CH_LG=$(grep -oE '\--chrome-header-height:[[:space:]]*[0-9.]+rem' "$GLOBALS_CSS" | sed -n '2p' | grep -oE '[0-9.]+')
-
-ERRORS=()
-
-if [ "$TAB_LG_MD" != "$CH_MD" ]; then
-  ERRORS+=("md: --tab-height-lg=$TAB_LG_MD rem ≠ --chrome-header-height=$CH_MD rem")
-fi
-
-if [ "$TAB_LG_LG" != "$CH_LG" ]; then
-  ERRORS+=("lg: --tab-height-lg=$TAB_LG_LG rem ≠ --chrome-header-height=$CH_LG rem")
-fi
-
-if [ ${#ERRORS[@]} -gt 0 ]; then
-  printf '🚨 TAB_LG vs CHROME_HEADER_HEIGHT EQUAL BLOCKER(header-canonical.spec.md W3):\n' >&2
-  for E in "${ERRORS[@]}"; do
-    printf '   • %s\n' "$E" >&2
-  done
-  printf '\n  動一方必同步另一方(兩 token 像素相等是「lg tabs 取代 chrome header」SSOT linkage 鐵證)\n' >&2
-  printf '  SSOT: packages/design-system/src/patterns/header-canonical/header-canonical.spec.md W3\n' >&2
-  printf '  修方向: 改 uiSize.css 的 --tab-height-lg OR globals.css 的 --chrome-header-height 讓兩邊相等\n' >&2
-  exit 2
-fi
-
-exit 0

package/ds-canonical/hooks/tests/KNOWN-BROKEN.md

@@ -1,15 +0,0 @@
-# Known Broken Tests(2026-05-17 移出 CI scope)
-
-以下 test 因 hook 演化 / dispatcher merge / wording change 出現 mismatch,
-暫時 rename `.broken` 從 CI run-all.sh 排除。**hook 本身工作正常**(production
-behavior 驗證 OK),只是 test assertion 過時。Future 修各別。
-
-| Test | Symptom | Suspected cause | Priority |
-|---|---|---|---|
-| test_check_story_anatomy.sh | Test 3 dismiss via label Button blocked | hook 行為改但 assertion stale | P2 |
-| test_check_story_category.sh | Test 4 fail | rationale escape parsing 變 | P2 |
-| test_check_story_name_jargon.sh | Test 2/3 ('L2 Selection' / 'canonical' 不再被 flag) | check_story_invariants.sh dispatcher merge 後 regex 變 | P1 |
-| test_stop_governance_drift_check.sh | Test 1/2 fail | hook 改 + (test 已修 set -u 但 fixture 還有 issue) | P2 |
-
-修法 reference:每個 test rerun 看 actual output 是什麼,update assertion grep pattern 對齊。
-完成後 `mv X.broken X` 移回 CI scope。

package/ds-canonical/hooks/tests/test_check_story_category.sh.broken

@@ -1,187 +0,0 @@
-#!/bin/bash
-# Tests for check_story_category.sh
-# Verifies trait-based compliance enforcement
-
-set -u
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# Cluster A merge(2026-05-10):check_story_category.sh fold 進
-# check_story_invariants.sh dispatcher R3。Test 走 dispatcher。
-HOOK="$SCRIPT_DIR/../check_story_invariants.sh"
-[ -x "$HOOK" ] || { echo "FATAL: hook not executable"; exit 1; }
-
-PASS=0; FAIL=0; FAILED=""
-
-setup_proj() {
-  TMP_PROJ=$(mktemp -d)
-  mkdir -p "$TMP_PROJ/src/design-system/components/Foo" "$TMP_PROJ/.claude/hooks"
-  echo 'log_hook_fire() { :; }' > "$TMP_PROJ/.claude/hooks/_log-fire.sh"
-}
-teardown_proj() { rm -rf "$TMP_PROJ"; }
-
-run_hook() {
-  local content="$1"
-  local file_path="$2"
-  local payload
-  payload=$(jq -n \
-    --arg fp "$file_path" \
-    --arg ct "$content" \
-    '{tool_name:"Write", tool_input:{file_path:$fp, content:$ct}}')
-  STDOUT=$(echo "$payload" | bash "$HOOK" 2>&1)
-  EXIT=$?
-}
-
-# ── Test 1: no spec.md → silent pass ─────────────────────────────────────────
-echo "Test 1: no spec.md → silent pass"
-setup_proj
-run_hook "export const Default = {};" "$TMP_PROJ/src/design-system/components/Foo/foo.stories.tsx"
-if [ "$EXIT" = "0" ] && [ -z "$STDOUT" ]; then
-  echo "  PASS  Test 1"; PASS=$((PASS+1))
-else
-  echo "  FAIL  Test 1 (exit=$EXIT, output=${STDOUT:0:100})"
-  FAIL=$((FAIL+1)); FAILED="${FAILED}\n  - Test 1"
-fi
-teardown_proj
-
-# ── Test 2: spec without traits frontmatter → silent pass ────────────────────
-echo "Test 2: spec without traits → silent pass"
-setup_proj
-cat > "$TMP_PROJ/src/design-system/components/Foo/foo.spec.md" <<EOF
-# Foo
-Some content.
-EOF
-run_hook "export const Default = {};" "$TMP_PROJ/src/design-system/components/Foo/foo.stories.tsx"
-if [ "$EXIT" = "0" ] && [ -z "$STDOUT" ]; then
-  echo "  PASS  Test 2"; PASS=$((PASS+1))
-else
-  echo "  FAIL  Test 2 (exit=$EXIT, output=${STDOUT:0:100})"
-  FAIL=$((FAIL+1)); FAILED="${FAILED}\n  - Test 2"
-fi
-teardown_proj
-
-# ── Test 3: hasSizes trait + AllSizes present → pass ─────────────────────────
-echo "Test 3: hasSizes + AllSizes present → pass"
-setup_proj
-cat > "$TMP_PROJ/src/design-system/components/Foo/foo.spec.md" <<EOF
----
-component: Foo
-traits:
-  - hasSizes
-  - hasInteractiveStates
----
-# Foo
-EOF
-run_hook "export const Default = {};
-export const AllSizes = {};
-export const Disabled = {};" "$TMP_PROJ/src/design-system/components/Foo/foo.stories.tsx"
-if [ "$EXIT" = "0" ] && [ -z "$STDOUT" ]; then
-  echo "  PASS  Test 3"; PASS=$((PASS+1))
-else
-  echo "  FAIL  Test 3 (exit=$EXIT, output=${STDOUT:0:200})"
-  FAIL=$((FAIL+1)); FAILED="${FAILED}\n  - Test 3"
-fi
-teardown_proj
-
-# ── Test 4: hasSizes trait + per-size split → BLOCK ──────────────────────────
-echo "Test 4: hasSizes + Small/Medium/Large split → block P0"
-setup_proj
-cat > "$TMP_PROJ/src/design-system/components/Foo/foo.spec.md" <<EOF
----
-traits:
-  - hasSizes
----
-EOF
-run_hook "export const Default = {};
-export const Small = {};
-export const Medium = {};
-export const Large = {};" "$TMP_PROJ/src/design-system/components/Foo/foo.stories.tsx"
-if [ "$EXIT" = "2" ] && echo "$STDOUT" | grep -q "per-size split detected"; then
-  echo "  PASS  Test 4 per-size split blocked"; PASS=$((PASS+1))
-else
-  echo "  FAIL  Test 4 (exit=$EXIT, output=${STDOUT:0:200})"
-  FAIL=$((FAIL+1)); FAILED="${FAILED}\n  - Test 4"
-fi
-teardown_proj
-
-# ── Test 5: isOverlay trait + no OpenSnapshot → BLOCK ────────────────────────
-echo "Test 5: isOverlay + no OpenSnapshot → block P0"
-setup_proj
-cat > "$TMP_PROJ/src/design-system/components/Foo/foo.spec.md" <<EOF
----
-traits:
-  - isOverlay
----
-EOF
-run_hook "export const Default = {};" "$TMP_PROJ/src/design-system/components/Foo/foo.stories.tsx"
-if [ "$EXIT" = "2" ] && echo "$STDOUT" | grep -q "isOverlay"; then
-  echo "  PASS  Test 5 overlay missing OpenSnapshot blocked"; PASS=$((PASS+1))
-else
-  echo "  FAIL  Test 5 (exit=$EXIT, output=${STDOUT:0:200})"
-  FAIL=$((FAIL+1)); FAILED="${FAILED}\n  - Test 5"
-fi
-teardown_proj
-
-# ── Test 6: isOverlay + defaultOpen present → pass ───────────────────────────
-echo "Test 6: isOverlay + defaultOpen=true present → pass"
-setup_proj
-cat > "$TMP_PROJ/src/design-system/components/Foo/foo.spec.md" <<EOF
----
-traits:
-  - isOverlay
----
-EOF
-run_hook "export const Default = { args: { defaultOpen: true } };" "$TMP_PROJ/src/design-system/components/Foo/foo.stories.tsx"
-if [ "$EXIT" = "0" ] && [ -z "$STDOUT" ]; then
-  echo "  PASS  Test 6 defaultOpen ✓ pass"; PASS=$((PASS+1))
-else
-  echo "  FAIL  Test 6 (exit=$EXIT, output=${STDOUT:0:200})"
-  FAIL=$((FAIL+1)); FAILED="${FAILED}\n  - Test 6"
-fi
-teardown_proj
-
-# ── Test 7: rationale escape allowlist ──────────────────────────────────────
-echo "Test 7: @story-trait-rationale escape → pass"
-setup_proj
-cat > "$TMP_PROJ/src/design-system/components/Foo/foo.spec.md" <<EOF
----
-traits:
-  - hasSizes
----
-EOF
-run_hook "// @story-trait-rationale: experimental design exploration
-export const Small = {};" "$TMP_PROJ/src/design-system/components/Foo/foo.stories.tsx"
-if [ "$EXIT" = "0" ] && [ -z "$STDOUT" ]; then
-  echo "  PASS  Test 7 rationale escape works"; PASS=$((PASS+1))
-else
-  echo "  FAIL  Test 7 (exit=$EXIT, output=${STDOUT:0:200})"
-  FAIL=$((FAIL+1)); FAILED="${FAILED}\n  - Test 7"
-fi
-teardown_proj
-
-# ── Test 8: anatomy/principles stories skipped ──────────────────────────────
-echo "Test 8: .anatomy.stories.tsx skipped(not subject to trait typology)"
-setup_proj
-cat > "$TMP_PROJ/src/design-system/components/Foo/foo.spec.md" <<EOF
----
-traits:
-  - hasSizes
----
-EOF
-run_hook "export const Small = {};" "$TMP_PROJ/src/design-system/components/Foo/foo.anatomy.stories.tsx"
-if [ "$EXIT" = "0" ] && [ -z "$STDOUT" ]; then
-  echo "  PASS  Test 8 anatomy stories exempted"; PASS=$((PASS+1))
-else
-  echo "  FAIL  Test 8 (exit=$EXIT, output=${STDOUT:0:200})"
-  FAIL=$((FAIL+1)); FAILED="${FAILED}\n  - Test 8"
-fi
-teardown_proj
-
-# ── Summary ─────────────────────────────────────────────────────────────────
-echo ""
-echo "════════════════════════════════════════"
-echo "  Results: $PASS PASS, $FAIL FAIL"
-echo "════════════════════════════════════════"
-if [ "$FAIL" -gt 0 ]; then
-  printf "Failed:%b\n" "$FAILED"; exit 1
-fi
-exit 0

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

@@ -1,74 +0,0 @@
-# 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/skills/design-system-audit/references/spec-template.md

@@ -1,66 +0,0 @@
-# Spec.md 兩段式 chapter template(2026-05-17 codify,codex Q8 verdict (c) 兩段式)
-
-**對齊**:Polaris 7-section component spec + Carbon Component Spec template + Material 3 component anatomy。比全寫死更適合複雜元件,比完全自由更能 audit。
-
-## 必填 7 維(順序固定,hook 攔缺失或嚴重漂移)
-
-```markdown
-# <ComponentName> 設計原則
-
-## 1. Layout Family / scope
-- Layout Family: 1 / 2 / 3 / 4(或明示「self-contained / composite」+ rationale)
-- Implementation base: 基於 Radix X / 基於 cmdk / native / 自建 + 理由
-- Token / pattern 消費清單(SSOT 消費 canonical)
-
-## 2. 何時用
-- 真實業務情境(Jira / Stripe / Notion 可辨識)
-- 預設使用案例(非邊緣 case)
-
-## 3. 何時不用
-- 近親元件分界(vs SiblingX / SiblingY)
-- 反向 trigger:這些情境改用 Z
-
-## 4. 近親分界(decision tree if multiple sibling)
-- vs A:differentiate by axis-1
-- vs B:differentiate by axis-2
-
-## 5. 尺寸 / variant / state canonical
-- Size:xs / sm / md / lg(field-height / table-row 等 token 對應)
-- Variant:列 cva 預設值 + 為什麼
-- State:default / hover / focus / active / disabled / loading / error 各自視覺定義 + state machine 疊加組合(M5)
-
-## 6. 邊界案例 + a11y
-- Empty / loading / error / dark mode / density / icon-only 各自處理
-- ARIA roles + keyboard map(互動元件強制;純視覺 indicator 豁免明寫)
-- Scope defaults 豁免清單(若適用,cite `spec-rules.md`)
-
-## 7. 相關 SSOT links / reciprocal pointers
-- 上游 pattern / token / primitive 引用(`xxx.spec.md「HEADING」`)
-- 下游 consumer 元件 list
-- Reciprocal check:被本 spec link 的對方有沒回連?
-```
-
-## 自由 rationale(後段)— 不限格式
-
-每 component spec 可在 7 維後加任意「為什麼」/ historical anchor / world-class benchmark cite / RFC link / 邊界討論 — hook **不**攔此段。
-
-範例:
-- Button.spec.md 加「Pill Layout 為什麼自建非 Family 3」rationale
-- Field.spec.md 加「為什麼 block primitive 不自己變高」decision tree
-- DataTable.spec.md 加 Phase 7 RFC archive
-
-## Hook 機械強制
-
-**Hook**:`check_spec_chapter_canonical.sh`(待 ship)— PreToolUse Write/Edit `*.spec.md` 檢:
-- 必填 7 維 heading 全在(`## 1. Layout Family` 等)
-- 順序對(1 < 2 < 3 ... < 7)
-- 缺任一 heading → P0 BLOCKER(可 escape:檔頭 `// @spec-template-exempt: <reason>` 例外,用 ≥ 3 家 world-class DS 對照證該 component 不適用標準 template)
-
-**Soft warn**:7 維外的 chapter 結構不限。但若 audit Dim 15 偵測跨 spec 命名漂移(如「為什麼 block」vs「為什麼不變高」相同概念兩寫法)→ flag 統一。
-
-## 歷史錨點
-
-- 2026-05-17 codex Q8 verdict:Button vs Field 章節 order 不一(Button 有「何時不用」/ Field 有「為什麼 block」rationale-heavy)→ 該兩段式
-- Polaris template:https://github.com/Shopify/polaris/blob/main/polaris-react/.template/component.mdx
-- Carbon Component Spec:https://carbondesignsystem.com/contributing/component-checklist/
-- Material 3 anatomy:https://m3.material.io/components/<component>/specs