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

package/ds-canonical/hooks/retired/2026-06-11-prune-merge/check_plugin_freshness.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+# check_plugin_freshness.sh — SessionStart soft notice
+#
+# Detect if installed DS plugin version is behind latest marketplace.json on GitHub
+# → notify fork user to run `/plugin marketplace update + /plugin install latest`.
+#
+# Per user 2026-05-27 verbatim「DS push main 一律自動同步 PW」directive.
+# Claude Code SDK 沒 auto-poll marketplace mechanism — workaround: session_start
+# 偵測 staleness → prompt user 手動 update。
+#
+# Mechanism:
+#   1. Read local plugin.json version
+#   2. Fetch latest DS marketplace.json from GitHub raw (no auth needed for public repo)
+#   3. Compare versions → if behind → emit notice to stdout (visible in session start)
+#
+# Soft notice only (exit 0) — doesn't block. Fork user decides when to update.
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null || echo "{}")
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+
+case "${EVENT:-}" in
+  SessionStart) ;;
+  *) exit 0 ;;
+esac
+
+# Find local plugin.json (DS plugin install path)
+PLUGIN_JSON=""
+for candidate in \
+  "$HOME/.claude/plugins/design-system@qijenchen-ds/plugin.json" \
+  "$HOME/.claude/plugins/cache/design-system/plugin.json" \
+  "${CLAUDE_PROJECT_DIR:-.}/.claude-plugin/plugin.json"
+do
+  if [ -f "$candidate" ]; then PLUGIN_JSON="$candidate"; break; fi
+done
+
+if [ -z "$PLUGIN_JSON" ]; then exit 0; fi
+
+LOCAL_VERSION=$(jq -r '.version // ""' "$PLUGIN_JSON" 2>/dev/null)
+if [ -z "$LOCAL_VERSION" ]; then exit 0; fi
+
+# Fetch latest marketplace.json from GitHub raw (5s timeout, fail silently if offline)
+REMOTE_VERSION=$(curl -sS --max-time 5 \
+  "https://raw.githubusercontent.com/ajenchen/design-system/main/.claude-plugin/marketplace.json" \
+  2>/dev/null | jq -r '.metadata.version // ""' 2>/dev/null)
+
+if [ -z "$REMOTE_VERSION" ] || [ "$REMOTE_VERSION" = "null" ]; then exit 0; fi
+
+if [ "$LOCAL_VERSION" != "$REMOTE_VERSION" ]; then
+  cat << EOF
+
+📦 DS plugin update available:
+   Local installed: $LOCAL_VERSION
+   Latest published: $REMOTE_VERSION
+
+Run in terminal (1 command):
+  npm run sync-all  # npm + plugin marketplace + plugin install + restart prompt
+
+
+(Per user 2026-05-27 directive「DS 增刪改自動同步」— this hook detects staleness on session start.)
+
+EOF
+fi
+
+exit 0

