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

package/ds-canonical/hooks/lib/_cva_default_sync.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# PostToolUse hook for Edit/Write on component .tsx:
+# When a change touches cva() defaultVariants, grep for 3-way consistency across
+# spec.md + docblock + anatomy.stories.tsx and warn if any disagree on the default.
+#
+# Prevents the SegmentedControl bug class: cva says 'md', spec/docblock/anatomy say
+# 'sm ★default' — silently drifts until audit catches it.
+#
+# Exit: 0 + stdout JSON additionalContext (non-blocking warning)
+
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+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
+
+# Only target component .tsx files (not stories, not specs)
+if ! echo "$FILE_PATH" | grep -qE 'packages/design-system/src/components/[^/]+/[^/]+\.tsx$'; then
+  exit 0
+fi
+echo "$FILE_PATH" | grep -qE '\.stories\.tsx$' && exit 0
+
+# Only fire if the file actually contains defaultVariants (post-edit state)
+[ -f "$FILE_PATH" ] || exit 0
+grep -q "defaultVariants" "$FILE_PATH" || exit 0
+
+# Diff-aware: only fire if this edit actually touched cva / defaultVariants content.
+# Extract old_string + new_string (Edit / MultiEdit) or content (Write) — if none
+# mention cva(, defaultVariants, or variants: , skip noise.
+DIFF_TEXT=$(echo "$INPUT" | jq -r '
+  (.tool_input.old_string // "") + "\n" +
+  (.tool_input.new_string // "") + "\n" +
+  (.tool_input.content    // "") + "\n" +
+  ([.tool_input.edits[]? | (.old_string + "\n" + .new_string + "\n")] | join(""))
+' 2>/dev/null || echo "")
+if [ -n "$DIFF_TEXT" ] && ! echo "$DIFF_TEXT" | grep -qE 'cva\(|defaultVariants|variants:[[:space:]]*\{'; then
+  exit 0
+fi
+
+COMP_DIR=$(dirname "$FILE_PATH")
+COMP_NAME=$(basename "$COMP_DIR")
+SPEC_FILE="$COMP_DIR/$(basename "$FILE_PATH" .tsx).spec.md"
+ANATOMY_FILE="$COMP_DIR/$(basename "$FILE_PATH" .tsx).anatomy.stories.tsx"
+
+# Extract default values from each source (best-effort grep; signal not proof)
+CVA_DEFAULTS=$(grep -A5 "defaultVariants" "$FILE_PATH" 2>/dev/null | grep -E "(size|variant|state):" | head -3 | tr -d ' "' | sed 's/,$//' || echo "")
+SPEC_DEFAULTS=""
+[ -f "$SPEC_FILE" ] && SPEC_DEFAULTS=$(grep -E "★|預設|default" "$SPEC_FILE" 2>/dev/null | head -5 || echo "")
+ANATOMY_DEFAULTS=""
+[ -f "$ANATOMY_FILE" ] && ANATOMY_DEFAULTS=$(grep -E "★|default|defaultVariants" "$ANATOMY_FILE" 2>/dev/null | head -5 || echo "")
+
+WARNING="⚠️ $COMP_NAME cva/defaultVariants touched — verify 3-way sync: tsx cva ↔ spec.md default markers ↔ anatomy SIZE_SPECS. Ref: SegmentedControl drift bug. Grep \"★|預設|default\" in $COMP_DIR/."
+
+# Escape for JSON via jq
+ESCAPED=$(printf '%s' "$WARNING" | jq -Rs .)
+
+cat <<EOJSON
+{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":$ESCAPED}}
+EOJSON
+
+exit 0

package/ds-canonical/hooks/lib/_governance_coverage_check.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# _governance_coverage_check.sh — PostToolUse helper:
+# 偵測 governance file edit(meta-patterns / spec.md frontmatter / hook / SKILL / rules)
+# → 跑 audit-preflight.mjs --check 比 baseline 是否新增 coverage gap
+# → 有 gap → stderr inject 警告:user 必補 audit dim or 撤原則
+#
+# 對應 SSOT:
+# - memory/feedback_audit_preflight_全盤查.md(2026-05-15 codified)
+# - design-system-audit/SKILL.md Phase 0.5 invariant
+# - user 原話「確保現在和未來都會自動涵蓋,當有新的準則就務必更新設計系統進階稽核的內容」
+#
+# 由 post_edit_dispatcher.sh orchestrate,non-standalone hook(不算 hook count)
+
+source "$(dirname "$0")/../_log-fire.sh" 2>/dev/null && log_hook_fire
+
+FILE_PATH=$(jq -r '.tool_input.file_path // empty')
+[ -z "$FILE_PATH" ] && exit 0
+
+# Governance file scope:M-rule / spec.md frontmatter / hook check / SKILL / rules
+GOV_RE='(meta-patterns\.md|/spec\.md$|check_.*\.sh$|/SKILL\.md$|\.claude/rules/.*\.md$|CLAUDE\.md$)'
+echo "$FILE_PATH" | grep -qE "$GOV_RE" || exit 0
+
+# Pre-check audit-preflight 存在
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PREFLIGHT="$PROJECT_DIR/scripts/audit-preflight.mjs"
+[ -f "$PREFLIGHT" ] || exit 0
+
+# 跑 preflight check mode(silent;exit 1 if gap)
+PREFLIGHT_OUT=$(cd "$PROJECT_DIR" && node scripts/audit-preflight.mjs --check 2>&1)
+PREFLIGHT_EXIT=$?
+
+if [ "$PREFLIGHT_EXIT" -eq 1 ]; then
+  TODAY=$(date +%Y-%m-%d)
+  LOG_FILE="$PROJECT_DIR/.claude/logs/audit-preflight-${TODAY}.json"
+  GAP_COUNT=0
+  GAP_SAMPLE=""
+  if [ -f "$LOG_FILE" ]; then
+    GAP_COUNT=$(jq -r '.coverageGaps // 0' "$LOG_FILE" 2>/dev/null || echo 0)
+    GAP_SAMPLE=$(jq -r '.gaps[:3] | .[]' "$LOG_FILE" 2>/dev/null | head -3 | tr '\n' ',' | sed 's/,$//')
+  fi
+
+  ADDITIONAL_CONTEXT="⚠️ Governance coverage gap(audit-preflight): ${FILE_PATH##*/} edit 後 ${GAP_COUNT} 原則無 audit dim cover(包含: ${GAP_SAMPLE})。若新加入的原則 → 必補 audit dim 進 design-system-audit/SKILL.md。若既有 false-positive(heuristic 不準)→ sub-agent semantic verify。SSOT: memory/feedback_audit_preflight_全盤查.md"
+
+  jq -n --arg ctx "$ADDITIONAL_CONTEXT" '{
+    hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: $ctx }
+  }'
+fi
+
+exit 0

package/ds-canonical/hooks/lib/_hardcoded_strings.sh

@@ -0,0 +1,163 @@
+#!/bin/bash
+# PostToolUse hook: flag hardcoded user-facing strings in DS component tsx
+# (CJK ≥ 3 chars or English ≥ 8 chars that look like sentence-case labels).
+#
+# Rationale(CLAUDE.md # Internationalization / 24-checklist #13 gap):
+#   DS primitive 的文案若 hardcode,consumer 換語言 / A/B test label 時要 forkDS。
+#   正確路線:prop 接收 + `loadingText` / `emptyText` 等 slot,或走 i18n 層。
+#
+# Scope:
+#   - ONLY packages/design-system/src/components/**/*.tsx(primitives)
+#   - ONLY patterns/ 如果出現 user-facing string
+#   - SKIP stories.tsx(stories 用真實 Jira/Stripe 範例 = 刻意)
+#   - SKIP spec.md / anatomy
+#
+# Whitelist(不 flag):
+#   - 註解 // /* */
+#   - `aria-label` / `title` 等 a11y prop 若無對應 prop 可接收 → 仍 flag(warn 改成 prop)
+#   - 標示 `// i18n-allow: {rationale}` 該行白名單
+#
+# WARN-style, 不 block.
+
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+source "$(dirname "$0")/../_log-fire.sh" 2>/dev/null && log_hook_fire
+
+FILE_PATH=$(jq -r '.tool_input.file_path // empty')
+
+# Scope: only design-system components/patterns .tsx
+if ! echo "$FILE_PATH" | grep -qE 'packages/design-system/src/(components|patterns)/.*\.tsx$'; then
+  exit 0
+fi
+if echo "$FILE_PATH" | grep -qE '\.(stories|principles|anatomy\.stories)\.tsx$'; then
+  exit 0
+fi
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Detect hardcoded user-facing CJK / English labels via perl oneliner
+# (macOS-portable: perl is always present; grep -P / pcregrep / rg 不一定有)
+#
+# Perl logic(per line):
+#  1. 跳過 `// ...` 單行註解(但不影響行內其他 content 判斷 — 我們直接跳整行簡化)
+#  2. 跳過 `/* ... */` 一行註解
+#  3. 跳過該行含 `i18n-allow` 白名單標記
+#  4. 對剩餘行偵測 JSX 文字節點 `>...<` 或字串字面量 `"..."` / `'...'`
+#     內含 ≥ 3 個 CJK 字元(\p{Han} / \p{Hiragana} / \p{Katakana} / \p{Hangul})
+#  5. English:narrow detection,僅當 JSX 文字節點或屬性值含 ≥ 2 個 sentence-case 詞
+#
+# Output: "line_num:matched_snippet"(每 file 最多 5 條)
+
+VIOLATIONS=""
+
+CJK_HITS=$(perl -CSD -ne '
+  BEGIN {
+    our $jsdoc = 0; our $console_open = 0; our $jsx_comment = 0;
+    our $allow_pending = 0; our $allow_depth = 0;
+  }
+  # ── block-level i18n-allow:上一行有 `// i18n-allow-block` 或
+  # `// i18n-allow`(單獨 comment 行)→ 標記下一個 `{...}` 區塊整個 skip ──
+  if (m{^\s*(?://|/\*+)\s*i18n-allow(-block)?\b}) { $allow_pending = 1; next }
+  if ($allow_pending && m{[\{\[]}) {
+    $allow_pending = 0;
+    my $opens = () = /[\{\[]/g; my $closes = () = /[\}\]]/g;
+    $allow_depth = $opens - $closes;
+    next if $allow_depth > 0;  # only enter block if net positive opens
+  }
+  if ($allow_depth > 0) {
+    my $opens = () = /[\{\[]/g; my $closes = () = /[\}\]]/g;
+    $allow_depth += $opens - $closes;
+    next;
+  }
+  # ── JSDoc block(多行 /** ... */)── stateful ──
+  if (!$jsdoc && m{/\*\*}) { $jsdoc = 1 }
+  if ($jsdoc) {
+    if (m{\*/}) { $jsdoc = 0 }
+    next;
+  }
+  # ── JSX block comment(多行 {/* ... */})── stateful ──
+  if (!$jsx_comment && m{\{/\*}) { $jsx_comment = 1 }
+  if ($jsx_comment) {
+    if (m{\*/\s*\}}) { $jsx_comment = 0 }
+    next;
+  }
+  # ── Line-level 註解 skip ──────────────
+  next if m{^\s*//};                    # single-line comment
+  next if m{^\s*/\*.*\*/\s*$};          # single-line block comment
+  next if m{^\s*\*};                    # stray JSDoc line
+  next if m{i18n-allow};
+  # ── strip trailing `//` comments(naïve:不處理 URL 等 string 內 `//`)─
+  # Fix FP:`code() // CJK comment` 被誤匹配 comment 內的 CJK
+  # 注意:不能用 `[^\x27"]` 限制,comment 內可能有 `"` 被 CJK 夾住
+  # 簡單策略 — `//` 後到 EOL 全 strip(string 內的 `//` 罕見 → 可接受 FP trade)
+  $_ =~ s{\s+//.*$}{};
+  # ── dev-only console.* / throw new Error() multi-line — stateful ─
+  # 這些是 DS internal dev / developer-facing diagnostics,consumer 看不到
+  if (!$console_open && m{(console\.(warn|error|log|info|debug)|throw\s+new\s+(Error|TypeError|RangeError))\s*\(}) {
+    $console_open = 1;
+    if (m{\)\s*[;,]?\s*$}) { $console_open = 0 }
+    next;
+  }
+  if ($console_open) {
+    if (m{\)\s*[;,]?\s*$}) { $console_open = 0 }
+    next;
+  }
+  # ── DS-internal metadata keys(designer-facing,非 end-user-facing)──
+  # 典型:buttonMeta / componentMeta / story args 的 `purpose:` / `description:` / `rationale:` / `when:` / `dont:` / `note:` / `text:`(stories)
+  # 匹配「行內任何位置出現 `{metadata_key}: "..."`」:如 `primary: { purpose: "..." }` 的 purpose
+  next if m{\b(purpose|description|rationale|when|dont|note|tip|detail|explanation|summary)\s*:\s*[\x27"]};
+  # ── JSX text node or string literal with CJK ≥ 3 ─
+  if (m{([>"\047])([^<"\047]*?[\p{Han}\p{Hiragana}\p{Katakana}\p{Hangul}]{3,}[^<"\047]*?)([<"\047])}) {
+    my $snippet = $2;
+    $snippet =~ s/^\s+|\s+$//g;
+    $snippet = substr($snippet, 0, 80) . "…" if length($snippet) > 80;
+    print "$.:$snippet\n";
+  }
+' "$FILE_PATH" 2>/dev/null | head -5)
+
+if [ -n "$CJK_HITS" ]; then
+  VIOLATIONS="${VIOLATIONS}\n⚠️ Hardcoded CJK strings in DS primitive(consumer 換語言要 fork 元件):\n${CJK_HITS}\n  修法:改成 prop 接收(e.g. \`loadingText / emptyText / label\` slot)。若確實 DS 層預設(如 internal debug),在該行末加 \`// i18n-allow: {rationale}\` 白名單。"
+fi
+
+# English sentence-case labels — narrow detection
+ENG_HITS=$(perl -CSD -ne '
+  BEGIN { our $allow_pending = 0; our $allow_depth = 0; }
+  # ── block-level i18n-allow(同 CJK block)─
+  if (m{^\s*(?://|/\*+)\s*i18n-allow(-block)?\b}) { $allow_pending = 1; next }
+  if ($allow_pending && m{[\{\[]}) {
+    $allow_pending = 0;
+    my $opens = () = /[\{\[]/g; my $closes = () = /[\}\]]/g;
+    $allow_depth = $opens - $closes;
+    next if $allow_depth > 0;  # only enter block if net positive opens
+  }
+  if ($allow_depth > 0) {
+    my $opens = () = /[\{\[]/g; my $closes = () = /[\}\]]/g;
+    $allow_depth += $opens - $closes;
+    next;
+  }
+  # ── 註解 skip(line-level)─────────────────────
+  next if m{^\s*//};
+  next if m{^\s*/\*.*\*/\s*$};
+  next if m{^\s*\*};
+  next if m{^\s*/\*\*?\s*$};
+  next if m{i18n-allow};
+  next if m{console\.(warn|error|log|info|debug)\s*\(};
+  next if m{className=|aria-label=|data-\w+=|href=|key=};
+  if (m{>([A-Z][a-z]+ [a-z]+(?: [a-z]+)+)<} || m{[\"\047]([A-Z][a-z]+ [a-z]+(?: [a-z]+)+)[\"\047]}) {
+    print "$.:$1\n";
+  }
+' "$FILE_PATH" 2>/dev/null | head -3)
+
+if [ -n "$ENG_HITS" ]; then
+  VIOLATIONS="${VIOLATIONS}\n⚠️ Hardcoded English sentence-case labels:\n${ENG_HITS}\n  若是 user-facing label,改 prop 接收;若是 internal,加 \`// i18n-allow\` 白名單。"
+fi
+
+# ── Emit warning if any violation ────────────────────────────────────────────
+if [ -n "$VIOLATIONS" ]; then
+  ESCAPED=$(printf "%b" "$VIOLATIONS" | jq -Rs .)
+  cat <<EOJSON
+{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"i18n hygiene 檢查(24-checklist #13 gap):${ESCAPED}\n\nDS primitive 應 prop-driven,hardcoded 文案讓 consumer 換語言時要 fork。"}}
+EOJSON
+fi
+
+exit 0

package/ds-canonical/hooks/lib/_layout_space_canonical.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# PostToolUse hook: detect layoutSpace canonical violations in stories / showcase tsx.
+#
+# Catches typical block-vs-inline gap mistakes per layoutSpace.spec.md:
+# 1. Hardcoded mt-N / mb-N / pt-N / pb-N (4/6/8) instead of tokens — should use --layout-space-*
+# 2. gap-tight on a flex column form with all-inline elements (should be loose per rule 3)
+# 3. block element (DataTable / Textarea / Editor) followed by mt-tight on next sibling
+#    (block → 容器底 / chrome band 應該 loose,規則 4)
+#
+# Scope: design-system stories.tsx + app/ + explorations/ (consumer-side layout).
+# WARN-style (not BLOCK): emit additionalContext so AI reads and can fix.
+
+# Per-hook fire logging
+source "$(dirname "$0")/../_log-fire.sh" 2>/dev/null && log_hook_fire
+
+FILE_PATH=$(jq -r '.tool_input.file_path // empty')
+
+# Scope: only stories.tsx + app code (not core component .tsx — they own their own internal padding)
+if ! echo "$FILE_PATH" | grep -qE '(\.stories\.tsx$|src/app/.*\.tsx$|src/explorations/.*\.tsx$)'; then
+  exit 0
+fi
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+VIOLATIONS=""
+
+# ── Check 1: hardcoded mt-N / mb-N adjacent to <DataTable / Textarea / Editor> ──
+# Block elements need loose bottom/top gap; tight is rule violation.
+# Pattern: <DataTable...>...</...> followed by <Alert / BulkActionBar / div with mt-tight>
+BLOCK_TIGHT_HITS=$(grep -nE "(mt|mb)-\[var\(--layout-space-tight\)\]" "$FILE_PATH" 2>/dev/null | head -5)
+if [ -n "$BLOCK_TIGHT_HITS" ]; then
+  # Only flag if file ALSO contains block elements (DataTable / Textarea / Editor / CodeBlock)
+  if grep -qE '<(DataTable|Textarea|Editor|CodeBlock)' "$FILE_PATH" 2>/dev/null; then
+    VIOLATIONS="${VIOLATIONS}\n⚠️ tight margin near block element(可能違反規則 4:block → 容器底 / chrome band = loose):\n${BLOCK_TIGHT_HITS}\n  → 確認該位置:block 旁邊應 loose;只有 block ↔ block 緊鄰且都在 form 內才用 tight。"
+  fi
+fi
+
+# ── Check 3: gap-tight on flex column form with all-inline (likely violation)──
+# 規則 3:inline ↔ inline = loose,不是 tight
+GAP_TIGHT_FLEX=$(grep -nE 'flex-col\s+gap-\[var\(--layout-space-tight\)\]' "$FILE_PATH" 2>/dev/null | head -3)
+if [ -n "$GAP_TIGHT_FLEX" ]; then
+  VIOLATIONS="${VIOLATIONS}\n⚠️ flex-col gap-tight(若內容全是 inline 元件就違反規則 3:inline ↔ inline 應 loose):\n${GAP_TIGHT_FLEX}\n  → 確認 form 內含 block(Table/Textarea/Editor)?有 → 保留 tight 合規;全 inline → 改 loose。"
+fi
+
+if [ -n "$VIOLATIONS" ]; then
+  ADDITIONAL_CONTEXT=$(printf '⚠️ layoutSpace canonical 提醒(tokens/layoutSpace/layoutSpace.spec.md):%b' "$VIOLATIONS")
+  jq -n --arg ctx "$ADDITIONAL_CONTEXT" '{
+    hookSpecificOutput: {
+      hookEventName: "PostToolUse",
+      additionalContext: $ctx
+    }
+  }'
+fi
+
+exit 0

package/ds-canonical/hooks/lib/_overlay_handcraft.sh

@@ -0,0 +1,141 @@
+#!/bin/bash
+# PostToolUse hook: detect hand-crafted overlay chrome violating mindset #2.
+#
+# Catches: <div className="...px-[var(--layout-space-loose)]...border-(b|t) border-divider">
+# in stories.tsx / DataTable helper.tsx / app code — pattern means consumer self-rendered
+# overlay header/footer chrome instead of consuming SurfaceHeader / SurfaceBody / SurfaceFooter
+# (or PopoverHeader / DialogHeader / SheetHeader).
+#
+# Why block: canonical primitives bundle padding + border + close X (Popover) + autofocus +
+# typography (PopoverTitle text-body font-medium). Self-rendering bypasses these = mindset #2
+# violation + silently breaks alignment / close X 一致性。
+#
+# 對齊 patterns/overlay-surface/overlay-surface.spec.md「Consumer rule」+
+# components/Popover/popover.tsx:72「所有 PopoverHeader 一律附右上 X」canonical。
+#
+# Escape hatch:add `// overlay-handcraft-allow: <reason>` on prev/same line for intentional cases
+# (e.g. non-overlay panel that just borrows the layout-space token).
+#
+# WARN-style (additionalContext) — AI reads + fixes next iteration.
+
+# Per-hook fire logging
+source "$(dirname "$0")/../_log-fire.sh" 2>/dev/null && log_hook_fire
+
+FILE_PATH=$(jq -r '.tool_input.file_path // empty')
+
+# Scope: tsx files (stories, components, patterns, app, explorations)
+if ! echo "$FILE_PATH" | grep -qE '\.tsx$'; then
+  exit 0
+fi
+# Skip spec.md / anatomy stories (different context)
+if echo "$FILE_PATH" | grep -qE '(\.spec\.md$|\.anatomy\.stories\.tsx$|\.principles\.stories\.tsx$)'; then
+  exit 0
+fi
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Pattern: <div className="...px-[var(--layout-space-loose)]...border-(b|t) border-divider...">
+PATTERN='<div className="[^"]*px-\[var\(--layout-space-loose\)\][^"]*border-(b|t) border-divider'
+HITS=$(grep -nE "$PATTERN" "$FILE_PATH" 2>/dev/null | head -5)
+
+if [ -n "$HITS" ]; then
+  # filter out lines with allowlist comment
+  FILTERED=""
+  while IFS= read -r line; do
+    line_num=$(echo "$line" | cut -d: -f1)
+    [ -z "$line_num" ] && continue
+    # check current line + previous line for allowlist
+    prev_line=$(sed -n "$((line_num-1))p" "$FILE_PATH" 2>/dev/null)
+    cur_line=$(sed -n "${line_num}p" "$FILE_PATH" 2>/dev/null)
+    if echo "$prev_line $cur_line" | grep -q 'overlay-handcraft-allow:'; then
+      continue
+    fi
+    FILTERED="${FILTERED}${line}\n"
+  done <<< "$HITS"
+
+  if [ -n "$FILTERED" ]; then
+    VIOLATIONS="${VIOLATIONS}\n⚠️ Hand-crafted overlay chrome detected(自刻 overlay 結構違 mindset #2):\n${FILTERED}\n  → 改用 primitive:\n    Popover content → PopoverHeader / PopoverBody / PopoverFooter / PopoverTitle\n    Dialog content → DialogHeader / DialogBody / DialogFooter / DialogTitle\n    Generic overlay panel → SurfaceHeader / SurfaceBody / SurfaceFooter (overlay-surface)\n  Why:canonical 自帶 padding token + border + close X(Popover)+ autofocus + title typography。\n  Escape hatch:加 \`// overlay-handcraft-allow: <reason>\` 在同/前行。"
+  fi
+fi
+
+# ── Check 2.5: Raw row handcraft (px-loose + py + rounded-md + hover:bg-neutral-hover) ──
+# Pattern:`<div className="...flex...gap-2 px-loose py-1.5 rounded-md hover:bg-neutral-hover">`
+# = 自刻 MenuItem-like row 違反 mindset #2(MenuItem primitive 自帶這些 + size canonical + a11y)
+ROW_PATTERN='<div className="[^"]*flex[^"]*gap-[12][^"]*px-\[var\(--layout-space-loose\)\][^"]*hover:bg-neutral-hover[^"]*rounded'
+ROW_HITS=$(grep -nE "$ROW_PATTERN" "$FILE_PATH" 2>/dev/null | head -3)
+if [ -n "$ROW_HITS" ] && ! grep -qE 'menu-item-handcraft-allow:' "$FILE_PATH" 2>/dev/null; then
+  VIOLATIONS="${VIOLATIONS}\n⚠️ 自刻 row(MenuItem-like)違反 mindset #2:\n${ROW_HITS}\n  → 改用 <MenuItem startIcon={...} endContent={...} disabled={...}>label</MenuItem>\n  Why:MenuItem 自帶 SelectionItem py 公式 + size canonical + a11y(role=option, aria-disabled, aria-selected) + cursor-not-allowed disabled。\n  Escape hatch:加 \`// menu-item-handcraft-allow: <reason>\` 在檔頭。"
+fi
+
+# ── Check 2: Raw <Checkbox> count > 1 not in <CheckboxGroup> ──
+# 同 root cause(自刻 SelectionItem 包 Checkbox 而非消費 CheckboxGroup primitive)。
+# 對齊 checkbox.spec.md「群組模式(CheckboxGroup)」canonical line 225:
+#   多選 Checkbox 必包 <CheckboxGroup>(zero-gap canonical + Context 隔離 + a11y group)。
+CB_COUNT=$(grep -c '<Checkbox\b' "$FILE_PATH" 2>/dev/null | head -1 || echo 0)
+CBG_COUNT=$(grep -c '<CheckboxGroup\b' "$FILE_PATH" 2>/dev/null | head -1 || echo 0)
+CB_COUNT=${CB_COUNT:-0}
+CBG_COUNT=${CBG_COUNT:-0}
+if [ "$CB_COUNT" -ge 2 ] && [ "$CBG_COUNT" -eq 0 ]; then
+  CB_HITS=$(grep -nE '<Checkbox\b' "$FILE_PATH" 2>/dev/null | head -3)
+  # allowlist: same-line or prev-line has // checkbox-group-allow:
+  if ! grep -qE 'checkbox-group-allow:' "$FILE_PATH" 2>/dev/null; then
+    VIOLATIONS="${VIOLATIONS}\n⚠️ 多個 raw <Checkbox> 未包 <CheckboxGroup>(${CB_COUNT} hits)— 違反 checkbox.spec.md 群組 canonical:\n${CB_HITS}\n  → 改用 <CheckboxGroup><Checkbox label=\"...\" />...</CheckboxGroup>\n  Why:CheckboxGroup 自帶 zero-gap canonical(SelectionItem py 公式)+ Context 隔離 fieldCtx + a11y group;raw 自刻 wrapper 違 mindset #2。\n  Escape hatch:加 \`// checkbox-group-allow: <reason>\` 在檔頭。"
+  fi
+fi
+
+# ── Check 5: Same-row consistency 違反(同 row 混 ItemInlineActionButton + Button iconOnly)──
+# 對齊 inline-action.spec.md L152「Same-row consistency rule:同 action row 所有 icon action 必同一類」。
+# Pattern:同檔出現 <ItemInlineActionButton 與 <Button.*iconOnly,且非 menu primitive impl(menu 內 Button 為合法 chrome)。
+HAS_INLINE=$(grep -c '<ItemInlineActionButton' "$FILE_PATH" 2>/dev/null | head -1)
+HAS_BTN_ICON=$(grep -cE '<Button[^>]*iconOnly' "$FILE_PATH" 2>/dev/null | head -1)
+HAS_INLINE=${HAS_INLINE:-0}
+HAS_BTN_ICON=${HAS_BTN_ICON:-0}
+IS_MENU_PRIMITIVE2=$(echo "$FILE_PATH" | grep -cE '(DropdownMenu|SelectMenu|Combobox|Menu)/.*\.tsx$' | head -1)
+IS_MENU_PRIMITIVE2=${IS_MENU_PRIMITIVE2:-0}
+if [ "$HAS_INLINE" -ge 1 ] && [ "$HAS_BTN_ICON" -ge 1 ] && [ "$IS_MENU_PRIMITIVE2" -eq 0 ]; then
+  if ! grep -qE 'same-row-mixed-allow:' "$FILE_PATH" 2>/dev/null; then
+    VIOLATIONS="${VIOLATIONS}\n⚠️ 同檔混用 <ItemInlineActionButton>(${HAS_INLINE}) + <Button.*iconOnly>(${HAS_BTN_ICON}):\n  → 違反 inline-action.spec.md L152 Same-row consistency rule(同 row icon action 必同一類)。\n  → Box size 不一致(InlineAction 16+18 vs Button text sm 28)會 gap 斷裂。\n  → 修法:row 內 icon action 全 ItemInlineActionButton(對齊 size=md / 16+18 hover bg)。\n  Escape hatch:加 \`// same-row-mixed-allow: <reason>\` 在檔頭(若 chrome corner action group 跟 row 不同 row,可分開)。"
+  fi
+fi
+
+# ── Check 4: Panel-style Popover + MenuItem co-occur(2026-04-29) ──
+# Pattern:同檔出現 <PopoverHeader> 且 <MenuItem>(不是 DropdownMenu / SelectMenu primitive 自身)
+# → panel-style popover 不該硬塞 menu specialization。MenuItem 預設 `px-3` 不對齊 panel chrome
+# `loose`,且 startIcon 色彩無 override → 該用視覺 primitive(ItemPrefix/ItemLabel/ItemSuffix)自組。
+HAS_POP_HEADER=$(grep -c '<PopoverHeader' "$FILE_PATH" 2>/dev/null | head -1)
+HAS_MENU_ITEM=$(grep -c '<MenuItem\b' "$FILE_PATH" 2>/dev/null | head -1)
+HAS_POP_HEADER=${HAS_POP_HEADER:-0}
+HAS_MENU_ITEM=${HAS_MENU_ITEM:-0}
+# Skip:DropdownMenu/SelectMenu primitive impl 本身(他們 import MenuItem 是合法 menu-style)
+IS_MENU_PRIMITIVE=$(echo "$FILE_PATH" | grep -cE '(DropdownMenu|SelectMenu|Combobox)/.*\.tsx$' | head -1)
+IS_MENU_PRIMITIVE=${IS_MENU_PRIMITIVE:-0}
+if [ "$HAS_POP_HEADER" -ge 1 ] && [ "$HAS_MENU_ITEM" -ge 1 ] && [ "$IS_MENU_PRIMITIVE" -eq 0 ]; then
+  if ! grep -qE 'panel-menuitem-allow:' "$FILE_PATH" 2>/dev/null; then
+    VIOLATIONS="${VIOLATIONS}\n⚠️ Panel-style Popover(<PopoverHeader>)+ <MenuItem> 同檔(${HAS_MENU_ITEM} hits):\n  → MenuItem 是 menu specialization(px-3 menu-style + icon 色繼承),不適 panel chrome loose。\n  → 改用視覺 primitive 自組:ItemPrefix + ItemLabel + ItemSuffix(item-anatomy.tsx)+ ROW_PADDING_BY_SIZE.md\n  Why:panel-style 需對齊 chrome \`loose\` + utility chrome icon color(neutral-7 / fg-muted),MenuItem 兩處 workaround = 錯 layer。\n  Escape hatch:加 \`// panel-menuitem-allow: <reason>\` 在檔頭。"
+  fi
+fi
+
+# ── Check 6: Overlay body 重新引入 flush / 等價 boolean variant(2026-05-01)──
+# 對齊 patterns/overlay-surface/overlay-surface.spec.md「List-as-region in overlay body」。
+# 2026-05-01 移除 flush(rationale:Material/Atlassian/Mantine/shadcn 主流不做 universal LayoutBody flush;
+# variant 不解決底層脆弱 — 加 1 row search/banner 就破功)。
+# 防止未來 silent re-introduction:DialogBody / SheetBody / PopoverBody tsx 內出現
+# `flush?: boolean` / `flush = false` / `naked?: boolean` / `bare?: boolean` / `noPadding?: boolean` 同類 boolean 變體。
+# Scope:`components/(Dialog|Sheet|Popover)/*.tsx`(非 stories)。
+IS_OVERLAY_BODY_TSX=$(echo "$FILE_PATH" | grep -cE 'components/(Dialog|Sheet|Popover)/[^/]+\.tsx$' | head -1)
+IS_OVERLAY_BODY_TSX=${IS_OVERLAY_BODY_TSX:-0}
+if [ "$IS_OVERLAY_BODY_TSX" -ge 1 ] && ! echo "$FILE_PATH" | grep -qE '\.stories\.tsx$'; then
+  STRIPPED_PROPS_PATTERN='(flush|naked|bare|stripped|unpadded|noPadding|paddingless)\??:\s*boolean'
+  STRIPPED_HITS=$(grep -nE "$STRIPPED_PROPS_PATTERN" "$FILE_PATH" 2>/dev/null | head -3)
+  if [ -n "$STRIPPED_HITS" ] && ! grep -qE 'overlay-body-stripped-variant-allow:' "$FILE_PATH" 2>/dev/null; then
+    VIOLATIONS="${VIOLATIONS}\n⚠️ Overlay body 重新引入 stripped-padding boolean variant(2026-05-01 已移除):\n${STRIPPED_HITS}\n  → list-as-region in overlay body canonical = consumer 用 className override:\n    <DialogBody className=\"!px-0 !pt-0 !pb-0\"><div className=\"py-2\">{items}</div></DialogBody>\n  Why removed:Material/Atlassian/Mantine/shadcn 主流不做 universal LayoutBody flush;\n  variant 不解決底層脆弱(加 1 row search/banner 就破功)+ 把 1 surface decision 拆兩 API。\n  詳 overlay-surface.spec.md「List-as-region in overlay body」+ memory feedback_layout_v6_canonical.md\n  Escape hatch:加 \`// overlay-body-stripped-variant-allow: <reason>\` 在檔頭(必含 ≥3 家世界級對照 + multi-row hold 保證)。"
+  fi
+fi
+
+if [ -n "$VIOLATIONS" ]; then
+  ESCAPED=$(printf "%b" "$VIOLATIONS" | jq -Rs .)
+  cat <<EOJSON
+{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"Primitive consumption 檢查發現違規:${ESCAPED}"}}
+EOJSON
+fi

package/ds-canonical/hooks/lib/_person_data_richness.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# PostToolUse hook: catch sparse PersonData literals that violate name-card.spec「DS-wide 預設展示一致 canonical」.
+#
+# Per name-card.spec.md:
+#   所有 PersonData 來源(table seller / picker member / dialog reviewer)展示 NameCard 時
+#   description / status / statusMessage / fields 4 個 section 預設都應提供
+#   sparse `{ name, avatarUrl }` 資料 = bug,違反一致呈現
+#
+# Detects literal `{ name: '...', avatar(Url)?: '...' }` with NO other PersonData fields.
+
+source "$(dirname "$0")/../_log-fire.sh" 2>/dev/null && log_hook_fire
+
+FILE_PATH=$(jq -r '.tool_input.file_path // empty')
+
+if ! echo "$FILE_PATH" | grep -qE '\.(tsx|stories\.tsx)$'; then
+  exit 0
+fi
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Skip the canonical sources(NameCard / Avatar / person-display 自身)
+if echo "$FILE_PATH" | grep -qE '(NameCard|Avatar|person-display|avatar\.spec)'; then
+  exit 0
+fi
+
+# Match `{ name: '...', avatarUrl?: '...' }` with no other PersonData fields on same line.
+# A "rich" PersonData usually spans multiple lines OR has description/status/statusMessage/fields.
+# Heuristic: single-line literal with only name + avatarUrl(no other PersonData props on same line).
+SPARSE_HITS=$(grep -nE "\{\s*name:\s*['\"][^'\"]+['\"],\s*avatar(Url)?:\s*['\"][^'\"]+['\"]\s*\}" "$FILE_PATH" 2>/dev/null | head -5)
+
+if [ -n "$SPARSE_HITS" ]; then
+  ADDITIONAL_CONTEXT=$(printf 'Sparse PersonData literal(違反 name-card.spec「DS-wide 預設展示一致 canonical」):\n%s\n  → 補上 description / status / statusMessage / fields 4 sections,讓 NameCard hover 展示資訊量一致' "$SPARSE_HITS")
+  jq -n --arg ctx "$ADDITIONAL_CONTEXT" '{
+    hookSpecificOutput: {
+      hookEventName: "PostToolUse",
+      additionalContext: $ctx
+    }
+  }'
+fi
+
+exit 0

package/ds-canonical/hooks/lib/_story_compile_drift.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# PreToolUse Edit/Write: 改過 tsx componentMeta / spec frontmatter 時,
+# 自動跑 compile-stories --check 偵測 drift。
+#
+# 對齊 Story Auto-Compile Phase 4 — stories canonical 從 spec+tsx 機械產,
+# key 不齊 = canonical drift,該修。本 hook 是 write-time early warning
+# (git commit 前),讓 AI / user 立刻看到 drift 而非 audit 時才發現。
+
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+source "$(dirname "$0")/../_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -euo pipefail
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+[ -z "$FILE_PATH" ] && exit 0
+
+# Only trigger on component tsx / spec.md writes
+case "$FILE_PATH" in
+  */design-system/components/*.tsx) ;;
+  */design-system/components/*.spec.md) ;;
+  *) exit 0 ;;
+esac
+
+# Extract component name from path
+COMP_NAME=$(echo "$FILE_PATH" | grep -oE 'components/[^/]+/' | head -1 | sed 's|components/||' | sed 's|/||')
+[ -z "$COMP_NAME" ] && exit 0
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+COMPILE_SCRIPT="$PROJECT_DIR/scripts/compile-stories.mjs"
+
+# Skip if compile script not yet built(graceful for pre-Phase-4 state)
+[ ! -f "$COMPILE_SCRIPT" ] && exit 0
+
+# Run drift check(quiet mode)
+cd "$PROJECT_DIR" || exit 0
+OUTPUT=$(node "$COMPILE_SCRIPT" "$COMP_NAME" --check 2>&1 || true)
+
+# Check if drift detected(exit 1 or has 「spec/tsx canonical drift」 in output)
+if echo "$OUTPUT" | grep -qE "spec/tsx canonical drift|spec-only|tsx-only"; then
+  MSG="📐 Story canonical drift detected in ${COMP_NAME}:\n\n${OUTPUT}\n\nFix tsx componentMeta export 或 spec frontmatter 讓 keys 對齊。"
+  ESCAPED=$(printf '%s' "$MSG" | jq -Rs .)
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":%s}}\n' "$ESCAPED"
+fi
+
+# Skip graceful(migration 未做的元件)不報
+exit 0