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

package/ds-canonical/hooks/check_opacity_token_usage.sh

@@ -11,7 +11,7 @@ set -uo pipefail
 # 檢的 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)
+#   - radius:rounded-{xl|2xl|3xl} / rounded(unscoped)/ rounded-[...] arbitrary(例外 rounded-[inherit])
 #   - 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 層)
@@ -22,10 +22,76 @@ set -uo pipefail
 # 修法:reuse semantic utility / token reference / var() bracket(詳 utility-registry.json `rationale_path`)。
 
 source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+source "$(dirname "$0")/lib/_provider_paths.sh" 2>/dev/null || {
+  printf 'GOVERNANCE_INTEGRITY: token registry provider resolver unavailable\n' >&2
+  exit 70
+}
+source "$(dirname "$0")/lib/_hook_integrity.sh" 2>/dev/null || {
+  printf 'GOVERNANCE_INTEGRITY: hook integrity helper unavailable\n' >&2
+  exit 70
+}
 
-INPUT=$(cat)
-TOOL=$(echo "$INPUT" | jq -r '.tool_name // ""')
-FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+_HOOK_CONTEXT_EVENT="PreToolUse"
+_HOOK_OUTPUT_CAPTURE=$(mktemp "${TMPDIR:-/tmp}/check-opacity-token-usage.XXXXXX") || {
+  printf 'GOVERNANCE_INTEGRITY: token registry output capture unavailable\n' >&2
+  exit 70
+}
+exec 3>&1 4>&2
+exec >"$_HOOK_OUTPUT_CAPTURE" 2>&1
+
+_finalize_hook_output() {
+  _hook_rc=$?
+  trap - EXIT
+  exec 1>&3 2>&4
+  _hook_output=$(cat "$_HOOK_OUTPUT_CAPTURE" 2>/dev/null || true)
+  rm -f "$_HOOK_OUTPUT_CAPTURE" 2>/dev/null || true
+
+  case "$_hook_rc" in
+    0)
+      [ -z "$_hook_output" ] && exit 0
+      if ! jq -cn \
+        --arg event "$_HOOK_CONTEXT_EVENT" \
+        --arg message "$_hook_output" \
+        '{governanceContext:{hookEventName:$event,message:$message}}'; then
+        printf 'GOVERNANCE_INTEGRITY: token registry warning envelope encoding failed\n' >&2
+        exit 70
+      fi
+      exit 0
+      ;;
+    2)
+      if grep -q 'GOVERNANCE_INTEGRITY:' <<<"$_hook_output"; then
+        printf '%s\n' "$_hook_output" >&2
+        exit 70
+      elif [ -n "$_hook_output" ]; then
+        printf '%s\n' "$_hook_output" >&2
+      else
+        printf 'token registry hook blocked without diagnostic\n' >&2
+      fi
+      exit 2
+      ;;
+    70)
+      if [ -n "$_hook_output" ]; then
+        printf '%s\n' "$_hook_output" >&2
+      else
+        printf 'GOVERNANCE_INTEGRITY: token registry failed without diagnostic\n' >&2
+      fi
+      exit 70
+      ;;
+    *)
+      printf 'GOVERNANCE_INTEGRITY: token registry undefined exit code %s\n' "$_hook_rc" >&2
+      [ -n "$_hook_output" ] && printf '%s\n' "$_hook_output" >&2
+      exit 70
+      ;;
+  esac
+}
+trap _finalize_hook_output EXIT
+
+governance_hook_load_input
+governance_hook_require_commands grep python3 sed
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'token registry tool extraction failed'
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'token registry path extraction failed'
 
 case "$TOOL" in
   Edit|Write|MultiEdit) ;;
@@ -44,84 +110,173 @@ case "$FILE_PATH" in
   *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 // ""')
