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

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

@@ -0,0 +1,95 @@
+#!/bin/bash
+# PostToolUse hook: catch 4 classes of token hygiene / cross-OS violations on component/pattern tsx edits.
+#
+# Detects (ALL are silent-fail or cross-OS drift bug classes per CLAUDE.md):
+# 1. shadcn compat alias 回流 — bg-popover / text-muted-foreground / bg-accent / text-accent-foreground / text-popover-foreground / bg-destructive / bg-background / bg-card / border-input / text-primary-foreground
+#    (these are shadcn safety-net aliases; our DS code MUST use direct tokens)
+# 2. Tailwind v4 `[--foo]` shorthand — must be `var(--foo)` wrapped; historical bug:
+#    Sidebar's `w-[--sidebar-width]` broke 8 places (silent fail, no error)
+# 3. Hardcoded Tailwind shadow — `shadow-sm/md/lg/xl/2xl` is forbidden; must use `shadow-[var(--elevation-N)] N∈{100,200,300}`
+# 4. Native overflow-{auto,scroll} without ScrollArea — cross-OS scrollbar drift
+#    (macOS overlay 不吃寬 / Windows always-visible 吃 17px = 跨 OS 跑版)
+#    應改用 ScrollArea(Components/ScrollArea/)— overlay scrollbar 跨 OS 一致
+#
+# WARN-style (not BLOCK): hook emits additionalContext so AI reads and can fix in next iteration.
+
+# 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 component / pattern .tsx files (not stories, not specs)
+if ! echo "$FILE_PATH" | grep -qE 'packages/design-system/src/(components|patterns)/.*\.tsx$'; then
+  exit 0
+fi
+if echo "$FILE_PATH" | grep -qE '\.stories\.tsx$'; then
+  exit 0
+fi
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+VIOLATIONS=""
+
+# ── Check 1: shadcn compat alias 回流 ─────────────────────────────────────────
+# These are all shadcn safety-net aliases. Our code must use direct tokens instead.
+# bg-muted / bg-secondary / ring-ring are OUR tokens (kept), not listed here.
+SHADCN_PATTERN='\b(bg-popover|text-popover-foreground|text-muted-foreground|bg-accent|text-accent-foreground|bg-destructive|bg-background|bg-card|text-card-foreground|border-input|text-primary-foreground)\b'
+SHADCN_HITS=$(grep -nE "$SHADCN_PATTERN" "$FILE_PATH" 2>/dev/null | head -5)
+if [ -n "$SHADCN_HITS" ]; then
+  VIOLATIONS="${VIOLATIONS}\n⚠️ shadcn compat alias found (必須遷移為 direct token):\n${SHADCN_HITS}\n  映射: bg-popover→bg-surface-raised / text-popover-foreground→text-foreground / text-muted-foreground→text-fg-muted / bg-accent→bg-neutral-hover / text-accent-foreground→text-foreground / bg-destructive→bg-error / bg-background→bg-canvas / bg-card→bg-surface / border-input→border-border / text-primary-foreground→text-white"
+fi
+
+# ── Check 2: Tailwind v4 [--foo] shorthand (silent fail) ─────────────────────
+# Arbitrary-value class 引用 CSS variable 必須 var() 包覆,不能 [--foo] shorthand.
+# Matches: w-[--foo], h-[--bar-baz], shadow-[--elevation-100] 等
+# False positive exclusion: [&[data-...]] / [&:hover] 等 arbitrary variants (open bracket 後跟 & 或冒號)
+TWV4_PATTERN='\[--[a-z][a-z0-9-]*\]'
+TWV4_HITS=$(grep -nE "$TWV4_PATTERN" "$FILE_PATH" 2>/dev/null | grep -v '\[&' | head -5)
+if [ -n "$TWV4_HITS" ]; then
+  VIOLATIONS="${VIOLATIONS}\n⚠️ Tailwind v4 [--foo] shorthand found (silent fail,必須 var() 包覆):\n${TWV4_HITS}\n  修法:將 [--foo] 改為 [var(--foo)]"
+fi
+
+# ── Check 3: Hardcoded Tailwind shadow ────────────────────────────────────────
+# shadow-sm/md/lg/xl/2xl 是 Tailwind 預設,繞過 elevation token 系統——禁止.
+# 允許:shadow-none / shadow-[var(--elevation-N)] N∈{100,200,300} / shadow-[calc(...)]
+SHADOW_PATTERN='\bshadow-(sm|md|lg|xl|2xl|inner)\b'
+SHADOW_HITS=$(grep -nE "$SHADOW_PATTERN" "$FILE_PATH" 2>/dev/null | head -5)
+if [ -n "$SHADOW_HITS" ]; then
+  VIOLATIONS="${VIOLATIONS}\n⚠️ Tailwind default shadow found (禁用,必須用 elevation token):\n${SHADOW_HITS}\n  修法:shadow-sm→shadow-[var(--elevation-100)] / shadow-md→shadow-[var(--elevation-200)] / shadow-lg→shadow-[var(--elevation-300)]"
+fi
+
+# ── Check 4: primitive color name used as Tailwind utility (silent fail) ─────
+# Primitive tokens (`--color-neutral-N` / `--color-blue-N` 等) 只在 :root 宣告,
+# 沒經 semantic.css 的 `@theme inline` 橋接 → 寫 `bg-neutral-3` / `text-blue-6`
+# 當 Tailwind utility 會 silent 失效(class 編譯後不生成任何規則)。
+# 正確:用 semantic utility(bg-secondary / bg-muted)或 arbitrary value
+# `bg-[var(--color-neutral-3)]`(Tag categorical 色常用)。
+# 歷史 bug:2026-04-22 FileItem compact static bg 用 `bg-neutral-3` 完全沒底色,
+# user 對照 Badge low 可見才發現;spec layer + 本 hook 同步修。
+PRIMITIVE_PATTERN='\b(bg|text|border|ring|fill|stroke|shadow|outline|decoration|divide|placeholder|caret|accent)-(neutral|blue|red|green|yellow|orange|purple|pink|cyan|teal|indigo|violet|deep-orange)-[0-9]+\b'
+PRIMITIVE_HITS=$(grep -nE "$PRIMITIVE_PATTERN" "$FILE_PATH" 2>/dev/null | head -5)
+if [ -n "$PRIMITIVE_HITS" ]; then
+  VIOLATIONS="${VIOLATIONS}\n⚠️ Primitive color name used as Tailwind utility (silent fail):\n${PRIMITIVE_HITS}\n  修法:改用 semantic utility(bg-secondary / bg-muted / bg-surface / text-fg-muted 等)或 arbitrary value(bg-[var(--color-neutral-3)] 給 Tag categorical 色用)。理由:primitive token 沒經 @theme inline 橋接,bg-neutral-3 等會 silent 失效。"
+fi
+
+# ── Check 5: native overflow-{auto,scroll} without ScrollArea ─────────────────
+# 在 component / pattern .tsx 裡 raw overflow-auto / overflow-scroll =
+# 跨 OS scrollbar 不一致(macOS overlay / Windows always-visible 吃 17px)。
+# 應改用 ScrollArea(Components/ScrollArea/)。
+# 允許:horizontal-overflow pattern(有 scrollbar-none / fade-mask 特殊 UX)/
+#      use-overflow-items hook consumers(Tabs/ChipGroup hiding scroll)
+OVERFLOW_PATTERN='\boverflow-(auto|scroll|x-auto|x-scroll|y-auto|y-scroll)\b'
+OVERFLOW_HITS=$(grep -nE "$OVERFLOW_PATTERN" "$FILE_PATH" 2>/dev/null | grep -vE 'scrollbar-none|useOverflow|horizontal-overflow' | head -5)
+if [ -n "$OVERFLOW_HITS" ]; then
+  VIOLATIONS="${VIOLATIONS}\n⚠️ Native overflow-auto/scroll found (可能造成跨 OS 跑版):\n${OVERFLOW_HITS}\n  考慮改用 ScrollArea(\`@/design-system/components/ScrollArea/scroll-area\`)取得跨 OS 一致 overlay 捲軸。例外:刻意隱藏捲軸(scrollbar-none)+ fade-mask UX 屬 horizontal-overflow pattern,不套用本規則。"
+fi
+
+# ── Emit warning if any violation found ────────────────────────────────────
+if [ -n "$VIOLATIONS" ]; then
+  # Escape for JSON (newlines)
+  ESCAPED=$(printf "%b" "$VIOLATIONS" | jq -Rs .)
+  cat <<EOJSON
+{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"Token hygiene 檢查發現違規 (CLAUDE.md 明文禁止項):${ESCAPED}\n\n這些是 silent-fail bug classes——不會造成 compile error,但 runtime 視覺或行為會壞。下個 Edit 回去修。"}}
+EOJSON
+fi

