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

package/ds-canonical/fork/hooks/check_layout_space_magic_numbers.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# check_layout_space_magic_numbers.sh — P0 BLOCKER
+#
+# 偵測 consumer / DS app code 用 Tailwind spacing magic numbers
+# (`p-4` / `px-6` / `py-2` / `gap-3` 等)而非 layoutSpace token
+# (`p-[var(--layout-space-N) N∈{loose,tight}]` / `gap-[var(--layout-space-N) N∈{loose,tight}]`)。
+# 2026-05-27 user verbatim「機械無強制就不會做?那為何不全部 ssot 都要強制吻合?」
+# 永久 codify — SSOT canonical 必 P0 BLOCKER,不分級。
+#
+# Anchor:user 質疑「content 自動繼承 layoutSpace SSOT 嗎?」
+# - app-shell.spec.md:205 明文 `<main>` landmark padding=0 (intentional)
+# - app-shell.spec.md:207-212 consumer 必遵循 layoutSpace.spec.md 6 條規則 + 親疏 3 級
+#
+# PostToolUse Edit/Write detect magic Tailwind spacing → P0 BLOCKER exit 2
+# 強制改 token OR 加 `// @layout-space-magic-ok: <rationale>` escape comment(per-line)。
+
+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 // .tool_input.notebook_path // ""' 2>/dev/null)
+
+# Only check .tsx / .ts in app code
+if ! echo "$FILE" | grep -qE '\.(tsx|ts)$'; then exit 0; fi
+# Skip DS source (DS components have their own spacing logic via cva)
+if echo "$FILE" | grep -qE 'packages/design-system/src/|node_modules/'; then exit 0; fi
+
+# Get new content
+NEW_CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null)
+[ -z "$NEW_CONTENT" ] && exit 0
+
+# Escape clause:single line escape comment per line of magic number usage
+# `// @layout-space-magic-ok: <rationale>` immediately above the line OR on same line
+ESCAPE_MARKER='@layout-space-magic-ok:'
+
+# Detect magic spacing classes (Tailwind class strings only — NOT JSX props like size={24})
+# Match per line so we can check per-line escape comments
+MAGIC_LINES=$(echo "$NEW_CONTENT" | grep -nE '\b(p|px|py|pt|pb|pl|pr|gap|space-x|space-y|m|mx|my|mt|mb|ml|mr)-(0\.5|[1-9][0-9]?(\.[0-9])?)\b')
+
+if [ -z "$MAGIC_LINES" ]; then
+  exit 0
+fi
+
+# Filter out lines with escape marker on same line OR immediately preceding line
+# 2026-06-03 修(doc-vs-code bug,M32):L41 文件宣稱支援「preceding line OR same line」,
+# 但原 code 只檢查同行 → JSX className 行無法放同行 `//` comment(會破壞 JSX)→ escape 對 JSX
+# 實質失效。補實作前一行檢查(grep -n 行號 → sed 取前一行),對齊文件 + 解 JSX 必需。
+UNJUSTIFIED=""
+while IFS= read -r line; do
+  # same-line marker
+  if echo "$line" | grep -qF "$ESCAPE_MARKER"; then continue; fi
+  # preceding-line marker(JSX `{/* @layout-space-magic-ok: ... */}` 在上一行)。
+  # 對齊 ESLint disable-next-line 慣例:前一行 marker 僅在該行是「註解專用行」(trimmed 開頭
+  # //、{/*、/*、*)時生效 — 否則上一行 code 的「同行 escape」會誤串到下一行(P8 conflict)。
+  lineno="${line%%:*}"
+  if [ "$lineno" -gt 1 ] 2>/dev/null; then
+    prev=$(echo "$NEW_CONTENT" | sed -n "$((lineno-1))p")
+    if echo "$prev" | grep -qF "$ESCAPE_MARKER" && echo "$prev" | grep -qE '^[[:space:]]*(//|\{?/\*|\*)'; then continue; fi
+  fi
+  UNJUSTIFIED="${UNJUSTIFIED}${line}\n"
+done <<< "$MAGIC_LINES"
+
+if [ -z "$UNJUSTIFIED" ]; then
+  exit 0
+fi
+
+cat >&2 << EOF
+🚨 LAYOUT-SPACE-MAGIC-NUMBER BLOCKER(P0,2026-05-27 user verbatim「機械無強制就不會做?
+為何不全部 ssot 都要強制吻合?」永久 codify)
+
+  Detected Tailwind spacing magic numbers in $FILE without escape:
+$(echo -e "$UNJUSTIFIED" | sed 's/^/    /' | head -10)
+
+  per app-shell.spec.md L205-219 + layoutSpace.spec.md SSOT:consumer content 必遵循
+  layoutSpace 6 條規則 + 親疏 3 級,**禁** 硬寫 Tailwind magic numbers。改用:
+    p-[var(--layout-space-loose)]      /* 16px 規則 1A/1B chrome / wrap */
+    p-[var(--layout-space-tight)]      /* 12px 規則 3 親 gap */
+    gap-[var(--layout-space-distant)]  /* 24px 規則 3 疏 gap */
+    space-y-[var(--layout-space-distant)]
+
+  修法 2 選 1:
+    (a) 改 token:換成 var(--layout-space-N) N∈{loose,tight} family per 6 規則 + 親疏 3 級
+    (b) Escape:在該 line 加 \`// @layout-space-magic-ok: <rationale>\` 顯式 documented
+        (eg.「\`gap-1\` 是 4px stack icon — non-spacing context,not consumer layout」)
+
+  完整 6 條規則 → packages/design-system/src/tokens/layoutSpace/layoutSpace.spec.md
+EOF
+exit 2

package/ds-canonical/fork/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:`node_modules/@qijenchen/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:-}/node_modules/@qijenchen/design-system/src/tokens/utility-registry.json"
+if [ ! -f "$REGISTRY" ]; then
+  # Fallback: try relative from hook dir
+  REGISTRY="$(dirname "$0")/../../node_modules/@qijenchen/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:node_modules/@qijenchen/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/fork/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/fork/hooks/check_sidebar_menu_button_implicit_wrap.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+# check_sidebar_menu_button_implicit_wrap.sh — PreToolUse Edit/Write 攔 SidebarMenuButton 沒 asChild + children 含 ItemAvatar/Avatar/Icon 致隱式 wrap 垂直 stack(2026-05-27)
+#
+# Per user 2026-05-27 抓 UserFooter Avatar 垂直 stack drift:
+#   SidebarMenuButton(sidebar.tsx L1036-1043)在沒 asChild 時把所有 children 塞進 <ItemLabel> 單一 span,
+#   Avatar + text-span 都在同 span 內 → 強迫垂直堆疊。
+#
+# Canonical:含 Avatar/ItemAvatar/icon prefix 的 SidebarMenuButton 必用 asChild + <div> wrap,
+#   per sidebar.tsx:1025-1027 docblock:「asChild 的 consumer 自行放 icon + label」+ DS canonical
+#   sidebar.stories.tsx#UserFooter 範例 L76-104。
+#
+# Detection:
+#   `<SidebarMenuButton ...>` (no asChild) ... `<ItemAvatar` or `<Avatar` inside → BLOCKER
+#   ALLOW:`<SidebarMenuButton startIcon={X}>label</SidebarMenuButton>`(用 startIcon prop 不 wrap)
+#   ALLOW:`<SidebarMenuButton asChild>...</SidebarMenuButton>`(consumer 自管 layout)
+
+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)
+NEW=$(echo "$INPUT" | jq -r '.tool_input.content // .tool_input.new_string // ""' 2>/dev/null)
+
+[ "$EVENT" != "PreToolUse" ] && exit 0
+case "$TOOL" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
+case "$FILE_PATH" in *.tsx) ;; *) exit 0 ;; esac
+case "$FILE_PATH" in *.test.tsx) exit 0 ;; esac
+
+# Python multiline regex:`<SidebarMenuButton` 不含 `asChild` 的 block + 內含 Avatar/ItemAvatar prefix
+HAS_DRIFT=$(printf '%s' "$NEW" | python3 -c '
+import sys, re
+content = sys.stdin.read()
+# Find SidebarMenuButton blocks(opening tag → closing tag,non-greedy multiline)
+# match opening `<SidebarMenuButton ...>` capture full open tag
+for m in re.finditer(r"<SidebarMenuButton\b([^>]*)>(.*?)</SidebarMenuButton>", content, re.DOTALL):
+    open_tag, body = m.group(1), m.group(2)
+    # Skip if asChild present
+    if re.search(r"\basChild\b", open_tag):
+        continue
+    # Drift = body 含 <ItemAvatar 或 <Avatar(both = avatar prefix)
+    if re.search(r"<(ItemAvatar|Avatar)\b", body):
+        print("DRIFT")
+        sys.exit(0)
+' 2>/dev/null)
+
+[ "$HAS_DRIFT" != "DRIFT" ] && exit 0
+
+# Override env(audit-logged)
+if [ "${CLAUDE_BYPASS_SIDEBAR_MENU_BUTTON_WRAP:-0}" = "1" ]; then
+  mkdir -p "$(dirname "$0")/../logs" 2>/dev/null
+  printf '{"ts":"%s","event":"sidebar-menu-button-wrap-bypass","file":"%s"}\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$FILE_PATH" >> "$(dirname "$0")/../logs/governance-bypass.jsonl" 2>/dev/null
+  exit 0
+fi
+
+REL=${FILE_PATH#"$CLAUDE_PROJECT_DIR"/}
+
+cat >&2 <<'EOF'
+🚨 SidebarMenuButton implicit-wrap canonical violation(per user 2026-05-27 UserFooter 垂直 stack 事件):
+
+🔍 偵測:SidebarMenuButton 內含 ItemAvatar 或 Avatar 但 **無 asChild**
+
+⚠️ 後果(per sidebar.tsx:1036-1043 source code):
+  SidebarMenuButton 沒 asChild → children 全塞進 ItemLabel(單 span)
+  → Avatar + text 在同 span 內 → 強迫垂直堆疊(user 抓的 bug)
+
+修法(per DS canonical sidebar.stories.tsx#UserFooter):
+
+  ❌ SidebarMenuButton id="..." 直接放 ItemAvatar + span 為 children
+
+  ✅ SidebarMenuButton asChild 包 div role="group" 內含 ItemAvatar + span data-sidebar="menu-label" min-w-0 flex-1 truncate
+
+Or use startIcon prop(自動 layout,不 wrap):
+  ✅ SidebarMenuButton startIcon={SomeLucideIcon} 直接 children 為純文字
+
+Bypass(極罕見):CLAUDE_BYPASS_SIDEBAR_MENU_BUTTON_WRAP=1 env var(audit-logged)。
+
+Citation:
+  - packages/design-system/src/components/Sidebar/sidebar.tsx:1025-1043(asChild docblock)
+  - packages/design-system/src/components/Sidebar/sidebar.stories.tsx UserFooter L76-104(canonical)
+EOF
+# 2026-05-31:exit 0 → exit 2(folded-hook-audit:原宣稱 BLOCKER 但 exit 0 = 假 enforcement;
+# SidebarMenuButton implicit-wrap 是 SSOT canonical,verified clean on 現有 sidebar code + 有 env escape)。
+exit 2