@qijenchen/design-system 0.1.0-beta.10 → 0.1.0-beta.13

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-*)])
+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

package/ds-canonical/hooks/check_propose_plain_chinese.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# check_propose_plain_chinese.sh — Stop hook: scan AI 本 turn reply 含「要 user 決策」pattern 但用 jargon 違 propose-in-plain-chinese canonical。
+#
+# 對應 SSOT:.claude/memory/feedback_propose_in_plain_chinese.md
+#         + CLAUDE.md `# 自主執行 canonical`「SSOT-UI/UX 中文具體人話」明文
+#
+# User 原話 2026-05-15:「已經跟你說過任何要我決策的東西請講具體人話,為何又跟智障一樣講人聽不懂的話呢?」
+#
+# Mechanism:
+# 1. Tail transcript 取 AI 本 turn 最後 assistant text content
+# 2. Detect 決策 prompt pattern(「回 A / B / C」/「→ 選 A」/「等你拍板」/「user 決策」)
+# 3. Count jargon density(「M[0-9]+」/「Dim [0-9]+」/「SSOT」/「@watch」/「frontmatter」/「stub」/etc)
+# 4. Density > threshold + 含決策 prompt → warn(P1 soft inject)
+#
+# 不 BLOCK turn,只 inject context warning(避免 false-positive 中斷 work)
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+INPUT=$(cat 2>/dev/null || echo "{}")
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null)
+
+[ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ] && exit 0
+
+# 找最新 user msg line 之後的 assistant text(本 turn AI reply)
+LAST_USER_LINE=$(grep -n '"role":"user"' "$TRANSCRIPT_PATH" 2>/dev/null | tail -1 | cut -d: -f1)
+[ -z "$LAST_USER_LINE" ] && exit 0
+
+AI_REPLY_TEXT=$(tail -n +$((LAST_USER_LINE+1)) "$TRANSCRIPT_PATH" 2>/dev/null | \
+  jq -r 'select(.message.role=="assistant") | .message.content // empty | if type=="string" then . else (.[]? | select(.type=="text") | .text // empty) end' 2>/dev/null)
+
+[ -z "$AI_REPLY_TEXT" ] && exit 0
+
+# Decision prompt pattern(reply 結尾含 ASK)
+DECISION_RE='(回 [A-Z]|→ ?選 [A-Z]|等你(拍板|決策|回|看)|user 決策|user 拍板|拍板.{0,5}決|決策.{0,5}選|一字回|回 OK)'
+HAS_DECISION=$(echo "$AI_REPLY_TEXT" | grep -cE "$DECISION_RE" 2>/dev/null)
+HAS_DECISION=${HAS_DECISION:-0}
+
+[ "$HAS_DECISION" -eq 0 ] && exit 0
+
+# GAP 4 fix(2026-05-18 M34 codify):升級 narrow 17-keyword fixed list 到
+# Python unicode 中英夾雜 density detector(對齊 check_story_invariants.sh R5.5 fix template)。
+# Spec wording「任何沒中譯的縮寫 / 內部代號 / hook 名」廣義,hook 過去窄 keyword list 漏:
+# Earn-existence / compound-component / Polaris-aligned / wrapper-vs-primitive / Anchor preflight
+# / *-canonical-allow / L42-58 / check_xxx.sh 等。
+#
+# 升級邏輯:
+# (a) EXEMPT list:legitimate retained-English(framework/brand/DS API)
+# (b) Density measure:jargon-word count / total Chinese-char count ratio
+# (c) jargon = 英文 token 不在 EXEMPT(任何 alphanumeric word ≥ 3 char)
+JARGON_COUNT=$(python3 -c "
+import re, sys
+text = sys.stdin.read()
+EXEMPT = re.compile(r'\b(cva|Radix|Polaris|Material|Atlassian|Carbon|Ant|Apple|MUI|TanStack|shadcn|Recharts|cmdk|dnd-kit|TypeScript|JavaScript|API|UI|UX|Jira|Stripe|Notion|Figma|Linear|GitHub|Gmail|Dropbox|Slack|Spotify|Discord|Storybook|Tailwind|ARIA|WCAG|FAQ|HSL|CSS|HTML|DOM|DS|F[1-9]|TODO|FIXME|XXX|NOTE|README|MIT|JSON|YAML|TSX|CSS|HTTP|HTTPS|URL|UUID|REST|GraphQL|SDK|CDN|CI|CD|PR|RFC|MR|UI/UX|primary|secondary|tertiary|hover|focus|active|disabled|invalid|readonly|null|true|false|undefined|void)\b', re.I)
+words = re.findall(r'\b[a-zA-Z][a-zA-Z\-_]{2,}\b', text)
+jargon = [w for w in words if not EXEMPT.fullmatch(w)]
+print(len(jargon))
+" <<< "$AI_REPLY_TEXT" 2>/dev/null)
+JARGON_COUNT=${JARGON_COUNT:-0}
+
+# Threshold:含決策 prompt + jargon count ≥ 10 → warn(Python 計數較廣,threshold 提高)
+THRESHOLD=10
+
+if [ "$JARGON_COUNT" -ge "$THRESHOLD" ]; then
+  echo "🟡 check_propose_plain_chinese WARN:本 turn reply 含 user 決策 prompt + jargon 密度 ${JARGON_COUNT}(threshold ${THRESHOLD})" >&2
+  echo "" >&2
+  echo "→ 違反 propose-in-plain-chinese canonical(memory/feedback_propose_in_plain_chinese.md SSOT)" >&2
+  echo "→ User 原話「請講具體人話,為何又跟智障一樣講人聽不懂的話」" >&2
+  echo "→ Rewrite reply:必含 3 段(發生什麼 / 影響什麼 / 各選項 outcome — 全中文具體,禁 jargon)" >&2
+  echo "" >&2
+  # Soft warn,不 BLOCK turn(exit 0)— 讓 AI 看到 stderr 後 self-correct
+fi
+
+exit 0

package/ds-canonical/hooks/check_propose_pre_grep_verify.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+set -uo pipefail
+# PreToolUse Edit/Write: enforce M18 Q0「Pre-ASK self-verify problem 真存在」.
+#
+# 2026-05-18 user-mandated codify after Sheet/inline-action/SurfaceBody 三題誤判事件:
+# Claude propose 給 user 拍板前必先 grep DS-wide + Read 相關 spec.md 確認 problem 真存在,
+# 沒 grep 就斷言「N 元件缺 X / 該 migrate」= 撤回 propose。
+#
+# Detection:Edit/Write content 含「propose / 請拍板 / 等你拍板 / 待你拍板 /
+# 決策 N / 我推 A/B/C / 選項」keywords,**但 content 內無 file:line cite 證據**
+# → P1 warn(stderr exit 0,Claude 自決撤回 OR 在 reply 補 cite)。
+#
+# SSOT: `.claude/skills/propose-options/SKILL.md` Q0 段 + meta-patterns.md M18。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+case "$TOOL" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+# Only fires on planning docs / commit-style summaries / reply-style markdown
+# (避 false positive on production code / 一般 spec edit)
+case "$FILE_PATH" in
+  */planning/*.md|*/reports/*.md|*/handoff/*.md) ;;
+  *) 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
+
+# Detect propose keywords
+HAS_PROPOSE=$(echo "$NEW_CONTENT" | grep -cE '(請拍板|等你拍板|待你拍板|決策 [0-9N]|我推 [ABC]|選項[::]|propose for user|你決定|讓我判斷決策)' || true)
+
+[ "$HAS_PROPOSE" = "0" ] && exit 0
+
+# Allowed escape:檔頭 `<!-- @propose-pre-verified -->` 例外
+if echo "$NEW_CONTENT" | head -3 | grep -qE '@propose-pre-verified'; then
+  exit 0
+fi
+
+# Check for file:line cite evidence
+HAS_CITE=$(echo "$NEW_CONTENT" | grep -cE '`[a-z][a-z0-9/-]+\.(tsx|ts|css|md):[0-9]+`|`[a-z][a-z0-9/-]+\.(tsx|ts|css|md)`|`packages/design-system/src/' || true)
+
+if [ "$HAS_CITE" = "0" ]; then
+  printf '⚠️ PRE-ASK SELF-VERIFY GAP(M18 Q0,P1 soft):\n' >&2
+  printf '   File: %s\n' "$FILE_PATH" >&2
+  printf '   偵測到 propose 給 user 拍板 keyword,但 content 無 file:line cite 證據。\n' >&2
+  printf '\n  M18 Q0 強制檢查:\n' >&2
+  printf '   1. grep 既有 code DS-wide 確認 problem 真存在 (file:line)\n' >&2
+  printf '   2. Read 相關 spec.md 找 canonical cite\n' >&2
+  printf '   3. Read consumer usage 確認該 pattern 已在 N 處 work fine\n' >&2
+  printf '   4. propose 給 user 前列具體 file:line 證據\n' >&2
+  printf '\n  錨例:2026-05-18 Sheet/inline-action/SurfaceBody 三題誤判 propose 浪費 user 時間\n' >&2
+  printf '  SSOT: .claude/skills/propose-options/SKILL.md Q0 段\n' >&2
+  printf '  Escape: 檔頭加 <!-- @propose-pre-verified --> 若已 verify(rationale 必明示)\n' >&2
+fi
+
+exit 0

package/ds-canonical/hooks/check_select_all_canonical.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+set -uo pipefail
+# PreToolUse Edit/Write: Select All ordering SSOT drift guard(2026-05-16 user verbatim
+# 「以後遇到此類設計都有相同邏輯不會偏移」)
+#
+# 攔截 packages/design-system/src/** edit 時,如果新內容含「Select All」 / 「checkAll」 / 「全選」 等 bulk-select
+# 動作 + 自寫 ordering logic(`onValueChange?.(options.map(...))` / `[...prev, ...]` 等),
+# 要求消費 `@/design-system/lib/multi-select-ordering` SSOT primitive 而非自刻。
+#
+# 規則 SSOT:`packages/design-system/src/lib/multi-select-ordering.ts`(applySelectAll / clearSelection)。
+# 對應 Ant Transfer + Table rowSelection canonical(Layer A + Codex M31 Round 4 共識)。
+#
+# Soft warn(stderr,non-blocking)— 給開發者警示但不擋 ship。Edge case 真需自刻 → 在
+# new content 加 `// @select-all-canonical-allow: <reason>` allowlist escape。
+
+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
+[[ "$TOOL" != "Edit" && "$TOOL" != "Write" ]] && exit 0
+[[ "$FILE_PATH" != *packages/design-system/src/* ]] && exit 0
+# 本 SSOT primitive 檔自己不查
+[[ "$FILE_PATH" == *multi-select-ordering.ts ]] && exit 0
+# Allowlist
+echo "$NEW_CONTENT" | grep -q "@select-all-canonical-allow" && exit 0
+
+# Detect Select-All-like pattern:
+#   - function name contains SelectAll / CheckAll
+#   - `[...prev`-style append with `options.map`-style source values
+#   - 顯式「全部」 button click → onValueChange
+HAS_SELECTALL_HANDLER=$(echo "$NEW_CONTENT" | grep -cE "(handleSelectAll|onSelectAll|onCheckAll|handleCheckAll|全選|checkAll\s*=|selectAll\s*=)" || true)
+
+if [ "$HAS_SELECTALL_HANDLER" -gt 0 ]; then
+  USES_SSOT=$(echo "$NEW_CONTENT" | grep -cE "(applySelectAll|multi-select-ordering)" || true)
+  if [ "$USES_SSOT" -eq 0 ]; then
+    cat >&2 <<EOF
+⚠️  Select All ordering SSOT drift warning
+File: $FILE_PATH
+
+偵測「Select All」/「checkAll」/「全選」 handler 但無 import \`applySelectAll\` from
+\`@/design-system/lib/multi-select-ordering\`。
+
+SSOT canonical(per Ant Transfer + Table rowSelection,Layer A + Codex M31 Round 4 共識):
+  preserve existing user click order + append unselected options in source order(dedup)
+  → \`applySelectAll(selectedValues, allOptionValues)\`
+
+若刻意自刻 → 加 \`// @select-all-canonical-allow: <reason>\` 在 new content 中。
+EOF
+  fi
+fi
+
+exit 0