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

package/ds-canonical/hooks/retired/check_container_breathing.sh

@@ -0,0 +1,142 @@
+#!/bin/bash
+# PreToolUse hook: detect consumer 自建的 visual container(bg/border/shadow)缺 inner padding。
+#
+# Motivation(CLAUDE.md + element-anatomy.spec.md「視覺容器 breathing invariant」· 2026-04-22):
+#   任何有視覺邊界(permanent bg-* / border / shadow-*)的容器必有 inner padding,
+#   不讓內容物觸容器邊。責任在父容器。
+#
+# 世界級一致:Material / Polaris / Atlassian / Ant / Apple HIG / Carbon 6 家 chrome 都 own 內 padding。
+#
+# 反例(本 session 2026-04-22 糾正):
+#   <div className="bg-surface-raised rounded-lg">{rich FileItem map}</div>
+#   → rich card w-full 貼父 div 邊,兩層 rounded 視覺卡在一起
+#
+# 檢查 pattern(保守:只 warn,不 block — 靜態 grep 無法完美判斷):
+#   P1 WARN  `<div className="...bg-* | border | shadow-*...">` 且同 className 無 p*- / px-* / py-*
+#            → warn consumer 可能漏 padding
+#
+# Scope: *.tsx(component + story + exploration)
+#
+# Allowlist:
+#   // @breathing-exempt: <reason>(整檔豁免)
+#   // @breathing-exempt-next(下一行豁免)
+#
+# Exit codes:
+#   exit 0 — pass(P1 warn 也走 0,不 block;重要改 chrome primitive 可升級為 block)
+#
+# 不攔截的情境(AI 判斷,非 hook 責任):
+#   - 子元件自己的 class(如 Button `bg-primary px-3` 已有 padding)
+#   - p-0 刻意覆寫(如 SheetBody variant="list" `py-2`)
+#   - 無 bg 的 flex container 只用 border separator
+
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+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
+  *.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 "")
+
+if [ -z "${NEW_CONTENT//[[:space:]]/}" ]; then
+  exit 0
+fi
+
+# ── File-level allowlist ──
+FIRST_LINES=$(printf '%s\n' "$NEW_CONTENT" | sed -n '1,3p')
+if echo "$FIRST_LINES" | grep -qE '//[[:space:]]*@breathing-exempt:'; then
+  exit 0
+fi
+if [ -f "$FILE_PATH" ]; then
+  ON_DISK_FIRST=$(sed -n '1,3p' "$FILE_PATH" 2>/dev/null || true)
+  if echo "$ON_DISK_FIRST" | grep -qE '//[[:space:]]*@breathing-exempt:'; then
+    exit 0
+  fi
+fi
+
+WARN_VIOLATIONS=""
+
+TMP=$(mktemp)
+trap 'rm -f "$TMP"' EXIT
+printf '%s\n' "$NEW_CONTENT" > "$TMP"
+
+ROW=0
+SKIP_NEXT=0
+while IFS= read -r LINE || [ -n "$LINE" ]; do
+  ROW=$((ROW+1))
+
+  if [ "$SKIP_NEXT" = "1" ]; then
+    SKIP_NEXT=0
+    continue
+  fi
+  if echo "$LINE" | grep -qE '//[[:space:]]*@breathing-exempt-next|\{/\*[[:space:]]*@breathing-exempt-next'; then
+    SKIP_NEXT=1
+    continue
+  fi
+
+  # P1 WARN: `<div className="..."` contains visual-boundary class(bg-*/border/shadow-*)且 same className 無 padding
+  #
+  # heuristic:只查 div / section 等 structural element,不查 children 元件(Button / Input 等自帶 padding)
+  # 視覺邊界 class:
+  #   bg-surface* / bg-neutral-* / bg-primary* / bg-error* / bg-* (有色的,不含 bg-transparent)
+  #   border / border-* (但 border-0 / border-transparent 不算)
+  #   shadow-[var(--elevation-* (不含 shadow-none)
+  # Padding class:
+  #   p-[0-9]+ / px-[0-9]+ / py-[0-9]+ / p-\[var(--layout-space-* / px-\[var / py-\[var / p-calc / p-0(刻意移除也算宣告)
+  if echo "$LINE" | grep -qE '<(div|section|aside|header|footer|main|nav)[^>]*className="[^"]*"'; then
+    # Extract className content(best-effort for single-line):
+    CLASSNAMES=$(echo "$LINE" | grep -oE 'className="[^"]+"' | head -1)
+    # Has visual boundary?
+    HAS_BG=$(echo "$CLASSNAMES" | grep -qE '\bbg-(surface|neutral|primary|error|warning|success|info|inverse|overlay)[a-z0-9-]*|\bbg-\[' && echo 1 || echo 0)
+    HAS_BORDER=$(echo "$CLASSNAMES" | grep -qE '\bborder(-[a-z0-9]+)?\b' && ! echo "$CLASSNAMES" | grep -qE '\bborder-0\b|\bborder-transparent\b' && echo 1 || echo 0)
+    HAS_SHADOW=$(echo "$CLASSNAMES" | grep -qE '\bshadow-\[var\(--elevation|\bshadow-\[' && ! echo "$CLASSNAMES" | grep -qE '\bshadow-none\b' && echo 1 || echo 0)
+
+    if [ "$HAS_BG" = "1" ] || [ "$HAS_BORDER" = "1" ] || [ "$HAS_SHADOW" = "1" ]; then
+      # Has padding?
+      HAS_PADDING=$(echo "$CLASSNAMES" | grep -qE '\bp-[0-9]+\b|\bpx-[0-9]+\b|\bpy-[0-9]+\b|\bpt-[0-9]+\b|\bpb-[0-9]+\b|\bpl-[0-9]+\b|\bpr-[0-9]+\b|\bp-\[|\bpx-\[|\bpy-\[|\bpt-\[|\bpb-\[' && echo 1 || echo 0)
+      if [ "$HAS_PADDING" = "0" ]; then
+        REASONS=""
+        [ "$HAS_BG" = "1" ] && REASONS="${REASONS} bg"
+        [ "$HAS_BORDER" = "1" ] && REASONS="${REASONS} border"
+        [ "$HAS_SHADOW" = "1" ] && REASONS="${REASONS} shadow"
+        WARN_VIOLATIONS="${WARN_VIOLATIONS}
+────────────────────────────────
+[P1 visual container 缺 inner padding(warn)] ${FILE_PATH}:${ROW}
+  視覺邊界:${REASONS# }
+  > $(echo "$LINE" | sed 's/^[[:space:]]*//' | cut -c1-120)
+  判斷: 視覺容器(bg/border/shadow)必有 inner padding,不讓內容物貼容器邊。
+        建議:chrome 層用 p-[var(--layout-space-N) N∈{loose,tight}] / px-3 等。
+        若是 (a) chrome primitive override 刻意 p-0,(b) 父容器另外提供 padding,
+        (c) 子元件自帶足夠 padding → 加 // @breathing-exempt-next 到此行上一行。
+        SSOT: patterns/element-anatomy/element-anatomy.spec.md「視覺容器 breathing invariant」"
+      fi
+    fi
+  fi
+
+done < "$TMP"
+
+if [ -n "$WARN_VIOLATIONS" ]; then
+  {
+    echo ""
+    echo "┄┄┄┄ check_container_breathing — P1 warn(視覺容器缺 inner padding) ┄┄┄┄"
+    printf '%s\n' "$WARN_VIOLATIONS"
+  } >&2
+fi
+
+exit 0

package/ds-canonical/hooks/retired/check_governance_compliance.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+# PreToolUse Write: 任何治理檔(新 skill / hook / CLAUDE.md 章節)寫入前,
+# 強制 AI 跑 governance compliance self-check — 防 M7 violation 再次發生。
+#
+# 根源:AI 設計新 skill/hook/rule 時常忘 cross-check 既有 meta-pattern
+# + 2-home canonical(spec/tsx)+ Rule-of-3 + audit-vs-execute 分權,
+# 導致後續需要 refactor(見 2026-04-24 `/knowledge-prune` 錯搬 canonical 事件)。
+#
+# 本 hook 在 Write 時注入強制 self-check prompt,AI 必逐條答。
+# 非 blocking(只注入 context),但 AI 必在 response 裡提出 audit 結果。
+
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Only fire for new governance files
+[ -z "$FILE_PATH" ] && exit 0
+[ "$TOOL_NAME" != "Write" ] && exit 0
+
+# File path scope
+case "$FILE_PATH" in
+  */CLAUDE.md)                          SCOPE="CLAUDE.md section/rule" ;;
+  */.claude/skills/*/SKILL.md)          SCOPE="new skill" ;;
+  */.claude/skills/*/references/*.md)   SCOPE="skill reference doc" ;;
+  */.claude/hooks/*.sh|*/.claude/hooks/*.py)  SCOPE="new hook" ;;
+  */.claude/planning/*.md)              SCOPE="planning doc" ;;
+  *) exit 0 ;;
+esac
+
+# Only fire for NEW files(Write 新檔;既存 edit 不注入,減噪音)
+[ -f "$FILE_PATH" ] && exit 0
+
+MSG=$(cat <<EOF
+🛡️ Governance compliance self-check(${SCOPE})— 寫入前必回答以下 7 題,答不過停下重設計:
+
+1. M7 cross-check:本規則 / skill / hook 跟既有 Meta-Pattern M1-M17 有牴觸 / 漏用嗎?特別 M10(proactive exhaustive scan)/ M14(AUTO integrate pipeline)/ M17(SSOT 必可傳播)— 有受影響嗎?
+
+2. 2-Home canonical(spec.md = 不可程式化 judgment / tsx = 可程式化):本規則會把 canonical judgment 推到 references/ 嗎?若是違反 2-home,該留 spec/tsx。
+
+3. Rule-of-3:本規則概念已在 ≥ 3 處出現?若是,選 SSOT 其他 pointer only。
+
+4. Audit-vs-execute 分權:動到 canonical substantive meaning 嗎?若是,走 STOP 提議不 AUTO。
+
+5. 既有 SSOT 整合(對齊 CLAUDE.md SSOT 消費 canonical):本規則該 cross-link 到哪個現有 spec / hook / skill?
+
+6. hook / skill 重複偵測:.claude/hooks/ 跟 .claude/skills/ 有既存類似功能嗎?若是擴充既有,而非新建。
+
+7. Phase F Self-improvement capture:本 skill 若是 audit 類,Phase F 有無 Self-improvement capture step?
+
+規則:在 response 明確列出 7 題答案(可簡短)。有任一題 fail → 停下重設計不寫入。通過才寫。
+EOF
+)
+
+ESCAPED=$(printf '%s' "$MSG" | jq -Rs .)
+printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":%s}}\n' "$ESCAPED"
+exit 0

package/ds-canonical/hooks/retired/check_icon_only_padding_formula.sh

@@ -0,0 +1,104 @@
+#!/bin/bash
+# PreToolUse hook: 偵測 icon-only host 用 padding-formula `(field-height - <iconPx>) / 2`
+# 派(舊 idiom),warn 改用 padding-free `ICON_ONLY_BASE = 'aspect-square p-0 min-w-0 gap-0'`。
+#
+# Motivation(2026-04-25 user 在 Safari mobile DS Devmode 抓到 14×16 asymmetric):
+#   舊 padding-formula 公式沒扣 border 2px → SVG 被 flex `min-w-0` 擠成 width<intrinsic
+#   asymmetric(width=14px / height=16px,對齊 `--font-body-size` / `--font-body-lg-size`)。
+#   修法 = padding-free idiom(Polaris/Atlassian 派),消除 magic number 完全。
+#
+# SSOT:`tokens/uiSize/uiSize.spec.md`「Icon-only 元件的 padding canonical」節。
+# 已 migrate consumers:Button + SegmentedControl(2026-04-25)。
+#
+# Detection 規則(同時滿足才 fire):
+#   1. .tsx 含 `iconOnly` keyword(prop / variant / variable name)
+#   2. AND 含 `(var(--field-height-X) - <iconPx>px)` 公式 — iconPx ∈ {14,16,20,24}
+#      (vertical centering 公式 `(field-height - 1lh)/2` 不觸發,因為 1lh 不是 px 數字)
+#
+# Allowlist:
+#   //  @icon-only-padding-allow: <reason>(整檔豁免)
+#
+# Exit codes:
+#   exit 0(non-blocking,injected context only)— PreToolUse 注入 warning,
+#     依 user 判斷是否 migrate;不 hard block 因為某些舊 layer 公式可能仍合法。
+
+# Per-hook fire logging
+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
+
+# 只查 design-system tsx(不查 stories 不查 test)
+case "$FILE_PATH" in
+  */packages/design-system/src/components/*.tsx|*/packages/design-system/src/patterns/*.tsx) ;;
+  *) exit 0 ;;
+esac
+case "$FILE_PATH" in
+  *.stories.tsx|*.test.tsx|*.spec.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
+
+# Allowlist
+FIRST=$(printf '%s\n' "$NEW_CONTENT" | sed -n '1,5p')
+if echo "$FIRST" | grep -qE '//[[:space:]]*@icon-only-padding-allow:'; then
+  exit 0
+fi
+if [ -f "$FILE_PATH" ]; then
+  ON_DISK=$(sed -n '1,5p' "$FILE_PATH" 2>/dev/null || true)
+  if echo "$ON_DISK" | grep -qE '//[[:space:]]*@icon-only-padding-allow:'; then
+    exit 0
+  fi
+fi
+
+# Combine new content with existing on-disk(若 Edit 局部改不一定包含 iconOnly)
+COMBINED="$NEW_CONTENT"
+if [ -f "$FILE_PATH" ]; then
+  COMBINED="${COMBINED}
+$(cat "$FILE_PATH" 2>/dev/null || echo "")"
+fi
+
+HAS_ICONONLY=0
+HAS_FORMULA=0
+FORMULA_SAMPLE=""
+
+if echo "$COMBINED" | grep -qE 'iconOnly|ICON_ONLY|icon-only'; then
+  HAS_ICONONLY=1
+fi
+
+# Match `(var(--field-height-X) - <iconPx>px ...) / 2` where iconPx ∈ 14/16/20/24
+MATCH=$(printf '%s\n' "$COMBINED" | grep -oE 'calc\(\(var\(--field-height-(xs|sm|md|lg)\)\s*-\s*(14|16|20|24)px[^)]*\)\s*/\s*2\)' | head -1 || true)
+if [ -n "$MATCH" ]; then
+  HAS_FORMULA=1
+  FORMULA_SAMPLE="$MATCH"
+fi
+
+if [ "$HAS_ICONONLY" = "1" ] && [ "$HAS_FORMULA" = "1" ]; then
+  MSG="🚨 iconOnly host 用 padding-formula(舊 idiom)— $(basename "$FILE_PATH")\n\n"
+  MSG="${MSG}偵測到:${FORMULA_SAMPLE}\n\n"
+  MSG="${MSG}Canonical(2026-04-25):iconOnly 必用 padding-free idiom\n\n"
+  MSG="${MSG}\`\`\`tsx\nconst ICON_ONLY_BASE = 'aspect-square p-0 min-w-0 gap-0'\n\`\`\`\n\n"
+  MSG="${MSG}舊 idiom bug origin:公式沒扣 border 2px → SVG 被 flex min-w-0 擠成 14×16 不對稱。\n"
+  MSG="${MSG}World-class 派(Polaris / Atlassian)走 padding-free,我們對齊。\n\n"
+  MSG="${MSG}SSOT:tokens/uiSize/uiSize.spec.md「Icon-only 元件的 padding canonical」\n"
+  MSG="${MSG}參照 migrated consumers:components/Button/button.tsx + components/SegmentedControl/segmented-control.tsx\n\n"
+  MSG="${MSG}若此檔屬刻意保留舊公式(極罕見、需 spec rationale),檔首加 // @icon-only-padding-allow: <reason>"
+  ESCAPED=$(printf '%b' "$MSG" | jq -Rs .)
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":%s}}\n' "$ESCAPED"
+fi
+
+exit 0