+NEW_CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.content // .tool_input.new_string // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'token registry content extraction failed'
+[ -z "$NEW_CONTENT" ] && exit 0
+# Per-line escape(2026-07-07 方向 2 升 P0 配套):行內含 `@token-registry-ok: <rationale>` 豁免該行
+governance_hook_grep_capture NEW_CONTENT_FILTERED 'token registry escape filter failed' \
+  "$NEW_CONTENT" -v '@token-registry-ok:'
+NEW_CONTENT="$NEW_CONTENT_FILTERED"
 [ -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
+# The registry is corpus-owned SSOT. The project resolver is still required to validate the active
+# provider project boundary; no hook-relative or opacity-only fallback may silently weaken policy.
+CORPUS_ROOT=$(governance_corpus_root 2>/dev/null) \
+  || governance_hook_integrity_fail 'token registry corpus root could not be resolved'
+PROJECT_ROOT=$(governance_project_root 2>/dev/null) \
+  || governance_hook_integrity_fail 'token registry project root could not be resolved'
+REGISTRY="$CORPUS_ROOT/packages/design-system/src/tokens/utility-registry.json"
+if [ -L "$REGISTRY" ] || [ ! -f "$REGISTRY" ] || [ ! -r "$REGISTRY" ]; then
+  governance_hook_integrity_fail "canonical utility registry is unavailable or unsafe:${REGISTRY}"
 fi
+# `_meta.owner` is the canonical identity of the source record, not its projected install path.
+# Keep the two path segments separate so the fork path projection rewrites REGISTRY above without
+# rewriting this identity assertion.
+CANONICAL_REGISTRY_OWNER='packages/design-system'"/src/tokens/utility-registry.json"
+# The registry carries both the token lists and the executable matcher inventory. The hook only
+# implements one bounded engine; it never repeats aliases in shell regexes. Adding a token to an
+# authenticated list therefore changes enforcement immediately, while schema/build closure rejects
+# a new list that was not deliberately wired to either block or warn behavior.
+SCAN_RESULT=$(python3 - "$REGISTRY" "$CANONICAL_REGISTRY_OWNER" 3<<<"$NEW_CONTENT" <<'PY'
+import json
+import os
+import re
+import sys
 
-# Aggregate violations across all categories
-VIOLATIONS=""
+registry_path = sys.argv[1]
+expected_owner = sys.argv[2]
+content = os.fdopen(3, encoding="utf-8").read()
+with open(registry_path, encoding="utf-8") as source:
+    registry = json.load(source)
 
-# 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
+if (
+    not isinstance(registry, dict)
+    or registry.get("schemaVersion") != 1
+    or registry.get("_meta", {}).get("owner") != expected_owner
+    or not isinstance(registry.get("_meta", {}).get("provider_view_policy"), str)
+    or registry.get("enforcement", {}).get("schemaVersion") != 1
+    or registry.get("enforcement", {}).get("engine") != "utility-registry-rules-v1"
+):
+    raise ValueError("registry identity is invalid")
 
-# 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
+expected_pointers = {
+    "block": {
+        "/typography/block/size_raw",
+        "/typography/block/weight_raw",
+        "/typography/block/tracking_raw",
+        "/radius/block/out_of_range",
+        "/radius/block/ambiguous_default",
+        "/radius/block/arbitrary_value",
+        "/opacity/block/numeric_tier",
+        "/elevation/block/tailwind_size",
+        "/shadcn_alias/block/color_alias",
+        "/primitive_color_as_utility/block/primitive_class",
+    },
+    "warn": {
+        "/spacing/warn/micro_gap",
+        "/sizing/warn/fraction",
+    },
+}
 
-# 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
+def pointer_value(pointer):
+    if not isinstance(pointer, str) or not pointer.startswith("/") or "~" in pointer:
+        raise ValueError("unsafe registry pointer")
+    value = registry
+    for segment in pointer[1:].split("/"):
+        if not segment or not isinstance(value, dict) or segment not in value:
+            raise ValueError("unresolved registry pointer")
+        value = value[segment]
+    return value
 
-# 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
+def token_list(pointer):
+    value = pointer_value(pointer)
+    if (
+        not isinstance(value, list)
+        or not value
+        or any(not isinstance(token, str) or not token or any(ord(char) < 32 or ord(char) == 127 for char in token) for token in value)
+        or len(set(value)) != len(value)
+    ):
+        raise ValueError("invalid registry token list")
+    return value
 
-# 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
+result = {"block": [], "warn": []}
+seen_ids = set()
+for level in ("block", "warn"):
+    rules = registry["enforcement"].get(level)
+    if not isinstance(rules, list) or not rules:
+        raise ValueError("missing enforcement rules")
+    actual_pointers = set()
+    for rule in rules:
+        if not isinstance(rule, dict):
+            raise ValueError("invalid enforcement rule")
+        identifier = rule.get("id")
+        label = rule.get("label")
+        if (
+            not isinstance(identifier, str)
+            or not re.fullmatch(r"[a-z][a-z0-9-]*", identifier)
+            or identifier in seen_ids
+            or not isinstance(label, str)
+            or not label
+            or any(ord(char) < 32 or ord(char) == 127 for char in label)
+        ):
+            raise ValueError("invalid enforcement rule identity")
+        seen_ids.add(identifier)
 
-# 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
+        if "tokenListPointer" in rule:
+            if set(rule) != {"id", "label", "tokenListPointer"}:
+                raise ValueError("open token-list enforcement rule")
+            pointer = rule["tokenListPointer"]
+            if pointer in actual_pointers:
+                raise ValueError("duplicate token-list enforcement rule")
+            actual_pointers.add(pointer)
+            tokens = token_list(pointer)
+            matcher = re.compile(
+                r"(?<![A-Za-z0-9_-])(?:" + "|".join(re.escape(token) for token in sorted(tokens, key=len, reverse=True)) + r")(?![A-Za-z0-9_-])"
+            )
+            hits = {match.group(0) for match in matcher.finditer(content)}
+        else:
+            allowed_keys = {"id", "label", "pattern", "excludeTokenListPointer"}
+            if set(rule) - allowed_keys or not {"id", "label", "pattern"}.issubset(rule):
+                raise ValueError("open pattern enforcement rule")
+            pattern = rule["pattern"]
+            if not isinstance(pattern, str) or not pattern:
+                raise ValueError("empty enforcement pattern")
+            matcher = re.compile(pattern)
+            excluded = set(token_list(rule["excludeTokenListPointer"])) if "excludeTokenListPointer" in rule else set()
+            hits = {match.group(0) for match in matcher.finditer(content) if match.group(0) not in excluded}
 
-# 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
+        if hits:
+            result[level].append({
+                "id": identifier,
+                "label": label,
+                "hits": sorted(hits),
+            })
+    if actual_pointers != expected_pointers[level]:
+        raise ValueError("registry token lists are outside exact behavioral closure")
 
-# 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' ' ')"
+print(json.dumps(result, ensure_ascii=False, separators=(",", ":")))
+PY
+) || governance_hook_integrity_fail "canonical utility registry scan failed:${REGISTRY}"
+if ! jq -e '
+  type == "object"
+  and (keys | sort) == ["block", "warn"]
+  and all(.block[], .warn[];
+    type == "object"
+    and (keys | sort) == ["hits", "id", "label"]
+    and (.id | type == "string" and length > 0)
+    and (.label | type == "string" and length > 0)
+    and (.hits | type == "array" and length > 0 and all(.[]; type == "string" and length > 0))
+  )
+' <<<"$SCAN_RESULT" >/dev/null 2>&1; then
+  governance_hook_integrity_fail 'canonical utility registry scan emitted an invalid result'
 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
+VIOLATIONS=$(jq -r '.block[] | "   [\(.label)] \(.hits | join(" "))"' <<<"$SCAN_RESULT" 2>/dev/null) \
+  || governance_hook_integrity_fail 'canonical utility block result could not be decoded'
+SOFT_NOTES=$(jq -r '.warn[] | "   [\(.label)] \(.hits | join(" "))"' <<<"$SCAN_RESULT" 2>/dev/null) \
+  || governance_hook_integrity_fail 'canonical utility warning result could not be decoded'
+[ -n "$VIOLATIONS" ] && VIOLATIONS=$'\n'"$VIOLATIONS"
+[ -n "$SOFT_NOTES" ] && SOFT_NOTES=$'\n'"$SOFT_NOTES"
 
 if [ -n "$VIOLATIONS" ]; then
   cat >&2 <<'EOF_HEAD'
@@ -138,12 +293,27 @@ EOF_HEAD
      leading-{N}   → leading-compact / leading-normal
      tracking-*    → tracking-shortcut(or codify role-specific semantic utility)
      rounded-xl..  → rounded-xs..rounded-lg / rounded-full
+     rounded-[..]  → rounded-xs..lg 語意 utility(rounded-[inherit] 唯一例外,registry allow)
      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 優先」。
+   Per-line escape:行尾註解 `@token-registry-ok: <rationale>`(audit 可追)。
 EOF_BODY
+  # P0 BLOCKER(2026-07-07 治理進化方向 2:對齊 user 2026-05-27「SSOT canonical 必 P0」doctrine;
+  # 檔級豁免(anatomy/principles stories / token 自家)+ 行級 escape 已備,升級不增誤殺)
+  # micro-gap/fraction soft note 附在硬 block 訊息尾(一起讓 AI 看到,但不影響 exit code 判定)
+  [ -n "$SOFT_NOTES" ] && { echo "" >&2; echo "   （另有 soft flag,非 block 原因）:" >&2; echo -e "$SOFT_NOTES" >&2; }
+  exit 2
+fi
+
+# 只有 micro-gap / fraction soft note(無硬 violation)→ WARN 非 block(registry rationale「flag for human review」)
+if [ -n "$SOFT_NOTES" ]; then
+  echo "" >&2
+  echo "⚠️  Dim 47 soft flag(registry micro_gap / fraction「flag for human review」— 非 block,#71 接線):" >&2
+  echo -e "$SOFT_NOTES" >&2
+  echo "   <4px gap / registry fraction width 常違反 item-anatomy slot 幾何 / layout SSOT → 人工 review。合理則行尾 @token-registry-ok: <rationale>。" >&2
 fi
 
 exit 0

package/ds-canonical/hooks/check_orphan_ds_css.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+# check_orphan_ds_css.sh — P0 BLOCKER
+#
+# 防 DS CSS file orphan(在 src 但不在 tokens.css aggregator + 沒被任何 tsx import)
+# (2026-05-27 user verbatim「之前不就已經整理過一次 token 了?還沒搞好?那到底還要搞幾次?
+# 你他媽最好給我保證這是最後一次」永久 codify)
+#
+# Anchor 錨點:
+# - 2026-05-26 sidebar-width token 從 globals.css 搬 uiSize.css(part 1 fix)
+# - 但 header-canonical.css / data-table.css 兩個 non-token-home CSS 沒一起 sweep
+# - 兩者都在 globals.css 為 DS internal 載入,但 tokens.css consumer aggregator 漏
+# - Consumer install DS + import @qijenchen/design-system/styles/tokens 拿不到
+#   → sidebar 收合 logo 跑版(--chrome-header-avatar-size missing)+ DataTable cell grid 跑掉
+# - User 抓「sidebar 修了一百次都白做,真 root 在 token bundle pipeline」
+#
+# Stop hook(post-assistant turn)scan packages/design-system/src/**/*.css:
+# Orphan condition:file NOT in tokens.css aggregator AND NOT imported by any tsx/ts in DS
+# → provider-neutral Stop block decision，由統一 runner 轉成各 provider native transport
+#
+# Defense layer 補 gen-figma-make-artifacts.mjs auto-scan(generator 自動抓,本 hook 額外驗)。
+
+HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd -P)" || {
+  printf 'GOVERNANCE_INTEGRITY: orphan-CSS hook directory is unavailable\n' >&2
+  exit 70
+}
+source "$HOOK_DIR/lib/_hook_integrity.sh" 2>/dev/null || {
+  printf 'GOVERNANCE_INTEGRITY: canonical hook integrity helper is unavailable\n' >&2
+  exit 70
+}
+source "$HOOK_DIR/_log-fire.sh" 2>/dev/null && log_hook_fire
+
+set -uo pipefail
+
+governance_hook_load_input
+governance_hook_require_commands find grep basename
+EVENT=$(printf '%s' "$INPUT" | jq -r '.hook_event_name // ""') \
+  || governance_hook_integrity_fail 'orphan-CSS event could not be decoded'
+
+case "${EVENT:-}" in
+  Stop|SubagentStop) ;;
+  *) exit 0 ;;
+esac
+
+DS_SRC="${GOVERNANCE_PROJECT_DIR:-.}/packages/design-system/src"
+AGGREGATOR="$DS_SRC/styles/tokens.css"
+
+if [ ! -d "$DS_SRC" ] || [ ! -f "$AGGREGATOR" ]; then
+  governance_hook_integrity_fail \
+    "orphan-CSS canonical DS root or aggregator is unavailable:$AGGREGATOR"
+fi
+
+CSS_FILES=$(find "$DS_SRC" -name '*.css' -type f -print 2>/dev/null)
+FIND_RC=$?
+[ "$FIND_RC" -eq 0 ] \
+  || governance_hook_integrity_fail "orphan-CSS scan failed(exit=$FIND_RC):$DS_SRC"
+
+ORPHANS=""
+while IFS= read -r css; do
+  [ -n "$css" ] || continue
+  rel="${css#$DS_SRC/}"
+  # Skip aggregator itself
+  if [ "$rel" = "styles/tokens.css" ]; then continue; fi
+  # In aggregator?
+  grep -qF "$rel" "$AGGREGATOR" 2>/dev/null
+  AGGREGATOR_RC=$?
+  case "$AGGREGATOR_RC" in
+    0) continue ;;
+    1) ;;
+    *) governance_hook_integrity_fail "orphan-CSS aggregator could not be scanned:$AGGREGATOR" ;;
+  esac
+  # Imported by any tsx/ts in DS?
+  basename=$(basename "$css")
+  IMPORT_MATCHES=$(grep -rln "import.*${basename}\|@import.*${basename}" "$DS_SRC" \
+    --include='*.tsx' --include='*.ts' --include='*.css' 2>/dev/null)
+  IMPORT_RC=$?
+  case "$IMPORT_RC" in
+    0)
+      if grep -vF "$css" <<<"$IMPORT_MATCHES" | grep . >/dev/null; then
+        continue
+      fi
+      ;;
+    1) ;;
+    *) governance_hook_integrity_fail "orphan-CSS imports could not be scanned:$DS_SRC" ;;
+  esac
+  ORPHANS="${ORPHANS}  - $rel\n"
+done <<< "$CSS_FILES"
+
+if [ -n "$ORPHANS" ]; then
+  REASON=$(printf '🚨 ORPHAN-DS-CSS BLOCKER(2026-05-27 user 永久糾正「之前不就已經整理過一次 token 了?最後一次」)\n\n  DS src 內 CSS 既不在 tokens.css aggregator 也不被任何 tsx/ts import:\n%b\n  Consumer install DS + import @qijenchen/design-system/styles/tokens 拿不到 → 跑版。\n  修法 2 選 1:\n    (a) 加進 tokens.css aggregator(若是 :root token / @theme 宣告):\n        node scripts/gen-figma-make-artifacts.mjs(自動掃 patterns/+components/)\n    (b) 在對應 tsx file 加 `import ./xxx.css`(若是 component-internal scoped style)' "$ORPHANS")
+  DECISION=$(jq -nc --arg reason "$REASON" '{governanceDecision:"block",reason:$reason}') \
+    || governance_hook_integrity_fail 'orphan-CSS governance decision could not be encoded'
+  printf '%s\n' "$DECISION"
+  exit 0
+fi
+
+exit 0