package/ds-canonical/hooks/retired/2026-06-11-prune-merge/check_propose_cite_required.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+# check_propose_cite_required.sh — P1 BLOCKER
+#
+# 攔 AI 在對話講「DS 規定 / spec 規定 / canonical 寫 / 必配 / 必須用 / 必須是」
+# 沒附 file:line cite 的瞎掰 propose(2026-05-27 user verbatim「沒有好好按照規則
+# 和 ssot 跑設計，然後淨問我一下蠢問題」永久 codify)。
+#
+# Anchor 錨點:2026-05-27 我憑印象斷言「DS spec 規定 caption + muted 是標準組合」,
+# user grep verify 發現 semantic.css L49 只是 token use-case 描述,**沒「必配」rule**。
+# DS 自家 typography.stories.tsx 同時用 caption+secondary 跟 caption+muted。
+# 我瞎掰造成 user 接受錯誤 propose 風險。
+#
+# Stop hook(post-assistant turn)偵測:
+#   - Reply 含 claim keyword:「規定 / 必配 / 必須用 / 必須是 / canonical 寫 / spec 寫 / 強制」
+#   - 同 reply 無 cite:`<filename>.{spec\.md|css|tsx|ts}:\d+` 或 `L\d+` 或 `line \d+`
+#   - 觸發 BLOCKER 要求 retract 或補 cite
+#
+# Escape:Reply 含 `<!-- @propose-cite-skip: <rationale> -->` 顯式跳(極罕見)
+#
+# 對齊:M22 cite invariant(commit/spec)延伸到對話 propose 層 + mindset #2「不憑直覺發明」mechanical 強制。
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null || echo "{}")
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // ""' 2>/dev/null)
+
+# Only fire on stop events (post-assistant turn)
+case "${EVENT:-}" in
+  Stop|SubagentStop) ;;
+  *) exit 0 ;;
+esac
+
+# Read last assistant message
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null)
+[ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ] && exit 0
+
+LAST_REPLY=$(tail -200 "$TRANSCRIPT" 2>/dev/null | grep -E '"role":"assistant"|"type":"text"' | tail -50 | tr -d '\n' | head -c 8000)
+
+# Escape clause
+if echo "$LAST_REPLY" | grep -q 'propose-cite-skip'; then
+  exit 0
+fi
+
+# Detect claim keywords
+HAS_CLAIM=""
+for kw in '規定' '必配' '必須用' '必須是' '一定要' 'canonical 寫' 'spec 寫' '強制' 'DS spec 規定' '明文' 'mandate'; do
+  if echo "$LAST_REPLY" | grep -qF "$kw"; then
+    HAS_CLAIM="$kw"
+    break
+  fi
+done
+
+if [ -z "$HAS_CLAIM" ]; then
+  exit 0
+fi
+
+# Detect cite patterns
+# Accept: file.spec.md:42 | file.css:42 | file.tsx:42 | file.ts:42 | L42 | line 42 | semantic.css#L42
+HAS_CITE=""
+if echo "$LAST_REPLY" | grep -qE '\.(spec\.md|css|tsx|ts|json):[0-9]+|#L[0-9]+|line[[:space:]]+[0-9]+|L[0-9]+-[0-9]+|L[0-9]+'; then
+  HAS_CITE="found"
+fi
+
+if [ -z "$HAS_CITE" ]; then
+  cat >&2 << 'EOF'
+🚨 PROPOSE-WITHOUT-CITE BLOCKER(2026-05-27 user verbatim「沒有好好按照規則和 ssot 跑設計」)
+
+  你 reply 含 claim keyword(規定 / 必配 / 必須用 / canonical 寫 / spec 寫 / 強制)
+  但**無 file:line cite**(`.spec.md:42` / `.css:42` / `.tsx:42` / `L42` / `line 42` 任一)。
+
+  Anchor 2026-05-27:我憑印象斷言「DS spec 規定 caption + muted」,user grep verify
+  發現 semantic.css L49 只是 token use-case 描述,**沒「必配」rule**。瞎掰造成 user
+  接受錯誤 propose 風險。
+
+  修方向 2 選 1:
+    (a) 補 cite — 把 spec / source path:line 補進 reply,讓 user verify
+    (b) 撤回 claim — 顯式打「撤回 claim:此條無 SSOT 依據」
+
+  Escape(極罕見):reply 含 `<!-- @propose-cite-skip: <rationale> -->`
+
+  對齊 M22 cite invariant 延伸到對話層 + mindset #2「不憑直覺發明」mechanical 強制。
+EOF
+  exit 2
+fi
+
+exit 0

