@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

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})
+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_orphan_ds_css.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# check_orphan_ds_css.sh — P0 BLOCKER
+#
+# 防 DS CSS file orphan(在 src 但不在 tokens.css aggregator + 沒被任何 tsx import)
+# (2026-05-27 user verbatim「之前不就已經整理過一次 token 了?還沒搞好?那到底還要搞幾次?
+# 你他媽最好給我保證這是最後一次」永久 codify)
+#
+# Anchor 錨點:
+# - 2026-05-26 sidebar-width token 從 globals.css 搬 uiSize.css(part 1 fix)
+# - 但 header-canonical.css / data-table.css 兩個 non-token-home CSS 沒一起 sweep
+# - 兩者都在 globals.css 為 DS internal 載入,但 tokens.css consumer aggregator 漏
+# - Consumer install DS + import @qijenchen/design-system/styles/tokens 拿不到
+#   → sidebar 收合 logo 跑版(--chrome-header-avatar-size missing)+ DataTable cell grid 跑掉
+# - User 抓「sidebar 修了一百次都白做,真 root 在 token bundle pipeline」
+#
+# Stop hook(post-assistant turn)scan packages/design-system/src/**/*.css:
+# Orphan condition:file NOT in tokens.css aggregator AND NOT imported by any tsx/ts in DS
+# → BLOCKER exit 2 強制 fix
+#
+# Defense layer 補 gen-figma-make-artifacts.mjs auto-scan(generator 自動抓,本 hook 額外驗)。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null || echo "{}")
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+
+case "${EVENT:-}" in
+  Stop|SubagentStop) ;;
+  *) exit 0 ;;
+esac
+
+DS_SRC="${CLAUDE_PROJECT_DIR:-.}/packages/design-system/src"
+AGGREGATOR="$DS_SRC/styles/tokens.css"
+
+if [ ! -d "$DS_SRC" ] || [ ! -f "$AGGREGATOR" ]; then
+  exit 0
+fi
+
+ORPHANS=""
+while IFS= read -r css; do
+  rel="${css#$DS_SRC/}"
+  # Skip aggregator itself
+  if [ "$rel" = "styles/tokens.css" ]; then continue; fi
+  # In aggregator?
+  if grep -qF "$rel" "$AGGREGATOR" 2>/dev/null; then continue; fi
+  # Imported by any tsx/ts in DS?
+  basename=$(basename "$css")
+  if grep -rln "import.*${basename}\|@import.*${basename}" "$DS_SRC" --include='*.tsx' --include='*.ts' --include='*.css' 2>/dev/null | grep -v "${css}" | grep -q .; then continue; fi
+  ORPHANS="${ORPHANS}  - $rel\n"
+done < <(find "$DS_SRC" -name '*.css' -type f)
+
+if [ -n "$ORPHANS" ]; then
+  printf '🚨 ORPHAN-DS-CSS BLOCKER(2026-05-27 user 永久糾正「之前不就已經整理過一次 token 了?最後一次」)\n\n' >&2
+  printf '  DS src 內 CSS 既不在 tokens.css aggregator 也不被任何 tsx/ts import:\n' >&2
+  printf '%b' "$ORPHANS" >&2
+  printf '\n  Consumer install DS + import @qijenchen/design-system/styles/tokens 拿不到 → 跑版。\n' >&2
+  printf '  修法 2 選 1:\n' >&2
+  printf '    (a) 加進 tokens.css aggregator(若是 :root token / @theme 宣告):\n' >&2
+  printf '        node scripts/gen-figma-make-artifacts.mjs(自動掃 patterns/+components/)\n' >&2
+  printf '    (b) 在對應 tsx file 加 `import ./xxx.css`(若是 component-internal scoped style)\n' >&2
+  exit 2
+fi
+
+exit 0