package/ds-canonical/hooks/retired/check_item_content_primitive.sh

@@ -0,0 +1,150 @@
+#!/bin/bash
+# PreToolUse hook: detect hard-coded `mt-0.5` / `gap-0.5` in component .tsx(非 stories)
+# 應改用 `var(--item-gap-label-desc)` token OR `<ItemContent>` primitive。
+#
+# Motivation (2026-04-23 SSOT architecture · item-anatomy「Label ↔ Desc 間距」token/primitive):
+#   User 指出 mt-0.5 canonical 是 markdown 文字 / 13+ 消費者各自 hard-code = 非真 SSOT。
+#   已建 `--item-gap-label-desc` token + `<ItemContent>` primitive,消費者應:
+#     (a) 直接消費 token:`mt-[var(--item-gap-label-desc)]`
+#     (b) 消費 primitive:`<ItemContent label desc ...>`
+#   Hard-code `mt-0.5` / `gap-0.5` 會讓改值時漏同步 → DS drift
+#
+# 檢查 pattern:
+#   P1 WARN  .tsx 有 `mt-0.5` / `gap-0.5` 字面 class → warn 改 token / primitive
+#
+# Scope: component / pattern .tsx(跳過 stories、跳過已知例外 Calendar event / FileViewer zoom)
+#
+# Allowlist:
+#   // @item-gap-exempt: <reason>(整檔豁免 — consumer 有明文 rationale)
+#   // @item-gap-exempt-next(下一行豁免)
+#
+# Exit codes:
+#   exit 0 — pass OR warn only(不 block)
+
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+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 check .tsx in components/ or patterns/(不查 stories / markdown / css)
+case "$FILE_PATH" in
+  */packages/design-system/src/components/*.tsx|*/packages/design-system/src/patterns/*.tsx) ;;
+  *) exit 0 ;;
+esac
+
+# Skip stories
+case "$FILE_PATH" in
+  *.stories.tsx|*.anatomy.stories.tsx|*.principles.stories.tsx) exit 0 ;;
+esac
+
+# Skip known-exempt files(Calendar event column / FileViewer zoom pill — 非 label-desc 語義)
+case "$FILE_PATH" in
+  */Calendar/calendar.tsx|*/FileViewer/file-viewer.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 "")
+
+if [ -z "${NEW_CONTENT//[[:space:]]/}" ]; then
+  exit 0
+fi
+
+# File-level allowlist
+FIRST_LINES=$(printf '%s\n' "$NEW_CONTENT" | sed -n '1,3p')
+if echo "$FIRST_LINES" | grep -qE '//[[:space:]]*@item-gap-exempt:'; then
+  exit 0
+fi
+if [ -f "$FILE_PATH" ]; then
+  ON_DISK_FIRST=$(sed -n '1,3p' "$FILE_PATH" 2>/dev/null || true)
+  if echo "$ON_DISK_FIRST" | grep -qE '//[[:space:]]*@item-gap-exempt:'; then
+    exit 0
+  fi
+fi
+
+WARN_VIOLATIONS=""
+
+TMP=$(mktemp)
+trap 'rm -f "$TMP"' EXIT
+printf '%s\n' "$NEW_CONTENT" > "$TMP"
+
+ROW=0
+SKIP_NEXT=0
+while IFS= read -r LINE || [ -n "$LINE" ]; do
+  ROW=$((ROW+1))
+
+  if [ "$SKIP_NEXT" = "1" ]; then
+    SKIP_NEXT=0
+    continue
+  fi
+  if echo "$LINE" | grep -qE '//[[:space:]]*@item-gap-exempt-next|\{/\*[[:space:]]*@item-gap-exempt-next'; then
+    SKIP_NEXT=1
+    continue
+  fi
+
+  # P1 WARN: `mt-0.5` or `gap-0.5` 硬寫(非 comment)
+  # heuristic:line 含 className=".*mt-0\.5|.*gap-0\.5" 且非純 comment
+  if echo "$LINE" | grep -qE 'className\s*=\s*\{?[^}]*"[^"]*\b(mt-0\.5|gap-0\.5)\b' \
+     || echo "$LINE" | grep -qE "'[^']*\b(mt-0\.5|gap-0\.5)\b[^']*'"; then
+    WARN_VIOLATIONS="${WARN_VIOLATIONS}
+────────────────────────────────
+[P1 hard-coded mt-0.5 / gap-0.5(warn)] ${FILE_PATH}:${ROW}
+  > $(echo "$LINE" | sed 's/^[[:space:]]*//' | cut -c1-120)
+  建議修法(擇一):
+    (a) 用 token:改成 \`mt-[var(--item-gap-label-desc)]\` / \`gap-[var(--item-gap-label-desc)]\`
+    (b) 用 primitive:改用 \`<ItemContent label description descriptionTone mode>\`
+        (from \`@/design-system/patterns/element-anatomy/item-anatomy\`)
+  若此處刻意 hard-code 有 rationale,在該 tsx 檔首加 // @item-gap-exempt: <reason>
+  SSOT: tokens/layoutSpace/layoutSpace.css + patterns/element-anatomy/item-anatomy.tsx(ItemContent)"
+  fi
+
+  # P2 WARN: suffix block formula `calc(1lh+2px+...)` 硬寫 2px(應用 token)
+  if echo "$LINE" | grep -qE 'calc\(1lh\+2px\+'; then
+    WARN_VIOLATIONS="${WARN_VIOLATIONS}
+────────────────────────────────
+[P2 hard-coded 2px in calc formula(warn)] ${FILE_PATH}:${ROW}
+  > $(echo "$LINE" | sed 's/^[[:space:]]*//' | cut -c1-120)
+  建議修法:\`calc(1lh+2px+...)\` → \`calc(1lh+var(--item-gap-label-desc)+...)\`
+  Rationale:block formula 的 gap 2px 應跟 inline label↔desc gap 共用 SSOT token,
+  確保「改 token 一處 → inline + block 兩層 formula 同步」。
+  SSOT: tokens/layoutSpace/layoutSpace.css(\`--item-gap-label-desc\`)"
+  fi
+
+  # P3 WARN: `h-[1lh] shrink-0 flex items-center` 手刻 prefix wrapper(應用 ItemPrefix primitive)
+  if echo "$LINE" | grep -qE '"[^"]*\bh-\[1lh\]\s+shrink-0\s+flex\s+items-center\b'; then
+    WARN_VIOLATIONS="${WARN_VIOLATIONS}
+────────────────────────────────
+[P3 hard-coded prefix wrapper(warn)] ${FILE_PATH}:${ROW}
+  > $(echo "$LINE" | sed 's/^[[:space:]]*//' | cut -c1-120)
+  建議修法:改用 \`<ItemPrefix>\` primitive
+    (from \`@/design-system/patterns/element-anatomy/item-anatomy\`)
+  Rationale:\`h-[1lh] shrink-0 flex items-center\` 是 item-anatomy「Prefix 垂直對齊」
+  canonical 的實作細節,ItemPrefix 已封裝(+ \`min-w-[var(--item-prefix-slot,auto)]\` 對齊行為)。
+  手刻 = 未來改 prefix wrapper 規則需手動 grep 26+ 檔。
+  若本 span 有 **特殊 width / justify-content 需求**(例如 TreeView 固定 iconPx 寬):
+  加 // @item-gap-exempt-next 到此行上一行(必須附 rationale 在 spec.md)。
+  SSOT: patterns/element-anatomy/item-anatomy.tsx(ItemPrefix)"
+  fi
+
+done < "$TMP"
+
+if [ -n "$WARN_VIOLATIONS" ]; then
+  {
+    echo ""
+    echo "┄┄┄┄ check_item_content_primitive — hard-coded mt-0.5 / gap-0.5(warn) ┄┄┄┄"
+    printf '%s\n' "$WARN_VIOLATIONS"
+  } >&2
+fi
+
+exit 0

package/ds-canonical/hooks/retired/check_item_list_gap.sh

@@ -0,0 +1,153 @@
+#!/bin/bash
+# PreToolUse hook: detect FileItem list wrapper 加外框(P2 block)或 likely-missing gap(P1 warn)。
+#
+# Motivation(CLAUDE.md「連續 item 貼邊合法性」v2 canonical · 2026-04-22):
+#   Permanent standalone card/pill(bg + radius + inset)→ 必 gap(防融合)
+#   Permanent flush full-width / transparent → 0 gap 合法(靠 border-b / progress bar / separator)
+#
+#   FileItem rich    → permanent border card → standalone → 必 gap-2
+#   FileItem compact no status(Type B form attachment) → permanent bg-secondary pill → 必 gap-1
+#   FileItem compact with status(Type A upload manager) → flush + progress bar 分隔線型 → 0 gap 合法
+#
+# 檢查 patterns(scope: FileItem MVP,未來可擴其他 standalone card 類元件):
+#   P1  list wrapper `flex-col` 無 `gap-*` + FileItem map 內 → **WARN**(exit 0 + stderr)
+#       靜態 grep 難 reliably 區分 Type A / Type B,交給人判斷
+#   P2  list wrapper 加 `border` / `overflow-hidden` / `rounded-lg` + FileItem map 內 → **BLOCK**(exit 2)
+#       無論 Type A / B / rich,外框 + overflow-hidden 都是 wrong(強制邊框相黏、雙重 card)
+#
+# Allowlist:
+#   // @item-gap-exempt: <reason>
+#
+# Exit codes:
+#   exit 0 — pass(OR P1 warn only,stderr has 訊息但不 block)
+#   exit 2 + stderr — P2 block
+
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+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
+  *.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 "")
+
+if [ -z "${NEW_CONTENT//[[:space:]]/}" ]; then
+  exit 0
+fi
+
+# Allowlist
+FIRST_LINES=$(printf '%s\n' "$NEW_CONTENT" | sed -n '1,3p')
+if echo "$FIRST_LINES" | grep -qE '//[[:space:]]*@item-gap-exempt:'; then
+  exit 0
+fi
+if [ -f "$FILE_PATH" ]; then
+  ON_DISK_FIRST=$(sed -n '1,3p' "$FILE_PATH" 2>/dev/null || true)
+  if echo "$ON_DISK_FIRST" | grep -qE '//[[:space:]]*@item-gap-exempt:'; then
+    exit 0
+  fi
+fi
+
+# 需要全檔內容上下文(map 外層 wrapper 通常在 FileItem 上方幾行),用合併後的檔案新狀態掃描
+if [ -f "$FILE_PATH" ]; then
+  FULL_CONTENT=$(cat "$FILE_PATH" 2>/dev/null)
+  # Edit 類: 檔案修改後的實際樣子(簡化:直接讀 on-disk + incoming content 合併判斷)
+  # 這裡保守用 NEW_CONTENT 為主(incoming changes)
+  CONTENT="$NEW_CONTENT"
+else
+  CONTENT="$NEW_CONTENT"
+fi
+
+BLOCK_VIOLATIONS=""   # P2 — always wrong(block)
+WARN_VIOLATIONS=""    # P1 — likely wrong but depends on Type A/B(warn,不 block)
+
+TMP=$(mktemp)
+trap 'rm -f "$TMP"' EXIT
+printf '%s\n' "$CONTENT" > "$TMP"
+
+ROW=0
+while IFS= read -r LINE || [ -n "$LINE" ]; do
+  ROW=$((ROW+1))
+
+  # P2 BLOCK: wrapper 有 border / overflow-hidden / rounded-lg 外框 + FileItem map → 總是錯
+  if echo "$LINE" | grep -qE '<div[^>]*className="[^"]*\bflex-col\b[^"]*\b(border|overflow-hidden|rounded-lg)\b'; then
+    END=$((ROW+6))
+    LOOKAHEAD=$(sed -n "$((ROW+1)),${END}p" "$TMP" 2>/dev/null || true)
+    if echo "$LOOKAHEAD" | grep -qE '<FileItem\b'; then
+      BLOCK_VIOLATIONS="${BLOCK_VIOLATIONS}
+────────────────────────────────
+[P2 list wrapper 加外框] ${FILE_PATH}:${ROW}
+  > $(echo "$LINE" | sed 's/^[[:space:]]*//' | cut -c1-120)
+  修法: FileItem rich 自帶 border card、compact 自帶 bg-secondary(Type B)或 progress bar(Type A)。
+        list wrapper **不應**再加 border / rounded-lg / overflow-hidden。
+        (overflow-hidden 會強制邊框合併、雙重外框破壞 card 自立)
+        改用:<div className=\"flex flex-col [gap-*]\">
+        SSOT: components/FileItem/file-item.spec.md「List wrapper canonical」"
+    fi
+  fi
+
+  # P1 WARN: wrapper flex-col 無 gap + FileItem map → 可能缺 gap(Type A / B 判斷由人)
+  if echo "$LINE" | grep -qE '<div[^>]*className="[^"]*\bflex-col\b[^"]*"' \
+     && ! echo "$LINE" | grep -qE '\bgap-[0-9]' \
+     && ! echo "$LINE" | grep -qE 'gap-\[var\(--'; then
+    END=$((ROW+6))
+    LOOKAHEAD=$(sed -n "$((ROW+1)),${END}p" "$TMP" 2>/dev/null || true)
+    if echo "$LOOKAHEAD" | grep -qE '<FileItem\b'; then
+      WARN_VIOLATIONS="${WARN_VIOLATIONS}
+────────────────────────────────
+[P1 list wrapper 可能缺 gap(warn)] ${FILE_PATH}:${ROW}
+  > $(echo "$LINE" | sed 's/^[[:space:]]*//' | cut -c1-120)
+  判斷: FileItem 依 mode / status 有不同 gap 需求:
+          rich(任何 status)        → standalone card → 必 gap-2
+          compact + 無 status(Type B) → standalone pill(bg-secondary)→ 必 gap-1
+          compact + 有 status(Type A) → flush + progress bar 分隔線 → 0 gap 合法
+        若此處是 Type A(compact 上傳狀態,progress bar 作分隔)→ 合法,可忽略。
+        若是 rich / Type B → 補 gap-2 / gap-1。
+        SSOT: patterns/element-anatomy/item-anatomy.spec.md「連續 item 貼邊合法性 v2」"
+    fi
+  fi
+
+done < "$TMP"
+
+# Emit warnings(stderr but continue)
+if [ -n "$WARN_VIOLATIONS" ]; then
+  {
+    echo ""
+    echo "┄┄┄┄ check_item_list_gap — P1 warn(可能缺 gap,依 mode/status 判斷) ┄┄┄┄"
+    printf '%s\n' "$WARN_VIOLATIONS"
+  } >&2
+fi
+
+# Emit block only for P2
+if [ -n "$BLOCK_VIOLATIONS" ]; then
+  {
+    echo ""
+    echo "╔════════════════════════════════════════════════════════════════"
+    echo "║ check_item_list_gap — list wrapper 加外框(P2 block)"
+    echo "╚════════════════════════════════════════════════════════════════"
+    printf '%s\n' "$BLOCK_VIOLATIONS"
+    echo ""
+    echo "────────────────────────────────"
+    echo "SSOT canonical:"
+    echo "  - patterns/element-anatomy/item-anatomy.spec.md「連續 item 貼邊合法性 v2」"
+    echo "  - components/FileItem/file-item.spec.md「List wrapper canonical」"
+  } >&2
+  exit 2
+fi
+
+exit 0

package/ds-canonical/hooks/retired/check_sideoffset_canonical.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# PostToolUse hook: catch non-canonical sideOffset overrides on overlay primitives.
+#
+# DS canonical: all overlay primitives (Popover / Tooltip / DropdownMenu / HoverCard /
+# SelectMenu / Coachmark) use sideOffset=8 (Notion / Linear / Figma 6-8px idiom).
+# Consumers should NEVER override sideOffset — if they think they need to, the
+# visual is fighting the DS and the right fix is to discuss, not to patch locally.
+#
+# This hook warns when a file sets sideOffset to anything other than 8 (the DS
+# canonical). Overlay primitive SOURCE files are exempt (they set the default).
+#
+# Trigger: PostToolUse on Edit/Write/MultiEdit for any .tsx/.md file that
+# contains `sideOffset=`.
+
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -euo pipefail
+
+FILE_PATH="${CLAUDE_TOOL_INPUT_FILE_PATH:-}"
+
+# Only .tsx / .md files
+case "$FILE_PATH" in
+  *.tsx|*.md) ;;
+  *) exit 0 ;;
+esac
+
+[ -f "$FILE_PATH" ] || exit 0
+
+# Exempt the overlay primitive source files themselves (they set defaults).
+case "$FILE_PATH" in
+  */Popover/popover.tsx) exit 0 ;;
+  */Tooltip/tooltip.tsx) exit 0 ;;
+  */DropdownMenu/dropdown-menu.tsx) exit 0 ;;
+  */HoverCard/hover-card.tsx) exit 0 ;;
+  */SelectMenu/select-menu.tsx) exit 0 ;;
+  */Coachmark/coachmark.tsx) exit 0 ;;
+esac
+
+# Look for sideOffset set to a literal number != 8
+# Matches: sideOffset={4}  sideOffset = 4  sideOffset={12}  etc.
+# Does NOT match:
+#   sideOffset={8}                                                (canonical)
+#   sideOffset={sideOffset}                                       (prop passthrough)
+#   sideOffset (mentioned in prose / tables / comments)
+VIOLATIONS=$(grep -nE 'sideOffset[[:space:]]*=[[:space:]]*\{[[:space:]]*[0-9]+[[:space:]]*\}' "$FILE_PATH" 2>/dev/null \
+  | grep -vE 'sideOffset[[:space:]]*=[[:space:]]*\{[[:space:]]*8[[:space:]]*\}' || true)
+
+if [ -n "$VIOLATIONS" ]; then
+  cat <<EOF
+⚠️  Non-canonical \`sideOffset\` override — $FILE_PATH
+
+$VIOLATIONS
+
+DS canonical: all overlay primitives use \`sideOffset={8}\` (世界級 idiom, Notion /
+Linear / Figma / Stripe 6-8px). Consumer should NOT override. If the default
+feels wrong visually, the fix is to discuss & change the canonical — NOT to
+sprinkle \`sideOffset={4}\` locally.
+
+Remove the override unless you have a documented exception. See
+\`components/Popover/popover.spec.md\` 「觸發距離 canonical」.
+EOF
+fi
+
+exit 0