package/ds-canonical/hooks/retired/2026-06-11-prune-merge/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_discipline.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_discipline.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/retired/2026-06-11-prune-merge/check_storybook_addon_preset_cjs.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+# check_storybook_addon_preset_cjs.sh — P0 BLOCKER
+#
+# 2026-05-28 beta.27-.31 5 連敗 anchor:storybook-config addon preset.ts 用
+# `createRequire` / `fileURLToPath` 在 `"type":"module"` package 內,被 Node ESM
+# scope 攔(`require is not defined`)。Root cause = ESM/esbuild-register CJS-interop
+# 衝突。Fix = hand-written `preset.cjs`(`.cjs` override package type field 強制 CJS)。
+#
+# SSOT:memory/feedback_storybook_addon_preset_must_be_cjs.md
+#
+# Mechanical 強制 PreToolUse Edit/Write 對 storybook-addon preset files:
+# - `preset.ts` 含 `require.resolve` / `createRequire` / `fileURLToPath` → BLOCK
+# - 提示用 `.cjs` extension 替代 + path.join(__dirname, ...) canonical pattern
+#
+# Scope:**/addons/**/preset.ts(in monorepo packages/* OR .storybook/addons/*)
+# Escape:`@preset-cjs-skip:` comment(極罕見,需 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 // ""' 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

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

@@ -0,0 +1,106 @@
+#!/bin/bash
+# PostToolUse hook: when editing a *.anatomy.stories.tsx file, verify section
+# numbering matches canonical slot rules (updated 2026-04-22 to align with
+# anatomy-standard.md's「保留 canonical 編號」rule).
+#
+# Canonical slots:
+#   1 = Overview      (reserved)
+#   2 = Inspector     (reserved)
+#   3 = ColorMatrix   (reserved)
+#   4 = SizeMatrix    (reserved)
+#   5 = StateBehavior (reserved)
+#   6+ = custom sections (contiguous from 6 onwards)
+#
+# **N/A slots keep their reserved number unused** (e.g. Calendar has no
+# SizeMatrix → file has 1,2,3,5 with a gap at 4). This is correct per canonical;
+# the previous hook version enforced strict contiguous 1..N which contradicted
+# canonical — reconciled 2026-04-22.
+#
+# Rules:
+#   - Slots in 1..5 MUST be one of the canonical set (1=Overview/2=Inspector/...)
+#     but may have gaps for N/A sections
+#   - Slots 6+ MUST be contiguous starting from 6 (no gaps in custom section tail)
+#   - No duplicate numbers anywhere
+#
+# Trigger: PostToolUse on Edit/Write/MultiEdit where file_path ends in
+# `.anatomy.stories.tsx`.
+
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+FILE_PATH="${CLAUDE_TOOL_INPUT_FILE_PATH:-}"
+
+case "$FILE_PATH" in
+  *.anatomy.stories.tsx) ;;
+  *) exit 0 ;;
+esac
+
+[ -f "$FILE_PATH" ] || exit 0
+
+NUMS=$(grep -oE "name:[[:space:]]*'[0-9]+\." "$FILE_PATH" 2>/dev/null | grep -oE "[0-9]+" | tr '\n' ' ')
+
+if [ -z "${NUMS// }" ]; then
+  exit 0
+fi
+
+BROKEN=0
+BROKEN_DETAIL=""
+SEEN=""
+
+# Sort numbers to check set properties (Storybook sidebar sorts by name prefix,
+# so file export order doesn't matter for UX)
+SORTED=$(echo "$NUMS" | tr ' ' '\n' | sort -n | tr '\n' ' ')
+
+# Check 1: no duplicates
+for N in $NUMS; do
+  case " $SEEN " in
+    *" $N "*)
+      BROKEN=1
+      BROKEN_DETAIL="${BROKEN_DETAIL}\n  • Duplicate slot number: ${N}"
+      ;;
+  esac
+  SEEN="$SEEN $N"
+done
+
+# Check 2: custom sections 6+ must form contiguous block starting from 6
+PREV=5
+for N in $SORTED; do
+  if [ "$N" -ge 6 ]; then
+    EXPECTED=$((PREV + 1))
+    if [ "$N" -ne "$EXPECTED" ]; then
+      BROKEN=1
+      BROKEN_DETAIL="${BROKEN_DETAIL}\n  • Custom section gap: expected ${EXPECTED}, got ${N}(6+ 必連續,不可跳號)"
+    fi
+    PREV="$N"
+  fi
+done
+
+# Check 3: canonical slot range validation
+for N in $NUMS; do
+  if [ "$N" -lt 1 ]; then
+    BROKEN=1
+    BROKEN_DETAIL="${BROKEN_DETAIL}\n  • Invalid slot: ${N}(must be ≥ 1)"
+  fi
+done
+
+if [ "$BROKEN" = "1" ]; then
+  cat <<EOF
+⚠️  Anatomy story numbering drift — $FILE_PATH
+
+Got sequence: $NUMS
+
+Issues:$(printf "%b" "$BROKEN_DETAIL")
+
+Canonical slots(anatomy-standard.md「保留 canonical 編號」):
+  1 = Overview     2 = Inspector     3 = ColorMatrix
+  4 = SizeMatrix   5 = StateBehavior
+  6+ = custom sections(contiguous from 6)
+
+N/A canonical slot 保留編號不 renumber(e.g. 無 SizeMatrix → 1,2,3,5 正確)。
+自訂 section 必從 6 開始連續(不可混入 1-5 slot 號)。
+EOF
+fi
+
+exit 0

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