package/ds-canonical/hooks/check_overlay_open_focus_escape_probe.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+# check_overlay_open_focus_escape_probe.sh — P0 BLOCKER
+#
+# Codex M31 P0 finding 2026-05-27:Overlay canonical rules require open visual
+# states, but active hooks check overlay handcraft/static code only;沒 runtime
+# probe Tooltip/Popover/Dialog/Sheet/DropdownMenu/HoverCard 真 open / focus / Esc.
+#
+# Triggers on consumer apps/**/*.stories.tsx edit. For each story using overlay
+# primitive, verify story contains:
+#   - `defaultOpen` prop OR
+#   - controlled `open={...}` / bare `open` boolean attr(2026-07-16 dim 74 加廣)OR
+#   - `play()` interaction function clicking trigger OR
+#   - `// @overlay-open-skip: <rationale>` per-story escape
+# Otherwise story is「trigger-only」= visual snapshot 看不到 overlay content (per
+# Empty-content rendered in sweep,user 2026-05-27 抓「overlay 沒彈出」7-bug 錨點).
+#
+# Scope: consumer storybook + DS canonical anatomy/principles stories.
+
+source "$(dirname "$0")/_log-fire.sh" 2>/dev/null && log_hook_fire
+source "$(dirname "$0")/lib/_hook_integrity.sh" 2>/dev/null || {
+  printf 'GOVERNANCE_INTEGRITY: hook integrity helper unavailable\n' >&2
+  exit 70
+}
+
+set -uo pipefail
+
+governance_hook_load_input
+governance_hook_require_commands grep sed sort
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'overlay-open tool extraction failed'
+
+case "${TOOL:-}" in
+  Edit|Write|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+FILE=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'overlay-open path extraction failed'
+if ! governance_hook_grep_q 'overlay-open scope matcher failed' "$FILE" -qE '\.stories\.tsx$'; then exit 0; fi
+
+CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // ""' 2>/dev/null) \
+  || governance_hook_integrity_fail 'overlay-open content extraction failed'
+[ -z "$CONTENT" ] && exit 0
+
+# File-level escape
+if governance_hook_grep_q 'overlay-open skip matcher failed' "$CONTENT" -q '@overlay-open-skip:'; then exit 0; fi
+# HoverCard documented exception (per codex 2026-05-27)
+if governance_hook_grep_q 'overlay-open trait escape matcher failed' "$CONTENT" -q '@story-trait-allow:.*missing-opensnapshot'; then exit 0; fi
+
+# Detect overlay primitive usage
+OVERLAY_PRIMITIVES='Tooltip|Popover|Dialog|Sheet|DropdownMenu|HoverCard'
+governance_hook_grep_capture USED_UNSORTED 'overlay-open primitive matcher failed' \
+  "$CONTENT" -oE "<(DS\.)?($OVERLAY_PRIMITIVES)Trigger\b"
+USED=$(sort -u <<< "$USED_UNSORTED" 2>/dev/null) \
+  || governance_hook_integrity_fail 'overlay-open primitive sorter failed'
+
+if [ -z "$USED" ]; then exit 0; fi
+
+# Detect open-state mechanism
+# 2026-07-16 dim 74 regex 加廣:原只認 open={true|isOpen|isVisible} 3 個字面名 —
+# 漏 controlled `open={<任意變數/expression>}`(如 open={open} / open={!collapsed})與
+# bare `open` boolean attr(JSX `<Popover open>` = true)→ 合法 controlled story 被誤殺。
+#   - bare attr 兩形態:tag 內 `<Sheet open>` / `<Popover open onX>`(`<Tag[^<>]* open` 限同 tag,
+#     `[^<>]*` 不可跨 `>` → JSX 內文 / 註解 prose 的「open / close」不誤中)+ 多行 prop 排版
+#     「整行只有 open」(`^\s*open\s*$`)。存量驗證:Coachmark principles(行只有 open)pass、
+#     dropdown-menu.anatomy prose「浮層 open / close」不誤 pass。
+#   - defaultOpen 原本就有,保留
+# 2026-07-18 修 bde8973c 過廣 bug:原 `open=\{[!a-zA-Z_]` 把 false/null/undefined 的首字 f/n/u
+#   誤中 → `open={false}`(假 open,控制成關閉)被當成「有 open 機制」→ 漏擋 trigger-only story
+#   (test P3 失敗 → ci.yml Hook test suite 紅 → 下游 gate 全跳過)。修:controlled open={<expr>}
+#   單獨抽出偵測,排除三個「關閉字面值」open={false|null|undefined}(空白容忍);identifier/negation
+#   /true 仍認(如 open={showMenu} / open={!collapsed} / open={true})。
+HAS_OPEN=""
+if governance_hook_grep_q 'overlay-open mechanism matcher failed' "$CONTENT" -qE \
+  'defaultOpen|<[A-Za-z][^<>]*[[:space:]]open([[:space:]>]|$)|^[[:space:]]*open[[:space:]]*$|play:\s*async|play\(.*click'; then
+  HAS_OPEN="found"
+fi
+# controlled open={<expr>}:認任意 identifier / negation / true,但排除關閉字面值 false|null|undefined
+if [ -z "$HAS_OPEN" ]; then
+  governance_hook_grep_capture CONTROLLED_CANDIDATES 'overlay-open controlled-state matcher failed' \
+    "$CONTENT" -oE 'open=\{[^}]*\}'
+  governance_hook_grep_capture CONTROLLED_OPEN 'overlay-open closed-state filter failed' \
+    "$CONTROLLED_CANDIDATES" -vE '^open=\{[[:space:]]*(false|null|undefined)[[:space:]]*\}$'
+  if [ -n "$CONTROLLED_OPEN" ]; then
+    HAS_OPEN="found"
+  fi
+fi
+
+if [ -z "$HAS_OPEN" ]; then
+  cat >&2 << EOF
+🚨 OVERLAY-OPEN-PROBE BLOCKER(P0,codex M31 finding 2026-05-27 + user 7-bug 錨點)
+
+  Story $FILE uses overlay primitive trigger but no open-state mechanism:
+$(echo "$USED" | sed 's/^/    /')
+
+  Without defaultOpen / open={true} / play() click, visual snapshot 永遠 看不到
+  overlay content。User 2026-05-27 verbatim「圖四,首先會彈出 overlay 的,感覺都沒
+  正常彈出」.
+
+  修法 2 選 1:
+    (a) 加 \`defaultOpen\` prop OR controlled \`open={true}\` OR Storybook \`play\` interaction
+        click trigger before screenshot
+    (b) Escape per-file:\`// @overlay-open-skip: <rationale>\`(eg. behavior-only
+        test) OR \`// @story-trait-allow: missing-opensnapshot\`(per codex
+        canonical exception list)
+EOF
+  exit 2
+fi
+
+exit 0