package/ds-canonical/hooks/check_overlay_open_focus_escape_probe.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# check_overlay_open_focus_escape_probe.sh — P0 BLOCKER
+#
+# Codex M31 P0 finding 2026-05-27:Overlay canonical rules require open visual
+# states, but active hooks check overlay handcraft/static code only;沒 runtime
+# probe Tooltip/Popover/Dialog/Sheet/DropdownMenu/HoverCard 真 open / focus / Esc.
+#
+# Triggers on consumer apps/**/*.stories.tsx edit. For each story using overlay
+# primitive, verify story contains:
+#   - `defaultOpen` prop OR
+#   - `open={true|isOpen}` controlled state OR
+#   - `play()` interaction function clicking trigger OR
+#   - `// @overlay-open-skip: <rationale>` per-story escape
+# Otherwise story is「trigger-only」= visual snapshot 看不到 overlay content (per
+# Empty-content rendered in sweep,user 2026-05-27 抓「overlay 沒彈出」7-bug 錨點).
+#
+# Scope: consumer storybook + DS canonical anatomy/principles stories.
+
+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)
+
+case "${TOOL:-}" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
+if ! echo "$FILE" | grep -qE '\.stories\.tsx$'; then exit 0; fi
+
+CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null)
+[ -z "$CONTENT" ] && exit 0
+
+# File-level escape
+if echo "$CONTENT" | grep -q '@overlay-open-skip:'; then exit 0; fi
+# HoverCard documented exception (per codex 2026-05-27)
+if echo "$CONTENT" | grep -q '@story-trait-allow:.*missing-opensnapshot'; then exit 0; fi
+
+# Detect overlay primitive usage
+OVERLAY_PRIMITIVES='Tooltip|Popover|Dialog|Sheet|DropdownMenu|HoverCard'
+USED=$(echo "$CONTENT" | grep -oE "<(DS\.)?($OVERLAY_PRIMITIVES)Trigger\b" | sort -u)
+
+if [ -z "$USED" ]; then exit 0; fi
+
+# Detect open-state mechanism
+HAS_OPEN=""
+if echo "$CONTENT" | grep -qE 'defaultOpen|open=\{(true|isOpen|isVisible)|play:\s*async|play\(.*click'; then
+  HAS_OPEN="found"
+fi
+
+if [ -z "$HAS_OPEN" ]; then
+  cat >&2 << EOF
+🚨 OVERLAY-OPEN-PROBE BLOCKER(P0,codex M31 finding 2026-05-27 + user 7-bug 錨點)
+
+  Story $FILE uses overlay primitive trigger but no open-state mechanism:
+$(echo "$USED" | sed 's/^/    /')
+
+  Without defaultOpen / open={true} / play() click, visual snapshot 永遠 看不到
+  overlay content。User 2026-05-27 verbatim「圖四,首先會彈出 overlay 的,感覺都沒
+  正常彈出」.
+
+  修法 2 選 1:
+    (a) 加 \`defaultOpen\` prop OR controlled \`open={true}\` OR Storybook \`play\` interaction
+        click trigger before screenshot
+    (b) Escape per-file:\`// @overlay-open-skip: <rationale>\`(eg. behavior-only
+        test) OR \`// @story-trait-allow: missing-opensnapshot\`(per codex
+        canonical exception list)
+EOF
+  exit 2
+fi
+
+exit 0

package/ds-canonical/hooks/check_pattern_invariants.sh

@@ -0,0 +1,196 @@
+#!/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
+      *)
+        # 2026-05-30(dim 39 M7/M34 fix):order-INDEPENDENT — extract className attrs,require ALL 4 tokens
+        # present(natural Tailwind 序 `flex items-center gap-2 shrink-0 h-[1lh]` 之前漏抓)。BSD/GNU grep 通用。
+        if ! echo "$NEW_CONTENT" | grep -q '@row-slot-handcraft-allow' \
+           && echo "$NEW_CONTENT" | grep -oE 'class(Name)?="[^"]*"' | grep -F 'h-[1lh]' | grep -F 'shrink-0' | grep -F 'flex' | grep -F 'items-center' >/dev/null 2>&1; 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