@@ -0,0 +1,90 @@
+#!/bin/bash
+# PostToolUse hook: enforce "person avatar → NameCard hoverCard" DS-wide canonical.
+#
+# Canonical source: packages/design-system/src/components/Avatar/avatar.spec.md
+#   「Avatar HoverCard 原則(DS-wide canonical,必遵守)」section
+#
+# Rule: any `<Avatar>` with `alt="..."` that looks like a PERSON name
+#   must also have `hoverCard={...}` prop (typically `<NameCard .../>`).
+#
+# Person-name heuristic (avoid false positive on entity names):
+#   - alt contains a space (人名常有空格:"Alan Chen" / "張三 / Ada Chen")
+#   - alt pattern like Ch/En first+last name
+#   - OR alt is a variable like `{p.name}` / `{member.name}` / `{user.name}` / `{person.name}`
+#
+# Entity names (NOT person, exempt):
+#   - single word + company suffix (Inc / Corp / Ltd / Co)
+#   - icon shape (alt matches "icon" variable)
+#   - file thumbnails (shape="square")
+#
+# Output: WARN (additionalContext), not block — AI reads and fixes next iteration.
+
+# Per-hook fire logging(enables /knowledge-prune D2 dead-hook detection)
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+FILE_PATH=$(jq -r '.tool_input.file_path // empty')
+
+# Scope: only design-system files (tsx + stories.tsx)
+if ! echo "$FILE_PATH" | grep -qE 'src/(design-system|explorations|app)/.*\.tsx$'; then
+  exit 0
+fi
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Exempt core Avatar/NameCard/HoverCard self-files and some internal primitives
+if echo "$FILE_PATH" | grep -qE '(Avatar/avatar\.tsx|NameCard/|HoverCard/|Empty/empty\.tsx|FileItem/file-item\.tsx|PeoplePicker/person-display\.tsx)'; then
+  exit 0
+fi
+
+VIOLATIONS=""
+
+# Find <Avatar uses that look like person avatars but lack hoverCard
+# We match <Avatar ... alt={...name...} ... /> without hoverCard in the same tag
+PERSON_AVATARS=$(grep -nE '<Avatar[^>]*(alt=\{[^}]*\.name|alt="[A-Z][a-z]+\s[A-Z][a-z]+")' "$FILE_PATH" | while read -r line; do
+  # Extract line number + line content
+  LINE_NUM=$(echo "$line" | cut -d: -f1)
+  LINE_CONTENT=$(echo "$line" | cut -d: -f2-)
+  # Check: does this Avatar tag (multi-line possible) contain hoverCard?
+  # Read next 8 lines after start to catch multi-line <Avatar ... />
+  BLOCK=$(sed -n "${LINE_NUM},$(( LINE_NUM + 8 ))p" "$FILE_PATH")
+  if ! echo "$BLOCK" | grep -q "hoverCard"; then
+    echo "  - $FILE_PATH:$LINE_NUM — <Avatar alt=... without hoverCard (person avatar 需 NameCard — 見 avatar.spec.md「Avatar HoverCard 原則」)"
+  fi
+done)
+
+# Also check AvatarData object literals with .name-like alt
+AVATAR_DATA=$(grep -nE '\{[[:space:]]*alt:[[:space:]]*[`"'\''"]?[A-Z][a-z]+ [A-Z][a-z]+' "$FILE_PATH" | while read -r line; do
+  LINE_NUM=$(echo "$line" | cut -d: -f1)
+  # Check same object doesn't have hoverCard
+  BLOCK=$(sed -n "${LINE_NUM},$(( LINE_NUM + 3 ))p" "$FILE_PATH")
+  if ! echo "$BLOCK" | grep -q "hoverCard"; then
+    echo "  - $FILE_PATH:$LINE_NUM — AvatarData with person alt 缺 hoverCard (MenuItem/SelectionItem/SelectMenu avatar prop 支援 hoverCard,必傳 NameCard)"
+  fi
+done)
+
+if [ -n "$PERSON_AVATARS" ] || [ -n "$AVATAR_DATA" ]; then
+  VIOLATIONS="$PERSON_AVATARS
+$AVATAR_DATA"
+  cat <<EOF >&2
+⚠️ Person avatar 缺 hoverCard(NameCard):
+
+$VIOLATIONS
+
+Canonical:avatar.spec.md「Avatar HoverCard 原則(DS-wide canonical)」— person avatar 必 hover → NameCard(default,非 opt-in)。
+
+修法:
+  <Avatar
+    src={...} alt={person.name} size={N}
+    hoverCard={<NameCard name={person.name} subtitle={...} actions={<NameCardDefaultActions />} />}
+  />
+
+OR AvatarData:
+  { alt: person.name, src: ..., hoverCard: <NameCard ... /> }
+
+豁免(entity avatar,不適用):organization logo / 專案 icon / app icon / file thumbnail
+EOF
+  exit 0
+fi
+
+exit 0