package/ds-canonical/hooks/log_governance_fires.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+set -uo pipefail
+# PostToolUse: log governance-relevant file writes to .claude/logs/hook-fires.jsonl
+#
+# Why: Meta-Pattern M18 — governance must be instrumented, not hoped for.
+# Fire-log lets /knowledge-prune identify:
+#   - dead hooks (never appear in log over 6 months → retire candidate)
+#   - hot files (edited constantly → candidate for refactor / split)
+#   - governance file edit cadence (CLAUDE.md edited 10x/week → churn signal)
+#
+# Size cap: if log > 1 MB, rotate to .jsonl.YYYYMM (keeps inspection file tight).
+# Non-blocking; silent on success.
+
+# 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_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+[ -z "$FILE_PATH" ] && exit 0
+
+# Only log governance files
+case "$FILE_PATH" in
+  */CLAUDE.md|*/memory/*.md|*.spec.md|*.claude/skills/*|*.claude/hooks/*|*.claude/settings.json) ;;
+  *) exit 0 ;;
+esac
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+LOG_DIR="$PROJECT_DIR/.claude/logs"
+LOG_FILE="$LOG_DIR/hook-fires.jsonl"
+
+mkdir -p "$LOG_DIR"
+
+# Rotate if > 1 MB
+if [ -f "$LOG_FILE" ]; then
+  SIZE=$(wc -c < "$LOG_FILE" | tr -d ' ')
+  if [ "$SIZE" -gt 1048576 ]; then
+    mv "$LOG_FILE" "${LOG_FILE}.$(date +%Y%m)"
+  fi
+fi
+
+# Append single-line JSON
+TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+REL_PATH=${FILE_PATH#$PROJECT_DIR/}
+printf '{"ts":"%s","tool":"%s","path":"%s"}\n' "$TIMESTAMP" "$TOOL_NAME" "$REL_PATH" >> "$LOG_FILE"
+
+exit 0

package/ds-canonical/hooks/log_skill_invokes.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+set -uo pipefail
+# PostToolUse Skill: log each skill invocation to .claude/logs/skill-invokes.jsonl
+#
+# 對齊 Meta-Pattern M14(AUTO integrate pipeline instrumentation)+ M10(proactive scan)。
+# /governance-health Phase 1 消費本 log 偵測 dead skill(3 mo 0 invoke = retire 候選)
+# + hot skill(high invoke = 值得優化 workflow)。
+#
+# 無本 hook,skill-invokes.jsonl 永遠空,governance-health 無法做 skill-level 決策。
+# Dogfood 時發現這個 gap。
+
+# 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_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+[ "$TOOL_NAME" != "Skill" ] && exit 0
+
+SKILL_NAME=$(echo "$INPUT" | jq -r '.tool_input.skill // empty')
+[ -z "$SKILL_NAME" ] && exit 0
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+LOG_DIR="$PROJECT_DIR/.claude/logs"
+LOG_FILE="$LOG_DIR/skill-invokes.jsonl"
+mkdir -p "$LOG_DIR"
+
+# Rotate if > 1 MB(對齊其他 log rotation 策略)
+if [ -f "$LOG_FILE" ]; then
+  SIZE=$(wc -c < "$LOG_FILE" | tr -d ' ')
+  if [ "$SIZE" -gt 1048576 ]; then
+    mv "$LOG_FILE" "${LOG_FILE}.$(date +%Y%m)"
+  fi
+fi
+
+TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+ARGS=$(echo "$INPUT" | jq -r '.tool_input.args // empty' | head -c 200)
+printf '{"ts":"%s","skill":"%s","args":"%s"}\n' "$TIMESTAMP" "$SKILL_NAME" "${ARGS//\"/\\\"}" >> "$LOG_FILE"
+
+exit 0

package/ds-canonical/hooks/post_edit_dispatcher.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# post_edit_dispatcher.sh — orchestrate 8 lib helper rules (PostToolUse Write|Edit|MultiEdit)
+#
+# 2026-05-13 /knowledge-prune consolidation:
+#   Per CLAUDE.md governance hook count budget (25 soft / 30 hard,Anthropic ~15 guideline)
+#   Pre-consolidation: 32 hooks → BLOCKER 30 cap breached
+#   This dispatcher folds 8 lib/_*.sh helpers into one hook registration
+#   Lib helpers remain as standalone testable files (renamed `_*` per Unix internal-helper convention)
+#   Net hook count: 32 - 8 lib + 1 dispatcher = 25 ✅
+#
+# Pattern: read stdin INPUT once,pipe to each helper sequentially,collect their JSON outputs
+# Each helper:
+#   - Reads file_path from stdin via jq
+#   - Filters by scope (skips if out-of-scope)
+#   - Emits {hookSpecificOutput: {additionalContext: "..."}} OR exits 0 silent
+# Dispatcher: concatenate non-empty additionalContext blocks into ONE JSON output
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null || echo "{}")
+HOOKS_DIR="$(dirname "$0")"
+LIB_DIR="$HOOKS_DIR/lib"
+
+# Aggregate additionalContext fragments from each helper
+COMBINED=""
+
+run_helper() {
+  local helper="$1"
+  [ -f "$helper" ] || return 0
+  local out
+  out=$(printf '%s' "$INPUT" | bash "$helper" 2>/dev/null)
+  [ -z "$out" ] && return 0
+  # Extract additionalContext via jq (each helper emits valid JSON)
+  local ctx
+  ctx=$(printf '%s' "$out" | jq -r '.hookSpecificOutput.additionalContext // empty' 2>/dev/null)
+  [ -z "$ctx" ] && return 0
+  if [ -z "$COMBINED" ]; then
+    COMBINED="$ctx"
+  else
+    COMBINED="${COMBINED}"$'\n\n────────\n\n'"$ctx"
+  fi
+}
+
+# Run 8 helpers sequentially (all silent-fail / exit 0 / additive warnings)
+run_helper "$LIB_DIR/_token_hygiene.sh"
+run_helper "$LIB_DIR/_hardcoded_strings.sh"
+run_helper "$LIB_DIR/_code_quality.sh"
+run_helper "$LIB_DIR/_layout_space_canonical.sh"
+run_helper "$LIB_DIR/_person_data_richness.sh"
+run_helper "$LIB_DIR/_overlay_handcraft.sh"
+run_helper "$LIB_DIR/_cva_default_sync.sh"
+run_helper "$LIB_DIR/_story_compile_drift.sh"
+run_helper "$LIB_DIR/_governance_coverage_check.sh"
+
+if [ -n "$COMBINED" ]; then
+  ESCAPED=$(printf '%s' "$COMBINED" | jq -Rs .)
+  printf '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":%s}}\n' "$ESCAPED"
+fi
+
+exit 0

package/ds-canonical/hooks/retired/check_anatomy_section_numbering.sh

@@ -0,0 +1,106 @@
+#!/bin/bash
+# PostToolUse hook: when editing a *.anatomy.stories.tsx file, verify section
+# numbering matches canonical slot rules (updated 2026-04-22 to align with
+# anatomy-standard.md's「保留 canonical 編號」rule).
+#
+# Canonical slots:
+#   1 = Overview      (reserved)
+#   2 = Inspector     (reserved)
+#   3 = ColorMatrix   (reserved)
+#   4 = SizeMatrix    (reserved)
+#   5 = StateBehavior (reserved)
+#   6+ = custom sections (contiguous from 6 onwards)
+#
+# **N/A slots keep their reserved number unused** (e.g. Calendar has no
+# SizeMatrix → file has 1,2,3,5 with a gap at 4). This is correct per canonical;
+# the previous hook version enforced strict contiguous 1..N which contradicted
+# canonical — reconciled 2026-04-22.
+#
+# Rules:
+#   - Slots in 1..5 MUST be one of the canonical set (1=Overview/2=Inspector/...)
+#     but may have gaps for N/A sections
+#   - Slots 6+ MUST be contiguous starting from 6 (no gaps in custom section tail)
+#   - No duplicate numbers anywhere
+#
+# Trigger: PostToolUse on Edit/Write/MultiEdit where file_path ends in
+# `.anatomy.stories.tsx`.
+
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+FILE_PATH="${CLAUDE_TOOL_INPUT_FILE_PATH:-}"
+
+case "$FILE_PATH" in
+  *.anatomy.stories.tsx) ;;
+  *) exit 0 ;;
+esac
+
+[ -f "$FILE_PATH" ] || exit 0
+
+NUMS=$(grep -oE "name:[[:space:]]*'[0-9]+\." "$FILE_PATH" 2>/dev/null | grep -oE "[0-9]+" | tr '\n' ' ')
+
+if [ -z "${NUMS// }" ]; then
+  exit 0
+fi
+
+BROKEN=0
+BROKEN_DETAIL=""
+SEEN=""
+
+# Sort numbers to check set properties (Storybook sidebar sorts by name prefix,
+# so file export order doesn't matter for UX)
+SORTED=$(echo "$NUMS" | tr ' ' '\n' | sort -n | tr '\n' ' ')
+
+# Check 1: no duplicates
+for N in $NUMS; do
+  case " $SEEN " in
+    *" $N "*)
+      BROKEN=1
+      BROKEN_DETAIL="${BROKEN_DETAIL}\n  • Duplicate slot number: ${N}"
+      ;;
+  esac
+  SEEN="$SEEN $N"
+done
+
+# Check 2: custom sections 6+ must form contiguous block starting from 6
+PREV=5
+for N in $SORTED; do
+  if [ "$N" -ge 6 ]; then
+    EXPECTED=$((PREV + 1))
+    if [ "$N" -ne "$EXPECTED" ]; then
+      BROKEN=1
+      BROKEN_DETAIL="${BROKEN_DETAIL}\n  • Custom section gap: expected ${EXPECTED}, got ${N}(6+ 必連續,不可跳號)"
+    fi
+    PREV="$N"
+  fi
+done
+
+# Check 3: canonical slot range validation
+for N in $NUMS; do
+  if [ "$N" -lt 1 ]; then
+    BROKEN=1
+    BROKEN_DETAIL="${BROKEN_DETAIL}\n  • Invalid slot: ${N}(must be ≥ 1)"
+  fi
+done
+
+if [ "$BROKEN" = "1" ]; then
+  cat <<EOF
+⚠️  Anatomy story numbering drift — $FILE_PATH
+
+Got sequence: $NUMS
+
+Issues:$(printf "%b" "$BROKEN_DETAIL")
+
+Canonical slots(anatomy-standard.md「保留 canonical 編號」):
+  1 = Overview     2 = Inspector     3 = ColorMatrix
+  4 = SizeMatrix   5 = StateBehavior
+  6+ = custom sections(contiguous from 6)
+
+N/A canonical slot 保留編號不 renumber(e.g. 無 SizeMatrix → 1,2,3,5 正確)。
+自訂 section 必從 6 開始連續(不可混入 1-5 slot 號)。
+EOF
+fi
+
+exit 0

package/ds-canonical/hooks/retired/check_avatar_hovercard.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+# PostToolUse hook: enforce "person avatar → NameCard hoverCard" DS-wide canonical.
+#
+# Canonical source: packages/design-system/src/components/Avatar/avatar.spec.md
+#   「Avatar HoverCard 原則(DS-wide canonical,必遵守)」section
+#
+# Rule: any `<Avatar>` with `alt="..."` that looks like a PERSON name
+#   must also have `hoverCard={...}` prop (typically `<NameCard .../>`).
+#
+# Person-name heuristic (avoid false positive on entity names):
+#   - alt contains a space (人名常有空格:"Alan Chen" / "張三 / Ada Chen")
+#   - alt pattern like Ch/En first+last name
+#   - OR alt is a variable like `{p.name}` / `{member.name}` / `{user.name}` / `{person.name}`
+#
+# Entity names (NOT person, exempt):
+#   - single word + company suffix (Inc / Corp / Ltd / Co)
+#   - icon shape (alt matches "icon" variable)
+#   - file thumbnails (shape="square")
+#
+# Output: WARN (additionalContext), not block — AI reads and fixes next iteration.
+
+# 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 files (tsx + stories.tsx)
+if ! echo "$FILE_PATH" | grep -qE 'src/(design-system|explorations|app)/.*\.tsx$'; then
+  exit 0
+fi
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Exempt core Avatar/NameCard/HoverCard self-files and some internal primitives
+if echo "$FILE_PATH" | grep -qE '(Avatar/avatar\.tsx|NameCard/|HoverCard/|Empty/empty\.tsx|FileItem/file-item\.tsx|PeoplePicker/person-display\.tsx)'; then
+  exit 0
+fi
+
+VIOLATIONS=""
+
+# Find <Avatar uses that look like person avatars but lack hoverCard
+# We match <Avatar ... alt={...name...} ... /> without hoverCard in the same tag
+PERSON_AVATARS=$(grep -nE '<Avatar[^>]*(alt=\{[^}]*\.name|alt="[A-Z][a-z]+\s[A-Z][a-z]+")' "$FILE_PATH" | while read -r line; do
+  # Extract line number + line content
+  LINE_NUM=$(echo "$line" | cut -d: -f1)
+  LINE_CONTENT=$(echo "$line" | cut -d: -f2-)
+  # Check: does this Avatar tag (multi-line possible) contain hoverCard?
+  # Read next 8 lines after start to catch multi-line <Avatar ... />
+  BLOCK=$(sed -n "${LINE_NUM},$(( LINE_NUM + 8 ))p" "$FILE_PATH")
+  if ! echo "$BLOCK" | grep -q "hoverCard"; then
+    echo "  - $FILE_PATH:$LINE_NUM — <Avatar alt=... without hoverCard (person avatar 需 NameCard — 見 avatar.spec.md「Avatar HoverCard 原則」)"
+  fi
+done)
+
+# Also check AvatarData object literals with .name-like alt
+AVATAR_DATA=$(grep -nE '\{[[:space:]]*alt:[[:space:]]*[`"'\''"]?[A-Z][a-z]+ [A-Z][a-z]+' "$FILE_PATH" | while read -r line; do
+  LINE_NUM=$(echo "$line" | cut -d: -f1)
+  # Check same object doesn't have hoverCard
+  BLOCK=$(sed -n "${LINE_NUM},$(( LINE_NUM + 3 ))p" "$FILE_PATH")
+  if ! echo "$BLOCK" | grep -q "hoverCard"; then
+    echo "  - $FILE_PATH:$LINE_NUM — AvatarData with person alt 缺 hoverCard (MenuItem/SelectionItem/SelectMenu avatar prop 支援 hoverCard,必傳 NameCard)"
+  fi
+done)
+
+if [ -n "$PERSON_AVATARS" ] || [ -n "$AVATAR_DATA" ]; then
+  VIOLATIONS="$PERSON_AVATARS
+$AVATAR_DATA"
+  cat <<EOF >&2
+⚠️ Person avatar 缺 hoverCard(NameCard):
+
+$VIOLATIONS
+
+Canonical:avatar.spec.md「Avatar HoverCard 原則(DS-wide canonical)」— person avatar 必 hover → NameCard(default,非 opt-in)。
+
+修法:
+  <Avatar
+    src={...} alt={person.name} size={N}
+    hoverCard={<NameCard name={person.name} subtitle={...} actions={<NameCardDefaultActions />} />}
+  />
+
+OR AvatarData:
+  { alt: person.name, src: ..., hoverCard: <NameCard ... /> }
+
+豁免(entity avatar,不適用):organization logo / 專案 icon / app icon / file thumbnail
+EOF
+  exit 0
+fi
+
+exit 0

package/ds-canonical/hooks/retired/check_button_icon_literal.sh.retired-2026-04-28

@@ -0,0 +1,38 @@
+#!/bin/bash
+# PostToolUse hook: catch literal icon characters in Button content (e.g. "+ 新增").
+#
+# Per .claude/rules/ui-development.md「Icon canonical」:
+# Icon 必須用 lucide-react component(Plus / X / Check / TriangleAlert / Info / etc),
+# 不可在 Button label 寫字面 "+" / "-" / "×" / "✓" / "→" 等符號當 icon 用。
+#
+# Detects: <Button ... >+ XX</Button> / <Button>↗ Open</Button> 等 pattern.
+
+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
+
+# Match Button content starting with a single icon-like character + space
+# Examples that violate:
+#   <Button>+ 新增</Button>
+#   <Button>× Close</Button>
+#   <Button>→ Continue</Button>
+LITERAL_HITS=$(grep -nE '<Button[^>]*>\s*[-+×✕✗✓→←↑↓↗↖↘↙]\s+' "$FILE_PATH" 2>/dev/null | head -5)
+
+if [ -n "$LITERAL_HITS" ]; then
+  ADDITIONAL_CONTEXT=$(printf 'Button label 含字面 icon 字元(請改 lucide-react component):\n%s\n  映射: + → startIcon={Plus} / × → startIcon={X} / → → endIcon={ArrowRight} / ✓ → startIcon={Check}' "$LITERAL_HITS")
+  jq -n --arg ctx "$ADDITIONAL_CONTEXT" '{
+    hookSpecificOutput: {
+      hookEventName: "PostToolUse",
+      additionalContext: $ctx
+    }
+  }'
+fi
+
+exit 0

package/ds-canonical/hooks/retired/check_container_breathing.sh

@@ -0,0 +1,142 @@
+#!/bin/bash
+# PreToolUse hook: detect consumer 自建的 visual container(bg/border/shadow)缺 inner padding。
+#
+# Motivation(CLAUDE.md + element-anatomy.spec.md「視覺容器 breathing invariant」· 2026-04-22):
+#   任何有視覺邊界(permanent bg-* / border / shadow-*)的容器必有 inner padding,
+#   不讓內容物觸容器邊。責任在父容器。
+#
+# 世界級一致:Material / Polaris / Atlassian / Ant / Apple HIG / Carbon 6 家 chrome 都 own 內 padding。
+#
+# 反例(本 session 2026-04-22 糾正):
+#   <div className="bg-surface-raised rounded-lg">{rich FileItem map}</div>
+#   → rich card w-full 貼父 div 邊,兩層 rounded 視覺卡在一起
+#
+# 檢查 pattern(保守:只 warn,不 block — 靜態 grep 無法完美判斷):
+#   P1 WARN  `<div className="...bg-* | border | shadow-*...">` 且同 className 無 p*- / px-* / py-*
+#            → warn consumer 可能漏 padding
+#
+# Scope: *.tsx(component + story + exploration)
+#
+# Allowlist:
+#   // @breathing-exempt: <reason>(整檔豁免)
+#   // @breathing-exempt-next(下一行豁免)
+#
+# Exit codes:
+#   exit 0 — pass(P1 warn 也走 0,不 block;重要改 chrome primitive 可升級為 block)
+#
+# 不攔截的情境(AI 判斷,非 hook 責任):
+#   - 子元件自己的 class(如 Button `bg-primary px-3` 已有 padding)
+#   - p-0 刻意覆寫(如 SheetBody variant="list" `py-2`)
+#   - 無 bg 的 flex container 只用 border separator
+
+# 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
+
+case "$FILE_PATH" in
+  *.tsx) ;;
+  *) exit 0 ;;
+esac
+
+NEW_CONTENT=$(echo "$INPUT" | jq -r '
+  (.tool_input.content // "") + "\n" +
+  (.tool_input.new_string // "") + "\n" +
+  ([.tool_input.edits[]? | .new_string] | join("\n"))
+' 2>/dev/null || echo "")
+
+if [ -z "${NEW_CONTENT//[[:space:]]/}" ]; then
+  exit 0
+fi
+
+# ── File-level allowlist ──
+FIRST_LINES=$(printf '%s\n' "$NEW_CONTENT" | sed -n '1,3p')
+if echo "$FIRST_LINES" | grep -qE '//[[:space:]]*@breathing-exempt:'; then
+  exit 0
+fi
+if [ -f "$FILE_PATH" ]; then
+  ON_DISK_FIRST=$(sed -n '1,3p' "$FILE_PATH" 2>/dev/null || true)
+  if echo "$ON_DISK_FIRST" | grep -qE '//[[:space:]]*@breathing-exempt:'; then
+    exit 0
+  fi
+fi
+
+WARN_VIOLATIONS=""
+
+TMP=$(mktemp)
+trap 'rm -f "$TMP"' EXIT
+printf '%s\n' "$NEW_CONTENT" > "$TMP"
+
+ROW=0
+SKIP_NEXT=0
+while IFS= read -r LINE || [ -n "$LINE" ]; do
+  ROW=$((ROW+1))
+
+  if [ "$SKIP_NEXT" = "1" ]; then
+    SKIP_NEXT=0
+    continue
+  fi
+  if echo "$LINE" | grep -qE '//[[:space:]]*@breathing-exempt-next|\{/\*[[:space:]]*@breathing-exempt-next'; then
+    SKIP_NEXT=1
+    continue
+  fi
+
+  # P1 WARN: `<div className="..."` contains visual-boundary class(bg-*/border/shadow-*)且 same className 無 padding
+  #
+  # heuristic:只查 div / section 等 structural element,不查 children 元件(Button / Input 等自帶 padding)
+  # 視覺邊界 class:
+  #   bg-surface* / bg-neutral-* / bg-primary* / bg-error* / bg-* (有色的,不含 bg-transparent)
+  #   border / border-* (但 border-0 / border-transparent 不算)
+  #   shadow-[var(--elevation-* (不含 shadow-none)
+  # Padding class:
+  #   p-[0-9]+ / px-[0-9]+ / py-[0-9]+ / p-\[var(--layout-space-* / px-\[var / py-\[var / p-calc / p-0(刻意移除也算宣告)
+  if echo "$LINE" | grep -qE '<(div|section|aside|header|footer|main|nav)[^>]*className="[^"]*"'; then
+    # Extract className content(best-effort for single-line):
+    CLASSNAMES=$(echo "$LINE" | grep -oE 'className="[^"]+"' | head -1)
+    # Has visual boundary?
+    HAS_BG=$(echo "$CLASSNAMES" | grep -qE '\bbg-(surface|neutral|primary|error|warning|success|info|inverse|overlay)[a-z0-9-]*|\bbg-\[' && echo 1 || echo 0)
+    HAS_BORDER=$(echo "$CLASSNAMES" | grep -qE '\bborder(-[a-z0-9]+)?\b' && ! echo "$CLASSNAMES" | grep -qE '\bborder-0\b|\bborder-transparent\b' && echo 1 || echo 0)
+    HAS_SHADOW=$(echo "$CLASSNAMES" | grep -qE '\bshadow-\[var\(--elevation|\bshadow-\[' && ! echo "$CLASSNAMES" | grep -qE '\bshadow-none\b' && echo 1 || echo 0)
+
+    if [ "$HAS_BG" = "1" ] || [ "$HAS_BORDER" = "1" ] || [ "$HAS_SHADOW" = "1" ]; then
+      # Has padding?
+      HAS_PADDING=$(echo "$CLASSNAMES" | grep -qE '\bp-[0-9]+\b|\bpx-[0-9]+\b|\bpy-[0-9]+\b|\bpt-[0-9]+\b|\bpb-[0-9]+\b|\bpl-[0-9]+\b|\bpr-[0-9]+\b|\bp-\[|\bpx-\[|\bpy-\[|\bpt-\[|\bpb-\[' && echo 1 || echo 0)
+      if [ "$HAS_PADDING" = "0" ]; then
+        REASONS=""
+        [ "$HAS_BG" = "1" ] && REASONS="${REASONS} bg"
+        [ "$HAS_BORDER" = "1" ] && REASONS="${REASONS} border"
+        [ "$HAS_SHADOW" = "1" ] && REASONS="${REASONS} shadow"
+        WARN_VIOLATIONS="${WARN_VIOLATIONS}
+────────────────────────────────
+[P1 visual container 缺 inner padding(warn)] ${FILE_PATH}:${ROW}
+  視覺邊界:${REASONS# }
+  > $(echo "$LINE" | sed 's/^[[:space:]]*//' | cut -c1-120)
+  判斷: 視覺容器(bg/border/shadow)必有 inner padding,不讓內容物貼容器邊。
+        建議:chrome 層用 p-[var(--layout-space-N) N∈{loose,tight}] / px-3 等。
+        若是 (a) chrome primitive override 刻意 p-0,(b) 父容器另外提供 padding,
+        (c) 子元件自帶足夠 padding → 加 // @breathing-exempt-next 到此行上一行。
+        SSOT: patterns/element-anatomy/element-anatomy.spec.md「視覺容器 breathing invariant」"
+      fi
+    fi
+  fi
+
+done < "$TMP"
+
+if [ -n "$WARN_VIOLATIONS" ]; then
+  {
+    echo ""
+    echo "┄┄┄┄ check_container_breathing — P1 warn(視覺容器缺 inner padding) ┄┄┄┄"
+    printf '%s\n' "$WARN_VIOLATIONS"
+  } >&2
+fi
+
+exit 0