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

package/ds-canonical/hooks/check_storybook_addon_packaging.sh

@@ -0,0 +1,151 @@
+#!/bin/bash
+# check_storybook_addon_packaging.sh — P0 BLOCKER ×2 — storybook-config addon 打包事故家族(beta.27-.31 5 連敗錨)
+#
+# 2026-06-11 prune merge(user 拍板「照你建議做」;59→51 headroom):
+# #   r1_addon_subdir_ship = 原 check_addon_subdir_ship.sh(規則逐字搬入,BLOCKER 級別與 escape 標記不變)
+#   r2_preset_cjs = 原 check_storybook_addon_preset_cjs.sh(規則逐字搬入,BLOCKER 級別與 escape 標記不變)
+# 原檔 → .claude/hooks/retired/2026-06-11-prune-merge/
+# 各規則跑在 pipeline 子 shell:規則內 exit 不中斷其他規則;任一 exit 2 → 整體 exit 2。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+INPUT=$(cat 2>/dev/null || echo "{}")
+
+r1_addon_subdir_ship() {
+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)
+# Only check addon main files
+if ! echo "$FILE" | grep -qE '/(\.storybook|storybook-config)/addons/[^/]+/[a-zA-Z]+\.(ts|tsx)$'; then exit 0; fi
+
+CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null)
+[ -z "$CONTENT" ] && exit 0
+
+# Escape clause
+if echo "$CONTENT" | grep -qE '@addon-subdir-skip:'; then exit 0; fi
+
+# Find relative subdir imports `./<dir>/*`
+RELATIVE_IMPORTS=$(echo "$CONTENT" | grep -oE "from[[:space:]]+['\"]\\./[a-zA-Z][a-zA-Z0-9_-]+/[a-zA-Z][a-zA-Z0-9_./-]*['\"]" | sed -E "s|^from[[:space:]]+['\"]\./([^/]+)/.*['\"]\$|\\1|" | sort -u)
+
+[ -z "$RELATIVE_IMPORTS" ] && exit 0
+
+ADDON_DIR=$(dirname "$FILE")
+MISSING=""
+for subdir in $RELATIVE_IMPORTS; do
+  if [ ! -d "$ADDON_DIR/$subdir" ]; then
+    MISSING="${MISSING}    - ./${subdir}/ (referenced but dir absent)\n"
+  fi
+done
+
+if [ -n "$MISSING" ]; then
+  cat >&2 << EOF
+🚨 ADDON SUBDIR SHIP BLOCKER(P0,2026-05-28 beta.27 anchor)
+
+  File: $FILE
+  Imports from subdirectories that don't exist alongside this file:
+$(printf '%b' "$MISSING")
+
+  Why blocked:
+    Addon main 檔 import 子資料夾 helper,但子 dir 沒一起 ship → npm build /
+    Rollup「Could not resolve」→ Storybook build 死。本 anchor:beta.27 第 7 次 CI
+    才抓到 ds-devmode 搬家漏帶 utils/ 6 files(燒 6 prior iterations debug)。
+
+  修方向:
+    1. Copy 缺漏 dir 過來:`cp -r <source>/<dir> $ADDON_DIR/<dir>`
+    2. 跑 npm run build-storybook local 過再 commit
+    3. 或:改 import 路徑 to existing location
+
+  Escape(極罕見): add \`// @addon-subdir-skip: <rationale>\` to file content
+EOF
+  exit 2
+fi
+
+exit 0
+}
+
+r2_preset_cjs() {
+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)
+# Scope:addons/<name>/preset.ts(stored anywhere — storybook-config or .storybook)
+if ! echo "$FILE" | grep -qE '/addons/[^/]+/preset\.ts$'; then exit 0; fi
+
+CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null)
+[ -z "$CONTENT" ] && exit 0
+
+# Escape clause
+if echo "$CONTENT" | grep -qE '@preset-cjs-skip:'; then exit 0; fi
+
+# Detect ESM/CJS interop antipatterns
+# 2026-05-30(dim 81 M7/M34 broad-vs-narrow fix + codex Phase B P3 inline-block edge):strip line-level 註解
+# BEFORE keyword grep — 正確的 preset.ts 會在 comment 內「文件化」這些 anti-pattern(教學),raw-content
+# grep 會假 BLOCK 合法 edit(ship 給 fork)。Strip 範圍:(1) 整行 //|/*|*/|* 開頭 (2) 同行 inline /* … */ block
+# (3) 行尾 // 註解。多行 block 的中間行以 * 開頭已被 (1) 覆蓋。極罕見「同行開 /* + keyword 未閉合」→ @preset-cjs-skip: escape。
+CONTENT_CODE=$(echo "$CONTENT" | grep -vE '^[[:space:]]*(//|\*|/\*|\*/)' | sed -E 's@/\*.*\*/@@g; s@//.*@@')
+ANTIPATTERN=""
+if echo "$CONTENT_CODE" | grep -qE 'createRequire|require\.resolve'; then
+  ANTIPATTERN="${ANTIPATTERN}  - createRequire / require.resolve(被 Node ESM scope 攔)\n"
+fi
+if echo "$CONTENT_CODE" | grep -qE 'fileURLToPath\s*\(\s*import\.meta\.url'; then
+  ANTIPATTERN="${ANTIPATTERN}  - fileURLToPath(import.meta.url)(同被 esbuild-register/ESM 衝突攔)\n"
+fi
+
+if [ -n "$ANTIPATTERN" ]; then
+  cat >&2 << EOF
+🚨 STORYBOOK ADDON PRESET CJS BLOCKER(P0,2026-05-28 beta.27-.31 5 連敗 anchor)
+
+  File: $FILE
+  偵測到 ESM/CJS interop 反 pattern:
+$(printf '%b' "$ANTIPATTERN")
+  Why blocked:
+    Storybook preset loader 走 esbuild-register CJS path,但 package.json
+    \`"type":"module"\` 強制 Node 把 .js 當 ESM。dynamic resolution(require.resolve /
+    fileURLToPath)被 ESM scope 攔 → ReferenceError: require not defined。
+
+  Fix:用 hand-written \`preset.cjs\`(\`.cjs\` override package type → 強制 CJS):
+
+    // preset.cjs
+    const path = require('path')
+    module.exports = {
+      managerEntries: (entry = []) => [...entry, path.join(__dirname, 'manager.tsx')],
+      previewAnnotations: (entry = []) => [...entry, path.join(__dirname, 'preview.ts')],
+    }
+
+  + package.json:
+    "exports": { "./preset": "./preset.cjs" }
+    "files": [..., "addons/<name>/preset.cjs"]
+
+  SSOT:memory/feedback_storybook_addon_preset_must_be_cjs.md
+  Anchor:2026-05-28 beta.27/.28/.29/.30/.31 5 連敗(本 hook codify 防再犯)
+
+  Escape(極罕見):add \`// @preset-cjs-skip: <rationale>\` to content
+EOF
+  exit 2
+fi
+
+exit 0
+}
+
+for _rule in r1_addon_subdir_ship r2_preset_cjs; do
+  echo "$INPUT" | "$_rule"
+  _rc=$?
+  if [ "$_rc" -eq 2 ]; then exit 2; fi
+done
+exit 0

package/ds-canonical/hooks/check_substantive_edit_approval_preflight.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+# check_substantive_edit_approval_preflight.sh — Pre-action gate for substantive design edits.
+#
+# Purpose: PRE-flight 偵測 packages/design-system/src/**.{tsx,ts,css} edit + last 5 user msgs 無
+# approval keyword → SOFT inject context warning。
+#
+# 對比 stop_self_audit.sh post-action BLOCKER:本 hook 是 PRE-action soft warn,
+# 讓 AI 看到 context 後 self-decide(propose-only OR cite approval verbatim),
+# 避免「edit → stop hook BLOCKER → revert」waste cycle(user 抓 2026-05-12 anti-pattern)。
+#
+# 對齊 Option 3 hybrid(M32 split 後 (f) ship gate 的 PRE-flight 補位):
+# - PreToolUse soft warn = info inject(本 hook)
+# - Stop hook BLOCKER = enforcement(stop_self_audit.sh Mechanism 4)
+# - AI inline self-statement = discipline(M31 Layer A/C marker + 本 hook context)
+#
+# Why pre-action soft instead of hard BLOCK:false-positive 風險(legit bug fix 可能撞)+
+# inject info 比 reject 更尊重 AI judgment + 配合 existing stop hook backstop。
+#
+# 對齊:CLAUDE.md `# 稽核 canonical` Audit-vs-execute 分權 + M31 Layer A/C + M32(f) ship gate。
+
+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)
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null)
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+
+# Only PreToolUse for Edit|Write|MultiEdit
+[ "$EVENT" != "PreToolUse" ] && exit 0
+case "$TOOL" in Edit|Write|MultiEdit) ;; *) exit 0 ;; esac
+
+# Substantive scope(2026-05-26 extended per user verbatim「未來其他人 fork 也會偏移 / 該程式化的都沒程式化」):
+# - DS internal: packages/design-system/src/**.{tsx,ts,css}
+# - Consumer fork-user app code: apps/**.{tsx,ts,css} (product-workspace 或任何 fork 的 monorepo apps/)
+# - DS source in node_modules(consumer 改 DS 直接 forbidden — 必走 fork 流程):node_modules/@qijenchen/design-system/**
+case "$FILE_PATH" in
+  */packages/design-system/src/*.tsx|*/packages/design-system/src/*.ts|*/packages/design-system/src/*.css) ;;
+  */apps/*.tsx|*/apps/*.ts|*/apps/*.css) ;;
+  */node_modules/@qijenchen/design-system/*) ;;
+  *) exit 0 ;;
+esac
+
+# Allowlist:storybook config / scripts / tests 等非 production code
+case "$FILE_PATH" in
+  *.stories.tsx|*.test.ts|*.spec.ts|*/scripts/*) exit 0 ;;
+esac
+
+[ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ] && exit 0
+
+# Scan last 5 真 user msgs(transcript role=user 且 content 非 tool_result)
+RECENT_USER_MSGS=$(tail -200 "$TRANSCRIPT_PATH" 2>/dev/null | \
+  jq -r 'select(.message.role=="user") |
+    .message.content // empty |
+    if type=="string" then .
+    else (.[]? | select(.type != "tool_result") | .text // empty)
+    end' 2>/dev/null | tail -5)
+
+# Approval keywords(對齊 stop_self_audit.sh:172)+ 2026-05-15 升 numbered directive
+# (`#1 A` / `#1 ship` 等)+ 「照建議」/「照共識」/「照我的」等 reference style approval
+# 2026-05-21 M34 fix(per user verbatim「都給我做到好」approval blocked by 妳/決策N coverage gap):
+#   (a) 加「妳」變體(`照妳`= `照你` 文書通用 variant)
+#   (b) 加「決策[一二三四五六七八九十1-9]」numbered directive(eg.「決策一改…」「決策3做」)
+#   (c) 加「做到好」/「都做」/「全做」auto-approve 變體
+APPROVAL_RE='(同意|採用|採納|拍板|拍\s*[A-Z0-9]|可以|改成|改為|執行|上吧|push|implement|go ahead|approved|OK|好|沒問題|做一做|就做|做吧|做完|全部做完|做到完|做到好|都做|全做|馬不停蹄|建議做|ship|合 main|^#[0-9]+|照你|照妳|照建議|照共識|照我的|按照|決策[一二三四五六七八九十1-9]|[A-Z][0-9]+\s*(做|改|修)|先\s*[A-Z][0-9]+)'
+HAS_APPROVAL=$(echo "$RECENT_USER_MSGS" | grep -cE "$APPROVAL_RE" 2>/dev/null)
+HAS_APPROVAL=${HAS_APPROVAL:-0}
+
+# Substantive-discuss keywords(若 user 在 discuss mode → 提示 propose-only)
+DISCUSS_RE='(propose|提案|建議|討論|比稿|看法|思考|評估|要不要|該不該|是否|怎麼想)'
+HAS_DISCUSS=$(echo "$RECENT_USER_MSGS" | grep -cE "$DISCUSS_RE" 2>/dev/null)
+HAS_DISCUSS=${HAS_DISCUSS:-0}
+
+# Approval present → silent pass
+if [ "$HAS_APPROVAL" -gt 0 ]; then
+  exit 0
+fi
+
+# 2026-05-15 upgrade per user verbatim:「上述的問題請你務必確實確保永遠他媽不要再給我犯了」
+# (memory/feedback_ship_then_revert_anti_pattern.md SSOT)
+# Soft warn → P0 BLOCKER on packages/design-system/src/**/*.tsx production substantive without approval。
+# Override env var:CLAUDE_BYPASS_DESIGN_APPROVAL=1(audit-logged below)
+REL_PATH=${FILE_PATH#*/my-project/}
+
+if [ "${CLAUDE_BYPASS_DESIGN_APPROVAL:-0}" = "1" ]; then
+  # Audit log override
+  mkdir -p "$(dirname "$0")/../logs" 2>/dev/null
+  printf '{"ts":"%s","event":"design-approval-bypass","file":"%s","tool":"%s"}\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$REL_PATH" "$TOOL" \
+    >> "$(dirname "$0")/../logs/approval-bypass.jsonl" 2>/dev/null || true
+  exit 0
+fi
+
+# BLOCKER:stderr + exit 2 = halt PreToolUse(Edit/Write/MultiEdit)
+echo "🚨 BLOCKER: Pre-action gate(check_substantive_edit_approval_preflight,2026-05-15 P0 升級)" >&2
+echo "  - 目標: ${REL_PATH}" >&2
+echo "  - 範圍: packages/design-system/src production code(substantive SSOT change)" >&2
+echo "  - 近 5 條 user msg approval keyword: ${HAS_APPROVAL} 次 / discuss keyword: ${HAS_DISCUSS} 次" >&2
+echo "" >&2
+echo "→ SSOT-affecting UI/UX edit without verbatim approval = ship-then-revert anti-pattern" >&2
+echo "  (memory/feedback_ship_then_revert_anti_pattern.md SSOT)" >&2
+echo "" >&2
+echo "修法 — 2 選 1:" >&2
+echo "  (a) Convert to propose-only:列 option + 4-Q 自檢 + 等 user 拍板,撤回 edit" >&2
+echo "  (b) Cite user approval verbatim quote 在 commit message + reply,然後設" >&2
+echo "      \`CLAUDE_BYPASS_DESIGN_APPROVAL=1\` env var 跑 edit(audit-logged)" >&2
+echo "" >&2
+echo "「user echo hypothesis」≠「user approve」— M4 sub-check enforces。" >&2
+exit 2

package/ds-canonical/hooks/check_tabs_content_chrome_body_double_gap.sh

@@ -0,0 +1,183 @@
+#!/bin/bash
+# check_tabs_content_chrome_body_double_gap.sh — P0 BLOCKER(overlay-body layout-space guardian,2 checks)
+#
+# **Check 1**(tabs double-gap):`<TabsContent>` 被放進 chrome scroll body(`<DialogBody>` /
+#   `<SheetBody>` / `<SurfaceBody>`)內卻沒 `mt-0` override → 雙重 gap owner。
+# **Check 2**(overlay-body fixed macro gap,2026-07-01 Sheet gap-4 錨例):浮層 body 自身 className
+#   用固定 `gap-[4-9]`(macro)而非 layout-space token → lg density 不縮放,drift。詳見下方 Check 2 段。
+#
+# 兩者同屬「overlay-body layout-space 合規」domain,折進一 hook(不增 hook 數)。
+#
+# Root invariant(item-anatomy.spec.md「垂直 padding 歸屬 / 禁雙重 padding」+ layoutSpace.spec.md
+# 規則 2「Header → element = 單一 tight」):兩元素之間的 gap 只能有一個 owner。
+# - DialogBody/SheetBody/SurfaceBody 內層 padded div 已用 `pt-/py-[var(--layout-space-tight)]`
+#   擁有 header→content 的 chrome gap。
+# - TabsContent 預設帶 `mt-[var(--layout-space-tight)]`(tabs.tsx,為「緊接 tab bar 下方」而設)。
+# - tabsSlot composition 把 tab bar 抬進 header,TabsContent 留在 body → 兩 owner 疊加 =
+#   雙重 tight(md 24 / lg 32)。修法 = chrome body 內的 TabsContent 加 `className="mt-0"`
+#   把 ownership 轉移給 body(對齊 AppShell 前例 app-shell.stories.tsx + Carbon/Radix「panel
+#   單一 owner」benchmark)。
+#
+# Anchor:2026-07-01 user 在「專案設定」Dialog(dialog.stories.tsx WithTabsInHeader)DevTools
+#   抓到「專案名稱」上方兩個 --layout-space-tight。歷次稽核漏抓,因既有
+#   check_layout_space_magic_numbers.sh **明確 skip packages/design-system/src/**(該 hook L34)。
+#   本 hook **反轉 scope** 專掃 DS src + apps composition,補該盲區。
+#
+# Scope:只掃 packages/design-system/src/** + apps/** 的 .tsx(含 .stories.tsx)。
+# Level:P0 BLOCKER exit 2(layout-space SSOT 一律 P0,非 P1 WARN — per
+#   feedback_ssot_mechanical_p0_not_p1_warn_2026_05_27)。窄 gate(必同時含 chrome body + TabsContent)
+#   控 false-positive。Escape:`// @tabs-content-gap-ok: <rationale>`(同行或前一註解行)。
+
+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)
+
+# Scope:DS source + apps,.tsx only(INVERSE of check_layout_space_magic_numbers.sh 的 DS-src skip)
+if ! echo "$FILE" | grep -qE '\.tsx$'; then exit 0; fi
+if ! echo "$FILE" | grep -qE '(packages/design-system/src/|/apps/|(^|/)apps/)'; then exit 0; fi
+
+# PostToolUse:file 已寫入磁碟,讀「完整檔」做 containment 分析(避免 hunk-only partial-edit 盲區 —
+# 部分 edit 的 new_string 可能只含 TabsContent 行不含外層 DialogBody,window 分析會漏)。
+[ -f "$FILE" ] || exit 0
+CONTENT=$(cat "$FILE" 2>/dev/null)
+[ -z "$CONTENT" ] && exit 0
+
+# ══ Check 2:overlay body 自身用固定 macro gap-N → 該用 layout-space token(2026-07-01 Sheet gap-4 錨例)══
+# Root(layoutSpace.spec.md 規則 2/3):浮層 body 直接堆疊內容的垂直 gap 屬 macro layout-space,該用
+#   density-scaling token(並列 = loose / functional 交互 = tight),非固定 gap-N(lg 不縮放 → 跟 DS
+#   自己 dialog.stories 的 gap-[var(--layout-space-loose)] 不一致)。窄 gate:只抓 overlay body 自身
+#   className 的固定 gap-[4-9](macro range;排除 gap-1/2/3 micro + 已 tokenize 的 gap-[var)。
+#   全庫掃證實零現存假陽性(純防未來 drift)。Escape:同行或前一註解行 @overlay-body-gap-ok:。
+GAP_MARKER='@overlay-body-gap-ok:'
+GAP_HITS=$(printf '%s\n' "$CONTENT" | grep -nE '<(DialogBody|SheetBody|PopoverBody|SurfaceBody)[^>]*gap-[4-9]([^0-9]|$)' 2>/dev/null | grep -v 'gap-\[var')
+GAP_UNJUSTIFIED=""
+if [ -n "$GAP_HITS" ]; then
+  while IFS= read -r hit; do
+    [ -z "$hit" ] && continue
+    ln="${hit%%:*}"
+    cur="${hit#*:}"
+    if echo "$cur" | grep -qF "$GAP_MARKER"; then continue; fi
+    if [ "$ln" -gt 1 ] 2>/dev/null; then
+      prev=$(printf '%s\n' "$CONTENT" | sed -n "$((ln-1))p")
+      if echo "$prev" | grep -qF "$GAP_MARKER" && echo "$prev" | grep -qE '^[[:space:]]*(//|\{?/\*|\*)'; then continue; fi
+    fi
+    GAP_UNJUSTIFIED="${GAP_UNJUSTIFIED}${ln}: $(echo "$cur" | sed 's/^[[:space:]]*//')\n"
+  done <<< "$GAP_HITS"
+fi
+if [ -n "$GAP_UNJUSTIFIED" ]; then
+  cat >&2 << EOF
+🚨 OVERLAY-BODY FIXED-GAP BLOCKER(P0,2026-07-01 Sheet demo gap-4 錨例)
+
+  在 $FILE 偵測到浮層 body(Dialog/Sheet/Popover/Surface Body)自身用固定 macro gap-N:
+$(echo -e "$GAP_UNJUSTIFIED" | sed 's/^/    /' | head -10)
+
+  ── 為什麼 ──
+  浮層 body 直接堆疊內容(並列表單欄位 / 區塊)的垂直 gap 屬 macro layout-space,該用
+  density-scaling token(並列 = loose / functional 交互 = tight),非固定 gap-N(lg 不縮放 →
+  跟 DS 自己 dialog.stories 的 gap-[var(--layout-space-loose)] 不一致)。
+
+  ── 修法 2 選 1 ──
+    (a) gap-N → gap-[var(--layout-space-loose)](並列)/ gap-[var(--layout-space-tight)](functional 交互)
+    (b) Escape:該行或前一註解行加 \`// @overlay-body-gap-ok: <rationale>\`(刻意 list 間距 / 視覺平衡)
+
+  canonical → tokens/layoutSpace/layoutSpace.spec.md 規則 2/3
+EOF
+  exit 2
+fi
+
+# ══ Check 1:<TabsContent> 在 chrome body 內雙重 gap(原 beta.78 邏輯)══
+# Gate:必同時含 chrome body open tag 且 TabsContent 才啟動(narrow surface,絕大多數 edit 靜默)
+if ! echo "$CONTENT" | grep -qE '<(DialogBody|SheetBody|SurfaceBody)[ />]'; then exit 0; fi
+if ! echo "$CONTENT" | grep -q '<TabsContent'; then exit 0; fi
+
+ESCAPE_MARKER='@tabs-content-gap-ok:'
+
+# 逐行 depth-counter(awk):進 chrome body +1、出 -1;TabsContent 在 depth>0 = 在 chrome body 內。
+# - 註解行(JSDoc `*` / `//` / `{/*` / `/*` / `*/`)整行跳過,不計 depth 也不判 TabsContent
+#   (避免 JSDoc 內 `<DialogBody>` 範例污染 depth / 內含的 mt-0 example 被誤判)。
+# - 同行 open 先加 depth 再判 TabsContent 再減 close → 同行 `<DialogBody><TabsContent>` 與
+#   `<TabsContent>...</DialogBody>` 都正確歸屬「inside」。
+# - TabsContent opening tag 可能跨行:accumulate 到 `>` 再驗 className 有無 canonical `mt-0`
+#   (class-boundary anchored;非-0 / arbitrary 值需 escape marker)。
+# 輸出:每個「chrome body 內且無 mt-0 override」的 TabsContent 起始行號(供 bash escape 過濾)。
+CANDIDATES=$(printf '%s\n' "$CONTENT" | awk '
+  function check_tag(tag, ln) {
+    # 只認 canonical `mt-0`(class-boundary anchored):排除 `mt-0.5` / `mt-04` 等 substring 假通過
+    # (mt-0.5 是本 DS 真實 class,item-anatomy.stories.tsx:766;2px 不抵銷 pt-tight → 仍雙重)。
+    # arbitrary `mt-[...]` / 非-0 值 = 非 canonical → 需 escape marker 明示 documented(非靜默通過)。
+    if (tag ~ /(^|[^a-zA-Z0-9])mt-0([^a-zA-Z0-9.]|$)/) return
+    print ln
+  }
+  BEGIN { depth=0; collecting=0; buf=""; startline=0 }
+  {
+    raw=$0
+    if (collecting) {
+      buf = buf " " raw
+      if (raw ~ />/) { collecting=0; check_tag(buf, startline); buf="" }
+      next
+    }
+    t=raw; sub(/^[ \t]+/,"",t)
+    if (t ~ /^(\*|\/\/|\{?\/\*|\*\/)/) next          # skip comment-only lines
+    tmp=raw;  o=gsub(/<(DialogBody|SheetBody|SurfaceBody)[ \t\/>]/,"X",tmp)
+    tmpc=raw; c=gsub(/<\/(DialogBody|SheetBody|SurfaceBody)>/,"X",tmpc)
+    depth += o
+    if (raw ~ /<TabsContent/ && depth > 0) {
+      idx = index(raw, "<TabsContent")
+      rest = substr(raw, idx)
+      if (rest ~ />/) { gt = index(rest, ">"); check_tag(substr(rest, 1, gt), NR) }
+      else { collecting=1; buf=rest; startline=NR }
+    }
+    depth -= c
+  }
+')
+
+if [ -z "$CANDIDATES" ]; then exit 0; fi
+
+# Escape 過濾:同行 OR 前一「註解專用行」含 @tabs-content-gap-ok: → 豁免(對齊
+# check_layout_space_magic_numbers.sh L57-69 已 debug 過的 preceding-line marker 邏輯)。
+UNJUSTIFIED=""
+while IFS= read -r ln; do
+  [ -z "$ln" ] && continue
+  cur=$(echo "$CONTENT" | sed -n "${ln}p")
+  if echo "$cur" | grep -qF "$ESCAPE_MARKER"; then continue; fi
+  if [ "$ln" -gt 1 ] 2>/dev/null; then
+    prev=$(echo "$CONTENT" | sed -n "$((ln-1))p")
+    if echo "$prev" | grep -qF "$ESCAPE_MARKER" && echo "$prev" | grep -qE '^[[:space:]]*(//|\{?/\*|\*)'; then continue; fi
+  fi
+  UNJUSTIFIED="${UNJUSTIFIED}${ln}: $(echo "$cur" | sed 's/^[[:space:]]*//')\n"
+done <<< "$CANDIDATES"
+
+if [ -z "$UNJUSTIFIED" ]; then exit 0; fi
+
+cat >&2 << EOF
+🚨 TABS-CONTENT-CHROME-BODY DOUBLE-GAP BLOCKER(P0,2026-07-01 user「專案名稱上方兩個 space-tight」)
+
+  在 $FILE 偵測到 <TabsContent> 放在 chrome scroll body(DialogBody/SheetBody/SurfaceBody)內
+  但未 override margin-top:
+$(echo -e "$UNJUSTIFIED" | sed 's/^/    /' | head -10)
+
+  ── 為什麼是 bug ──
+  DialogBody/SheetBody/SurfaceBody 內層已用 pt-/py-[var(--layout-space-tight)] 擁有 header→content
+  的 chrome gap;TabsContent 預設又帶 mt-[var(--layout-space-tight)](tabs.tsx,為緊接 tab bar 而設)。
+  tabsSlot composition 把 tab bar 抬進 header 後,兩個 owner 疊加 = 雙重 tight(md 24 / lg 32)。
+  一軸只能有一個 spacing owner(item-anatomy.spec.md「垂直 padding 歸屬 / 禁雙重 padding」)。
+
+  ── 修法 2 選 1 ──
+    (a) chrome body 內的 TabsContent 加 \`className="mt-0"\` 把 ownership 轉移給 body
+        (對齊 AppShell 前例 app-shell.stories.tsx + Carbon/Radix「panel 單一 owner」benchmark)
+    (b) Escape:該行或前一註解行加 \`// @tabs-content-gap-ok: <rationale>\`(顯式 documented 例外)
+
+  完整 canonical → components/Tabs/tabs.spec.md「出現在 Dialog」段
+                 + tokens/layoutSpace/layoutSpace.spec.md 規則 2
+EOF
+exit 2

package/ds-canonical/hooks/check_tailwind_wildcard_in_docs.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# check_tailwind_wildcard_in_docs.sh — P0 BLOCKER
+#
+# Per 2026-05-28 beta.27 release fail anchor(6+ CI iterations 燒):
+# Tailwind v4 vite plugin scans .md / .spec.md / docs by default。
+# 文件範例 like `shadow-[var(--elevation-*)]` 或 `var(--field-height-*)` /
+# `var(--elevation-100/200/300)` 是給 dev 看的 shorthand notation(`*` /  `/` 代表
+# enumeration placeholder),但 Tailwind 不知 → 當 literal class string 抓 → 產
+# invalid CSS `var(--X-*)` `var(--X-A/B/C)` → Storybook FULL smoke 死。
+#
+# 機械強制 PreToolUse Edit/Write:阻止寫入新檔含此 anti-pattern。
+# 改用 math notation:`var(--X-N) N∈{a,b,c}` Tailwind 不會誤判。
+#
+# Scope:所有 .md / .spec.md / .sh / .ts / .tsx 寫入時 grep new_string。
+# Exit 2 BLOCKER + cite this anchor。Escape:`@tailwind-wildcard-allow:` comment。
+
+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)
+# Self-exemption:本 hook help-text 合法含 anti-pattern literal 作為文件範例(且 .sh 不被 Tailwind
+# vite plugin 掃,無 build 風險)→ 不掃自己,避免 self-trigger false-positive(2026-05-30 test-surfaced)。
+case "$FILE" in */check_tailwind_wildcard_in_docs.sh) exit 0 ;; esac
+# 2026-06-11 R2 held-item #13:.claude/{tmp,logs} 歷史 artifact(codex brief / reply、audit findings
+# json、preflight log)非 Tailwind 掃描對象 — src/globals.css 用 explicit positive @source(只掃 src/ +
+# packages/{design-system,storybook-config} + .storybook/)且 `@source not "**/.claude/**"`;盤上 12 檔
+# 已含 antiPattern 而 build 連續綠(至 beta.61)= 零 build 風險實證。掃描對象路徑(src/packages/docs)
+# 保護不變。
+case "$FILE" in */.claude/tmp/*|*/.claude/logs/*|.claude/tmp/*|.claude/logs/*) exit 0 ;; esac
+# Only check files Tailwind v4 might scan
+if ! echo "$FILE" | grep -qE '\.(md|spec\.md|sh|ts|tsx|css|json)$'; then exit 0; fi
+
+CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null)
+[ -z "$CONTENT" ] && exit 0
+
+# Escape clause
+if echo "$CONTENT" | grep -qE '@tailwind-wildcard-allow:'; then exit 0; fi
+
+# Detect anti-patterns(class form with wildcard / slash enumeration in CSS var)
+# 2026-05-30 fix(test-surfaced M34 over-narrow):slash-segment 改 repeatable,
+# 否則漏多段斜線列舉形式(beta.27 anchor 的 N-段 enum,hook header 列為必擋 anti-pattern)。
+ANTI_PATTERNS=$(echo "$CONTENT" | grep -oE 'var\(--[a-z][a-z0-9-]*([\*/]+[a-z0-9-]*)+\)' | sort -u)
+
+if [ -n "$ANTI_PATTERNS" ]; then
+  cat >&2 << EOF
+🚨 TAILWIND v4 WILDCARD-IN-DOCS BLOCKER(P0,2026-05-28 beta.27 anchor)
+
+  File: $FILE
+  Detected anti-pattern(s):
+$(echo "$ANTI_PATTERNS" | sed 's/^/    /')
+
+  Why blocked:
+    Tailwind v4 vite plugin scans .md/.ts/etc → 把 \`var(--X-*)\` / \`var(--X-A/B/C)\`
+    當 literal class string 抓 → 產 invalid CSS(CSS 變數名禁 \`*\` / \`/\`)→ Storybook
+    build 死 → release CI fail。本 anchor:beta.27 6+ CI iteration 燒此問題。
+
+  改用 math notation(Tailwind 不誤判):
+    var(--elevation-*)         → var(--elevation-N) N∈{100,200}
+    var(--elevation-100/200) → var(--elevation-N) N∈{100,200}
+    var(--field-height-*)      → var(--field-height-N) N∈{sm,md,lg}
+    var(--layout-space-*)      → var(--layout-space-N) N∈{loose,tight}
+    var(--radix-*-available-height) → var(--radix-{popover|hover-card|dialog}-content-available-height)
+
+  Escape(極罕見,本 file 真需要 wildcard token literal):
+    add \`// @tailwind-wildcard-allow: <rationale>\` to file content
+EOF
+  exit 2
+fi
+
+exit 0

package/ds-canonical/hooks/check_wrapper_primitive_schema_drift.sh

@@ -0,0 +1,104 @@
+#!/bin/bash
+set -uo pipefail
+# M30 機械強制:wrapper-vs-primitive schema unify invariant。
+#
+# PreToolUse(Edit / Write)hook —— 編輯 `packages/design-system/src/components/**/*.tsx` 時掃:
+#   (a) 檢查同 file 是否 declare `export interface XxxOption` 同名於其他 file
+#   (b) 若同名且未 `extends XxxOption from primitive`/`extends YyyOption` → BLOCKER
+#   (c) 若 wrapper 用 `SelectMenuOption`(import from SelectMenu)但內部 `menuOptions` mapping
+#       未 forward `avatar` / `description` / `disabled`(只 forward value+label)→ WARN
+#
+# Bug 史(2026-05-10):
+#   `Select.SelectOption` Issue 4 補 avatar / description / disabled,但 `Combobox.SelectOption`
+#   是同名 weak schema `{ value, label }`。TypeScript 不抓(不同 file 同名各 export);consumer
+#   import 哪個版本看 import path 決定 → drift。PeoplePicker multi-mode dropdown 漏 avatar。
+#
+# Allow escape:
+#   檔頭 `// @wrapper-schema-allow: <reason>` 整檔豁免(legacy migration 過渡期)。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+case "$TOOL" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+case "$FILE_PATH" in
+  */packages/design-system/src/components/**/*.tsx) ;;
+  *) exit 0 ;;
+esac
+
+NEW_CONTENT=$(echo "$INPUT" | jq -r '
+  if .tool_input.new_string then .tool_input.new_string
+  elif .tool_input.content then .tool_input.content
+  else "" end
+')
+
+# Allow escape
+if echo "$NEW_CONTENT" | grep -qE '@wrapper-schema-allow:'; then
+  exit 0
+fi
+
+# Check 1: new file declares `export interface XxxOption {` ?
+DECLARES=$(echo "$NEW_CONTENT" | grep -oE 'export interface [A-Z][a-zA-Z]*Option\b[^{]*\{' || true)
+if [ -z "$DECLARES" ]; then
+  exit 0
+fi
+
+# For each declared OptionLike interface, check if same name declared elsewhere
+DS_COMPONENTS_DIR="$(dirname "$0")/../../packages/design-system/src/components"
+
+# normalize FILE_PATH relative to project for self-skip
+SELF_BASENAME="$(basename "$FILE_PATH")"
+
+WARNINGS=()
+BLOCKERS=()
+
+while IFS= read -r decl; do
+  IFACE_NAME=$(echo "$decl" | grep -oE '[A-Z][a-zA-Z]*Option' | head -1)
+  [ -z "$IFACE_NAME" ] && continue
+  # Skip if extends another OptionLike interface(M30 compliant)
+  if echo "$NEW_CONTENT" | grep -qE "interface $IFACE_NAME\b.*extends [A-Z][a-zA-Z]*Option"; then
+    continue
+  fi
+  # Find other files declaring same name(skip self by basename — imperfect but Edit context is single-file)
+  OTHER_DECLS=$(grep -rlE "export interface $IFACE_NAME\b" "$DS_COMPONENTS_DIR" 2>/dev/null | grep -v "/$SELF_BASENAME$" || true)
+  if [ -n "$OTHER_DECLS" ]; then
+    BLOCKERS+=("M30 schema drift: \`$IFACE_NAME\` declared in this file (no extends) + also in: $(echo "$OTHER_DECLS" | head -3 | xargs -n1 basename | tr '\n' ',' | sed 's/,$//')")
+  fi
+done <<< "$DECLARES"
+
+# Check 2: imports SelectMenuOption but menuOptions mapping drops fields(WARN)
+if echo "$NEW_CONTENT" | grep -qE 'import.*SelectMenuOption.*from.*SelectMenu'; then
+  # Look for `menuOptions: SelectMenuOption[]` mapping that misses fields
+  MAP_BLOCK=$(echo "$NEW_CONTENT" | grep -A5 -E 'menuOptions.*SelectMenuOption\[\]' | head -30)
+  if [ -n "$MAP_BLOCK" ]; then
+    # Heuristic: should forward at least `avatar` OR `description` OR `disabled` field
+    if ! echo "$MAP_BLOCK" | grep -qE '(avatar|description|disabled)'; then
+      WARNINGS+=("M30 schema partial-forward: \`menuOptions\` mapping seems to drop avatar/description/disabled. Forward 全 SelectMenuOption surface or annotate \`// @wrapper-schema-allow: <reason>\`.")
+    fi
+  fi
+fi
+
+# Output
+if [ ${#BLOCKERS[@]} -gt 0 ]; then
+  echo "🚨 M30 wrapper-vs-primitive schema drift BLOCKER:" >&2
+  for b in "${BLOCKERS[@]}"; do echo "  • $b" >&2; done
+  echo "" >&2
+  echo "Fix: declare \`interface $IFACE_NAME extends <PrimitiveSSoT>\` (e.g. \`extends SelectMenuOption\`)" >&2
+  echo "  詳 .claude/rules/meta-patterns.md M30 + Polaris ChoiceList / Material Autocomplete idiom" >&2
+  exit 2
+fi
+
+if [ ${#WARNINGS[@]} -gt 0 ]; then
+  echo "⚠️  M30 wrapper schema forward warning:" >&2
+  for w in "${WARNINGS[@]}"; do echo "  • $w" >&2; done
+fi
+
+exit 0