package/ds-canonical/hooks/retired/check_button_icon_literal.sh.retired-2026-04-28

@@ -0,0 +1,38 @@
+#!/bin/bash
+# PostToolUse hook: catch literal icon characters in Button content (e.g. "+ 新增").
+#
+# Per .claude/rules/ui-development.md「Icon canonical」:
+# Icon 必須用 lucide-react component(Plus / X / Check / TriangleAlert / Info / etc),
+# 不可在 Button label 寫字面 "+" / "-" / "×" / "✓" / "→" 等符號當 icon 用。
+#
+# Detects: <Button ... >+ XX</Button> / <Button>↗ Open</Button> 等 pattern.
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+FILE_PATH=$(jq -r '.tool_input.file_path // empty')
+
+if ! echo "$FILE_PATH" | grep -qE '\.(tsx|stories\.tsx)$'; then
+  exit 0
+fi
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Match Button content starting with a single icon-like character + space
+# Examples that violate:
+#   <Button>+ 新增</Button>
+#   <Button>× Close</Button>
+#   <Button>→ Continue</Button>
+LITERAL_HITS=$(grep -nE '<Button[^>]*>\s*[-+×✕✗✓→←↑↓↗↖↘↙]\s+' "$FILE_PATH" 2>/dev/null | head -5)
+
+if [ -n "$LITERAL_HITS" ]; then
+  ADDITIONAL_CONTEXT=$(printf 'Button label 含字面 icon 字元(請改 lucide-react component):\n%s\n  映射: + → startIcon={Plus} / × → startIcon={X} / → → endIcon={ArrowRight} / ✓ → startIcon={Check}' "$LITERAL_HITS")
+  jq -n --arg ctx "$ADDITIONAL_CONTEXT" '{
+    hookSpecificOutput: {
+      hookEventName: "PostToolUse",
+      additionalContext: $ctx
+    }
+  }'
+fi
+
+exit 0