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

package/ds-canonical/hooks/check_naming_and_abstraction.sh

@@ -0,0 +1,165 @@
+#!/bin/bash
+# Naming + abstraction unified hook(2026-05-08 cluster D consolidation)
+#
+# Merges 3 PreToolUse hooks(原各檔已 retire,合併入此):
+#   D.1 premature abstraction(原 check_premature_abstraction,P0 BLOCK)
+#   D.2 internal namespace consistency(原 check_internal_namespace_consistency,P0 BLOCK)
+#   D.3 primitive color var in tsx(原 check_primitive_color_var_in_tsx,P1 WARN stderr)
+#
+# Why merge:皆 命名 / 抽象 / token 消費紀律 invariant,共用 INPUT parsing 模式。
+# 散裝是 M17 + Anthropic ≤ 15 hook best-practice 偏離。
+#
+# Per-rule scope 差異(必保留各自 narrow):
+#   D.1: Write only + components/X/X.tsx 或 spec.md 主檔 + 新檔
+#   D.2: Edit/Write/MultiEdit + *.stories.tsx
+#   D.3: Edit/Write/MultiEdit + *.tsx minus Tag/Avatar/Chart/tokens
+#
+# Per-rule allowlist:
+#   D.1: 檔頭 10 行內 `// @separate-component-rationale: <world-class refs + 3-test 通過理由>`
+#   D.2: (無 allowlist,但若 file 沒 title namespace 自動 skip)
+#   D.3: 行尾 `// @primitive-color-allow: <reason>` OR 檔頭 `// primitive-color-allow-blanket`
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo 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
+
+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 "")
+
+[ -z "${NEW_CONTENT//[[:space:]]/}" ] && exit 0
+
+WORST=0
+record_worst() { local lvl=$1; [ "$lvl" -gt "$WORST" ] && WORST=$lvl; }
+
+# ── D.1 premature abstraction(Write only,新元件 BLOCK)──────────────────────
+if [ "$TOOL" = "Write" ]; then
+  case "$FILE_PATH" in
+    */packages/design-system/src/components/*/[^.]*.tsx|*/packages/design-system/src/components/*/*.spec.md)
+      if [ ! -f "$FILE_PATH" ]; then
+        COMPONENT_DIR=$(echo "$FILE_PATH" | sed -E 's|.*/components/([^/]+)/.*|\1|')
+        SUFFIX=""
+        BASE_NAME=""
+        for SFX in Time Range Color Light Dark Filled Outline Compact Rich Variant; do
+          if [[ "$COMPONENT_DIR" =~ ${SFX}$ ]] && [ "$COMPONENT_DIR" != "$SFX" ]; then
+            BASE=$(echo "$COMPONENT_DIR" | sed -E "s/${SFX}$//")
+            [ -z "$BASE" ] && continue
+            COMPONENTS_ROOT=$(echo "$FILE_PATH" | sed -E 's|(.*/components)/.*|\1|')
+            if [ -d "$COMPONENTS_ROOT/$BASE" ]; then
+              SUFFIX="$SFX"; BASE_NAME="$BASE"; break
+            fi
+          fi
+        done
+        if [ -n "$SUFFIX" ]; then
+          # Allowlist:檔頭 10 行內 rationale comment
+          if ! echo "$NEW_CONTENT" | head -10 | grep -qE '//\s*@separate-component-rationale:|^\s*#?\s*@separate-component-rationale:'; then
+            cat >&2 <<EOF
+
+┄┄┄ D.1 check_naming_and_abstraction — premature abstraction BLOCKER ┄┄┄
+
+[P0] 新元件 \`${COMPONENT_DIR}\`(後綴 \`${SUFFIX}\`)
+基底元件 \`${BASE_NAME}\` 已存在 → 強烈 signal 應為 prop variant on \`${BASE_NAME}\`。
+
+歷史(M21):
+  - DateTimePicker → \`<DatePicker showTime>\`
+  - DataTableFilterPanel → sub-file pattern
+
+3-test 通過才能分:
+  1. \`${BASE_NAME}\` 加 prop 達不到同 DOM/behavior?
+  2. ≥3 家 world-class DS 用分離元件而非 prop?(必 cite source)
+  3. value 結構或 contract 真的不同(如 Range = [start, end])?
+
+通過 → spec.md 加 rationale + 檔頭 10 行內加:
+  // @separate-component-rationale: <world-class refs + 3-test 通過理由>
+
+EOF
+            record_worst 2
+          fi
+        fi
+      fi
+      ;;
+  esac
+fi
+
+# ── D.2 internal namespace consistency(stories sibling check,BLOCK)──────────
+case "$FILE_PATH" in
+  *.stories.tsx)
+    NEW_NS=$(printf '%s' "$NEW_CONTENT" | grep -oE "title:[[:space:]]*['\"]Design System/(Components|Internal)/" | head -1 | grep -oE "(Components|Internal)" || true)
+    if [ -z "$NEW_NS" ] && [ -f "$FILE_PATH" ]; then
+      NEW_NS=$(grep -oE "title:[[:space:]]*['\"]Design System/(Components|Internal)/" "$FILE_PATH" 2>/dev/null | head -1 | grep -oE "(Components|Internal)" || true)
+    fi
+    if [ -n "$NEW_NS" ]; then
+      DIR=$(dirname "$FILE_PATH")
+      INCONSISTENT=""
+      while IFS= read -r SIB; do
+        [ "$SIB" = "$FILE_PATH" ] && continue
+        [ -f "$SIB" ] || continue
+        SIB_NS=$(grep -oE "title:[[:space:]]*['\"]Design System/(Components|Internal)/" "$SIB" 2>/dev/null | head -1 | grep -oE "(Components|Internal)" || true)
+        if [ -n "$SIB_NS" ] && [ "$SIB_NS" != "$NEW_NS" ]; then
+          INCONSISTENT="${INCONSISTENT}  - ${SIB} → ${SIB_NS}"$'\n'
+        fi
+      done < <(find "$DIR" -maxdepth 1 -name '*.stories.tsx' 2>/dev/null)
+      if [ -n "$INCONSISTENT" ]; then
+        cat >&2 <<EOF
+
+┄┄┄ D.2 check_naming_and_abstraction — sibling stories namespace BLOCKER ┄┄┄
+
+[P0] ${FILE_PATH} → ${NEW_NS}
+Sibling stories 不一致:
+${INCONSISTENT}
+3 stories(展示 / anatomy / principles)title namespace 必全 Components/ 或全 Internal/。
+
+決策:跑 CLAUDE.md「Internal vs Components 3-test」→ 把全 3 檔統一。
+
+EOF
+        record_worst 2
+      fi
+    fi
+    ;;
+esac
+
+# ── D.3 primitive color var in tsx(P1 WARN stderr only)──────────────────────
+case "$FILE_PATH" in
+  *.tsx)
+    case "$FILE_PATH" in
+      */components/Tag/*|*/components/Avatar/*|*/components/Chart/*|*/tokens/*) ;; # codified primitive-consumer skip
+      *)
+        if ! echo "$NEW_CONTENT" | grep -q 'primitive-color-allow-blanket'; then
+          VIOLATIONS_D3=$(printf '%s' "$NEW_CONTENT" | grep -nE 'var\(--color-[a-z]+-[0-9](-opaque)?\)' | grep -v 'primitive-color-allow' || true)
+          if [ -n "$VIOLATIONS_D3" ]; then
+            cat >&2 <<EOF
+
+┄┄┄ D.3 check_naming_and_abstraction — primitive color var WARN ┄┄┄
+
+[P1] ${FILE_PATH}
+tsx 內直接消費 primitive token \`var(--color-*-N)\`:
+${VIOLATIONS_D3}
+
+⚠️  Token 命名 rule 4:禁 primitive 色名作 utility,用 semantic alias。
+修法 3 擇 1:
+  1. 加 semantic alias 在 tokens/color/semantic.css(consumer 用 semantic)
+  2. 既有 semantic 已存在 → \`var(--border)\` / \`var(--bg-disabled)\`
+  3. 例外(Tag / Avatar / Chart 自動 allowed): \`// @primitive-color-allow: <reason>\` 行尾豁免
+
+詳 tokens/color/color.spec.md「架構流派定位」+「Primitive 色票與 Tag / Avatar 的消費」。
+
+EOF
+          fi
+        fi
+        ;;
+    esac
+    ;;
+esac
+
+exit $WORST

package/ds-canonical/hooks/check_opacity_token_usage.sh

@@ -0,0 +1,149 @@
+#!/bin/bash
+set -uo pipefail
+# Tailwind token registry enforcement hook(2026-05-18 升級 per audit Dim 47 + codex P1-5):
+#   原 hook 名 `check_opacity_token_usage.sh`(keep filename for settings.json registration),
+#   實際 logic 已升級成 full Tailwind utility registry compliance(per Dim 47 SSOT)。
+#
+# SSOT source:`packages/design-system/src/tokens/utility-registry.json`(block list per category)。
+# 對齊 Atlassian @atlaskit/tokens / Carbon @carbon/themes / Ant ConfigProvider / Polaris polaris-tokens
+# token-first lint enforcement。
+#
+# 檢的 block category:
+#   - opacity:opacity-{5..95} numeric tier(原 logic,保留)
+#   - typography:text-{xs..9xl} / font-{thin|light|semibold|black} / leading-{N} numeric / tracking-{wide..widest|tighter|tight}
+#   - radius:rounded-{xl|2xl|3xl} / rounded(unscoped)
+#   - elevation:shadow-{sm|md|lg|xl|2xl|inner} / shadow(unscoped)
+#   - shadcn alias:bg-popover / text-muted-foreground / bg-accent 等
+#   - primitive 色名:bg-neutral-N / text-blue-N 等(越過 semantic 層)
+#
+# 例外:utility-registry.json `_meta.exceptions` 段定義的 anatomy stories / principles code blocks 豁免
+#       (本 hook 已 skip *.anatomy.stories.tsx / *.principles.stories.tsx 不檢)
+#
+# 修法:reuse semantic utility / token reference / var() bracket(詳 utility-registry.json `rationale_path`)。
+
+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
+
+# Scope:.tsx + .css(DS source);skip stories / tests / token spec 自家 / anatomy/principles per registry exception
+case "$FILE_PATH" in
+  *.tsx|*.css) ;;
+  *) exit 0 ;;
+esac
+case "$FILE_PATH" in
+  # 註解:anatomy + principles stories per utility-registry.json `_meta.exceptions` 豁免
+  *.anatomy.stories.tsx|*.principles.stories.tsx) exit 0 ;;
+  *.stories.tsx|*.test.*|*.spec.tsx) exit 0 ;;
+  *tokens/opacity/*|*tokens/typography/*|*tokens/radius/*|*tokens/elevation/*|*tokens/color/*) exit 0 ;;
+esac
+
+NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // .tool_input.new_string // ""')
+[ -z "$NEW_CONTENT" ] && exit 0
+
+# Resolve registry path(absolute via $CLAUDE_PROJECT_DIR or relative fallback)
+REGISTRY="${CLAUDE_PROJECT_DIR:-}/packages/design-system/src/tokens/utility-registry.json"
+if [ ! -f "$REGISTRY" ]; then
+  # Fallback: try relative from hook dir
+  REGISTRY="$(dirname "$0")/../../packages/design-system/src/tokens/utility-registry.json"
+fi
+if [ ! -f "$REGISTRY" ]; then
+  # 沒 registry → fall back 到原 opacity-only logic(避免 hook 啞掉)
+  HITS=$(echo "$NEW_CONTENT" | grep -oE "opacity-[0-9]+" | grep -vE "^opacity-(0|100)$" | sort -u || true)
+  if [ -n "$HITS" ]; then
+    echo "" >&2
+    echo "⚠️  M23 violation(opacity tier;registry 不可用,fallback mode):" >&2
+    echo "$HITS" | sed 's/^/     /' >&2
+    echo "" >&2
+    echo "   reuse opacity-disabled / alpha 色階。詳 tokens/opacity/opacity.spec.md" >&2
+  fi
+  exit 0
+fi
+
+# Aggregate violations across all categories
+VIOLATIONS=""
+
+# 1) Opacity numeric tier(opacity-5..95,除 0/100/disabled)
+HITS_OPACITY=$(echo "$NEW_CONTENT" | grep -oE "\bopacity-[0-9]+\b" | grep -vE "^opacity-(0|100)$" | sort -u || true)
+if [ -n "$HITS_OPACITY" ]; then
+  VIOLATIONS="${VIOLATIONS}\n   [opacity] $(echo "$HITS_OPACITY" | tr '\n' ' ')"
+fi
+
+# 2) Typography raw size(text-xs..9xl)— skip semantic text-h*/text-body/text-caption/text-helper/text-label
+HITS_TEXT=$(echo "$NEW_CONTENT" | grep -oE "\btext-(xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl)\b" | sort -u || true)
+if [ -n "$HITS_TEXT" ]; then
+  VIOLATIONS="${VIOLATIONS}\n   [typography size] $(echo "$HITS_TEXT" | tr '\n' ' ')"
+fi
+
+# 3) Typography raw weight
+HITS_FONT=$(echo "$NEW_CONTENT" | grep -oE "\bfont-(thin|extralight|light|semibold|extrabold|black)\b" | sort -u || true)
+if [ -n "$HITS_FONT" ]; then
+  VIOLATIONS="${VIOLATIONS}\n   [typography weight] $(echo "$HITS_FONT" | tr '\n' ' ')"
+fi
+
+# 4) Leading numeric(leading-N where N is digit;skip leading-compact/normal/none/tight/snug/relaxed/loose)
+HITS_LEADING=$(echo "$NEW_CONTENT" | grep -oE "\bleading-[0-9]+\b" | sort -u || true)
+if [ -n "$HITS_LEADING" ]; then
+  VIOLATIONS="${VIOLATIONS}\n   [leading numeric] $(echo "$HITS_LEADING" | tr '\n' ' ')"
+fi
+
+# 5) Tracking raw(skip tracking-shortcut canonical token)
+HITS_TRACKING=$(echo "$NEW_CONTENT" | grep -oE "\btracking-(tighter|tight|wide|wider|widest)\b" | sort -u || true)
+if [ -n "$HITS_TRACKING" ]; then
+  VIOLATIONS="${VIOLATIONS}\n   [tracking raw] $(echo "$HITS_TRACKING" | tr '\n' ' ')"
+fi
+
+# 6) Radius out-of-range
+HITS_RADIUS=$(echo "$NEW_CONTENT" | grep -oE "\brounded-(xl|2xl|3xl)\b" | sort -u || true)
+if [ -n "$HITS_RADIUS" ]; then
+  VIOLATIONS="${VIOLATIONS}\n   [radius out-of-range] $(echo "$HITS_RADIUS" | tr '\n' ' ')"
+fi
+
+# 7) Shadow Tailwind size(shadow-sm/md/lg/xl/2xl/inner — DS 用 shadow-[var(--elevation-N)] N∈{100,200,300})
+HITS_SHADOW=$(echo "$NEW_CONTENT" | grep -oE "\bshadow-(sm|md|lg|xl|2xl|inner)\b" | sort -u || true)
+if [ -n "$HITS_SHADOW" ]; then
+  VIOLATIONS="${VIOLATIONS}\n   [elevation size] $(echo "$HITS_SHADOW" | tr '\n' ' ')"
+fi
+
+# 8) Shadcn compat alias(bg-popover / text-muted-foreground 等)
+HITS_SHADCN=$(echo "$NEW_CONTENT" | grep -oE "\b(bg-popover|text-popover-foreground|text-muted-foreground|bg-accent|text-accent-foreground|bg-destructive|bg-background|text-background|border-input)\b" | sort -u || true)
+if [ -n "$HITS_SHADCN" ]; then
+  VIOLATIONS="${VIOLATIONS}\n   [shadcn alias] $(echo "$HITS_SHADCN" | tr '\n' ' ')"
+fi
+
+# 9) Primitive 色名作 utility(bg-neutral-N / text-blue-N 等)
+HITS_PRIMITIVE=$(echo "$NEW_CONTENT" | grep -oE "\b(bg|text|border)-(neutral|blue|red|green|yellow|orange|purple|pink|cyan|teal|deep-orange|deep-purple|light-blue|light-green|lime|amber|indigo|brown|gray)-[0-9]+\b" | sort -u || true)
+if [ -n "$HITS_PRIMITIVE" ]; then
+  VIOLATIONS="${VIOLATIONS}\n   [primitive color as utility] $(echo "$HITS_PRIMITIVE" | tr '\n' ' ')"
+fi
+
+if [ -n "$VIOLATIONS" ]; then
+  cat >&2 <<'EOF_HEAD'
+
+⚠️  M23 / Dim 47 violation:Tailwind utility 繞 SSOT registry。
+EOF_HEAD
+  echo -e "$VIOLATIONS" >&2
+  cat >&2 <<'EOF_BODY'
+
+   SSOT:packages/design-system/src/tokens/utility-registry.json(block list per category)
+   修法 quick map:
+     text-xs..9xl  → text-h1..h6 / text-body / text-caption / text-helper / text-label
+     font-thin/...black → font-normal / font-medium / font-bold
+     leading-{N}   → leading-compact / leading-normal
+     tracking-*    → tracking-shortcut(or codify role-specific semantic utility)
+     rounded-xl..  → rounded-xs..rounded-lg / rounded-full
+     shadow-sm..   → shadow-[var(--elevation-100)] / shadow-[var(--elevation-200)]
+     bg-popover .. → direct semantic token(--surface-raised / --fg-muted / --error 等)
+     bg-neutral-N  → semantic utility(bg-surface 等)或 bg-[var(--color-neutral-N)]
+
+   詳 utility-registry.json `_meta.spec_sources` + M23「DS 內既有 canonical 優先」。
+EOF_BODY
+fi
+
+exit 0

package/ds-canonical/hooks/check_pattern_invariants.sh

@@ -0,0 +1,194 @@
+#!/bin/bash
+# Pattern invariants unified hook(2026-05-08 cluster C consolidation)
+#
+# Merges 4 PreToolUse hooks(原各檔已 retire,合併入此):
+#   C.1 overlay panel scroll chain(原 check_overlay_panel_scroll_chain,P1 WARN stderr)
+#   C.2 inline-action canonical gap(原 check_inline_action_canonical_gap,P1 WARN stderr)
+#   C.3 primitive wrapper padding(原 check_primitive_wrapper_padding,P0 BLOCK exit 2)
+#   C.4 row slot handcraft(原 check_row_slot_handcraft,P0 BLOCK exit 2)
+#
+# Why merge:皆 element-anatomy / overlay-surface SSOT 消費紀律 invariant,共用 INPUT
+# parsing + tsx filter,散裝是 M17 + Anthropic ≤ 15 hook best-practice 偏離。
+#
+# Exit precedence:BLOCK(2)> WARN-stderr(0)。每 rule 獨立 fire,worst 勝。
+#
+# Per-rule allowlist:
+#   C.1: `// @scroll-chain-allow: <reason>`(any line)
+#   C.2: `// @inline-action-gap-allow: <reason>`(any line)
+#   C.3: `// @primitive-padding-allow: <reason>`(檔案前 5 行)
+#   C.4: `// @row-slot-handcraft-allow: <reason>`(any line)
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo 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 "")
+
+[ -z "${NEW_CONTENT//[[:space:]]/}" ] && exit 0
+
+WORST=0
+record_worst() { local lvl=$1; [ "$lvl" -gt "$WORST" ] && WORST=$lvl; }
+
+# ── C.1 overlay panel scroll chain(P1 WARN stderr only)──────────────────────
+if ! echo "$NEW_CONTENT" | grep -q '@scroll-chain-allow' \
+   && echo "$NEW_CONTENT" | grep -q '<SurfaceBody'; then
+  SUSPECT_C1=$(printf '%s' "$NEW_CONTENT" | awk '
+    /^[[:space:]]*<div[[:space:]]/ {
+      line = $0
+      while (index(line, ">") == 0 && (getline next_line) > 0) line = line " " next_line
+      if (line ~ /w-\[/ && (line !~ /flex[^"]*flex-col/ || line !~ /h-full/ || line !~ /min-h-0/)) {
+        for (k = 0; k < 30 && (getline next_line) > 0; k++) {
+          if (next_line ~ /<SurfaceBody/) {
+            print "[panel root w-[...] 缺 flex flex-col h-full min-h-0]: " substr(line, 1, 100)
+            break
+          }
+          if (next_line ~ /<\/div>/) break
+        }
+      }
+    }
+  ')
+  if [ -n "$SUSPECT_C1" ]; then
+    cat >&2 <<EOF
+
+┄┄┄ C.1 check_pattern_invariants — overlay scroll chain WARN ┄┄┄
+
+[P1] ${FILE_PATH}
+${SUSPECT_C1}
+
+⚠️  M25 canonical:Popover/HoverCard/Dialog/Sheet viewport-aware scroll 要求 root → SurfaceBody
+    所有中間 wrapper forward \`flex flex-col h-full\`。斷鏈 → SurfaceBody flex-1 失效。
+
+修法:wrapper className 加 \`flex flex-col h-full\`(最小組合 \`flex flex-col h-full min-h-0\`)
+詳 patterns/overlay-surface/overlay-surface.spec.md「Viewport-aware scroll chain invariant」/ M25
+例外:行尾 \`// @scroll-chain-allow: <reason>\`
+
+EOF
+  fi
+fi
+
+# ── C.2 inline-action canonical gap(P1 WARN stderr only)─────────────────────
+case "$FILE_PATH" in
+  *components/*.tsx|*patterns/*.tsx)
+    case "$FILE_PATH" in
+      */item-anatomy.tsx|*.stories.tsx|*.test.*) ;; # SSOT/test skip
+      *)
+        if ! echo "$NEW_CONTENT" | grep -q '@inline-action-gap-allow' \
+           && echo "$NEW_CONTENT" | grep -qE '<ItemInlineAction(Button)?\b|DropdownMenuTrigger.*ItemInlineAction'; then
+          WRONG_GAP=$(echo "$NEW_CONTENT" | grep -nE 'className=.*\bgap-(1|3|4|5|6|8|10|12)\b' | head -3 || true)
+          if [ -n "$WRONG_GAP" ]; then
+            cat >&2 <<EOF
+
+┄┄┄ C.2 check_pattern_invariants — inline-action gap WARN ┄┄┄
+
+[P1] ${FILE_PATH}
+ItemInlineAction* consumer 用非 \`gap-2\` 的 gap class:
+${WRONG_GAP}
+
+⚠️  inline-action.spec.md:80:inline-action 跟 sibling gap 必 \`gap-2\`(8px)。
+    12px = --table-cell-px(cell L/R padding,不是 inline-action gap)。
+
+修法:className gap → gap-2 / 加 \`// @inline-action-gap-allow: <reason>\` 行尾豁免
+
+EOF
+          fi
+        fi
+        ;;
+    esac
+    ;;
+esac
+
+# ── C.3 primitive wrapper padding(P0 BLOCK exit 2)───────────────────────────
+# File-level allowlist:檔頭前 5 行
+ALLOW_C3=0
+FIRST_LINES_NEW=$(printf '%s\n' "$NEW_CONTENT" | sed -n '1,5p')
+echo "$FIRST_LINES_NEW" | grep -qE '//[[:space:]]*@primitive-padding-allow:' && ALLOW_C3=1
+if [ -f "$FILE_PATH" ] && [ "$ALLOW_C3" = "0" ]; then
+  ON_DISK_FIRST=$(sed -n '1,5p' "$FILE_PATH" 2>/dev/null || true)
+  echo "$ON_DISK_FIRST" | grep -qE '//[[:space:]]*@primitive-padding-allow:' && ALLOW_C3=1
+fi
+if [ "$ALLOW_C3" = "0" ]; then
+  PRIMITIVES_REGEX='DateGrid|Calendar|Surface|SurfaceHeader|SurfaceBody|SurfaceFooter'
+  VIOLATIONS_C3=$(printf '%s' "$NEW_CONTENT" | perl -0777 -ne '
+    while (/<div\b[^>]*className\s*=\s*["\x27`][^"\x27`]*\bp-\d+[^"\x27`]*["\x27`][^>]*>(?:[^<]*<(?!\/div\b)){0,8}\s*<('"$PRIMITIVES_REGEX"')\b/gs) {
+      my $primitive = $1;
+      my $offset = $-[0];
+      my $before = substr($_, 0, $offset);
+      my $line = ($before =~ tr/\n//) + 1;
+      print "line $line: <div className=\"...p-X...\"> wrapping <$primitive>\n";
+    }
+  ')
+  if [ -n "$VIOLATIONS_C3" ]; then
+    cat >&2 <<EOF
+
+┄┄┄ C.3 check_pattern_invariants — primitive wrapper padding BLOCKER ┄┄┄
+
+[P0] ${FILE_PATH}
+${VIOLATIONS_C3}
+
+SSOT primitive 自帶 outer padding,**consumer 不得另加 padding wrapper**:
+  - DateGrid / Calendar:root 自帶 p-3
+  - Surface{Header,Body,Footer}:各 segment 自帶 padding
+
+修法:直接放 primitive,不包 padding div。
+  ❌ <div className="p-2"><DateGrid /></div>
+  ✅ <DateGrid />
+
+整檔豁免:檔頭前 5 行加 \`// @primitive-padding-allow: <reason>\`(需 spec rationale)。
+詳 mindset #2 + M1 SSOT 消費。
+
+EOF
+    record_worst 2
+  fi
+fi
+
+# ── C.4 row slot handcraft(P0 BLOCK exit 2)──────────────────────────────────
+case "$FILE_PATH" in
+  *components/*.tsx|*patterns/*.tsx)
+    case "$FILE_PATH" in
+      */item-anatomy.tsx|*/field-wrapper.tsx|*.stories.tsx|*.test.*|*.spec.tsx) ;; # SSOT/test skip
+      *)
+        if ! echo "$NEW_CONTENT" | grep -q '@row-slot-handcraft-allow' \
+           && echo "$NEW_CONTENT" | grep -E 'h-\[1lh\][^"]*shrink-0[^"]*flex[^"]*items-center|shrink-0[^"]*h-\[1lh\][^"]*flex[^"]*items-center|flex[^"]*items-center[^"]*h-\[1lh\][^"]*shrink-0' >/dev/null; then
+          cat >&2 <<EOF
+
+┄┄┄ C.4 check_pattern_invariants — row slot handcraft BLOCKER ┄┄┄
+
+[P0] ${FILE_PATH}
+偵測自刻 row-layout slot:\`<span class="h-[1lh] shrink-0 flex items-center...">\`
+M1+M17 違反 — 該消費 L1 primitive。
+
+⚠️  M19 canonical(2026-05-05 v8):row prefix/suffix slot 必走 patterns/element-anatomy:
+  import { ItemPrefix, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
+  <ItemPrefix><StartIcon /></ItemPrefix>
+  <ItemSuffix>{chevron}</ItemSuffix>
+
+\`<ItemPrefix>\` / \`<ItemSuffix>\` 永遠 \`h-[1lh] shrink-0 flex items-center\`(item-anatomy.spec.md:175+190)。
+例外:行尾 \`// @row-slot-handcraft-allow: <reason>\`
+
+EOF
+          record_worst 2
+        fi
+        ;;
+    esac
+    ;;
+esac
+
+exit $WORST

package/ds-canonical/hooks/check_peoplepicker_ssot_drift.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+set -uo pipefail
+# PreToolUse Edit/Write: PeoplePicker SSOT drift guard(2026-05-15 user verbatim「避免下次再度偏移」)
+#
+# 攔截:`people-picker.tsx` / `person-display.tsx` / `combobox.tsx` 動以下 PeoplePicker SSOT-bearing
+# code 路徑時,要求 commit message / new content 包含 cite 對應 spec.md SSOT table row 的 marker。
+#
+# 規則 SSOT:`packages/design-system/src/components/PeoplePicker/people-picker.spec.md` §A-§F canonical table
+# (Trigger display SSOT canonical table)。
+#
+# 警告(non-blocking):新內容含「動 SSOT-bearing API」但無 spec 引用 → stderr 警告,要求自查對應 row。
+# Hard block 場景不適用(spec 偏移由 user 決定走 RFC 或直接修)。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // empty')
+
+[ -z "$FILE_PATH" ] && exit 0
+
+# Only check Edit/Write on PeoplePicker SSOT-bearing files
+case "$FILE_PATH" in
+  */PeoplePicker/people-picker.tsx|*/PeoplePicker/person-display.tsx|*/Combobox/combobox.tsx) ;;
+  *) exit 0 ;;
+esac
+
+# Patterns that touch SSOT-bearing render logic
+SSOT_KEYWORDS='tagRenderer|overflowShape|tagWrapperClassName|selectedItemRenderer|MultiPersonDisplay|PersonAvatarTag|PersonDisplay|searchIn|searchPlaceholder|placeholder=\\{'
+
+if echo "$NEW_CONTENT" | grep -qE "$SSOT_KEYWORDS"; then
+  # Check if new content cites spec.md SSOT table
+  if ! echo "$NEW_CONTENT" | grep -qE "(spec\\.md.*(§[A-F]|canonical table|Trigger display SSOT)|people-picker\\.spec\\.md.*L9[0-9])"; then
+    MSG="⚠️ PeoplePicker SSOT-bearing edit detected at ${FILE_PATH}
+
+動到 (tagRenderer / overflowShape / tagWrapperClassName / placeholder logic / MultiPersonDisplay 等) — 這些是 PeoplePicker SSOT-bearing API,不是 Combobox / Select 純繼承。
+
+必先 cite \`people-picker.spec.md\` §A-§F canonical table 對應 row,確認改動跟 SSOT 一致。違反 = 元件視覺漂移(2026-05-15 user verbatim「為什麼辯論之後會完全被 codex 帶走」+ 「避免下次再度偏移」)。
+
+對應 SSOT row 速查:
+  §A 元件本質繼承表 - 動繼承關係 / 視覺自定義 → 此處
+  §B 單人 trigger 5 state - 動 single mode render → 此處
+  §C 多人 length=1 trigger 3 state - 動 length=1 降階單人視覺 → 此處
+  §D 多人 length≥2 trigger 4 state - 動 stack overlap / +N 圓形 / inline-search cursor → 此處
+  §E 共享 SSOT - 動 avatar inset 12px / PersonDisplay / placeholder ellipsis → 此處
+  §F Cell-edit ↔ Field-edit 一致性 - 動 cell-registry MultiPersonCell / form PeoplePicker → 此處"
+
+    ESCAPED=$(printf '%s' "$MSG" | jq -Rs .)
+    printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":%s}}\n' "$ESCAPED"
+  fi
+fi
+
+exit 0

package/ds-canonical/hooks/check_pixel_quantified_audit.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# check_pixel_quantified_audit.sh — M32(a) pixel-quantified verify mechanical guardrail
+#
+# Per M32(2026-05-12 user 抓「audit ALL PASS 但 user 看視覺仍 broken」連環事件 4 RC absorbed):
+#   audit script 必驗 `rect.top / .left / .height` numeric pixel position,**不**可只驗
+#   `getAttribute('data-state')` / `class.includes('items-start')` attribute-existence
+#   = false-positive trap(DOM-structure-pass ≠ visual-pass)。
+#
+# Mechanical rule:scripts/visual-audit-*.mjs(or *.js)若有 `getAttribute(` 但沒 paired
+# `getBoundingClientRect(` 或 `offsetTop/.offsetHeight` 量化 measurement → warn。
+#
+# 對齊 Material X-DataGrid visual regression / AG Grid playwright pixel snapshot canonical。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+INPUT=$(cat 2>/dev/null || echo "{}")
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+
+case "$TOOL" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
+case "$FILE_PATH" in
+  */scripts/visual-audit-*.mjs|*/scripts/visual-audit-*.js) ;;
+  *) exit 0 ;;
+esac
+[ "$EVENT" != "PostToolUse" ] && exit 0
+[ ! -f "$FILE_PATH" ] && exit 0
+
+# Allowlist
+head -3 "$FILE_PATH" | grep -qE '//[[:space:]]*@pixel-quantified-allow:' && exit 0
+
+# Count getAttribute calls vs getBoundingClientRect / offsetTop / offsetHeight calls
+# 2026-05-23 bug fix:`grep -c ... 2>/dev/null || echo 0` 當 zero match 時 grep exit 1 + fallback echo,
+# 產生 multi-line "0\n0" string,下游 [ "$X" -eq 0 ] arithmetic 報「integer expression expected」silent skip。
+# 修法:grep 不用 fallback,直接保證輸出 numeric(strip 非數字)+ default 0。
+ATTR_HITS=$(grep -cE 'getAttribute\(|\.hasAttribute\(' "$FILE_PATH" 2>/dev/null)
+ATTR_HITS="${ATTR_HITS//[^0-9]/}"; ATTR_HITS=${ATTR_HITS:-0}
+PIXEL_HITS=$(grep -cE 'getBoundingClientRect\(|\.offsetTop\b|\.offsetHeight\b|\.offsetLeft\b|\.offsetWidth\b' "$FILE_PATH" 2>/dev/null)
+PIXEL_HITS="${PIXEL_HITS//[^0-9]/}"; PIXEL_HITS=${PIXEL_HITS:-0}
+
+if [ "$ATTR_HITS" -gt 0 ] && [ "$PIXEL_HITS" -eq 0 ]; then
+  CTX="⚠️ M32(a) pixel-quantified verify gap:
+${FILE_PATH}:
+  - getAttribute / hasAttribute calls: ${ATTR_HITS}
+  - getBoundingClientRect / offsetTop calls: 0
+  → audit 驗 attribute 但沒驗 pixel position = M32 違反(DOM-pass ≠ visual-pass)。
+    加 numeric pixel measurement(rect.top / .left / .height)真實 verify 視覺,
+    或檔首加 // @pixel-quantified-allow: <reason>(structural-only audit 例如 schema check)。"
+  jq -n --arg ctx "$CTX" '{
+    hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: $ctx }
+  }'
+fi