@qijenchen/design-system 0.1.0-beta.52 → 0.1.0-beta.53

package/ds-canonical/hooks/check_layout_space_magic_numbers.sh

@@ -49,10 +49,22 @@ if [ -z "$MAGIC_LINES" ]; then
   exit 0
 fi
 
-# Filter out lines with escape marker on same line OR preceding line
+# Filter out lines with escape marker on same line OR immediately preceding line
+# 2026-06-03 修(doc-vs-code bug,M32):L41 文件宣稱支援「preceding line OR same line」,
+# 但原 code 只檢查同行 → JSX className 行無法放同行 `//` comment(會破壞 JSX)→ escape 對 JSX
+# 實質失效。補實作前一行檢查(grep -n 行號 → sed 取前一行),對齊文件 + 解 JSX 必需。
 UNJUSTIFIED=""
 while IFS= read -r line; do
+  # same-line marker
   if echo "$line" | grep -qF "$ESCAPE_MARKER"; then continue; fi
+  # preceding-line marker(JSX `{/* @layout-space-magic-ok: ... */}` 在上一行)。
+  # 對齊 ESLint disable-next-line 慣例:前一行 marker 僅在該行是「註解專用行」(trimmed 開頭
+  # //、{/*、/*、*)時生效 — 否則上一行 code 的「同行 escape」會誤串到下一行(P8 conflict)。
+  lineno="${line%%:*}"
+  if [ "$lineno" -gt 1 ] 2>/dev/null; then
+    prev=$(echo "$NEW_CONTENT" | sed -n "$((lineno-1))p")
+    if echo "$prev" | grep -qF "$ESCAPE_MARKER" && echo "$prev" | grep -qE '^[[:space:]]*(//|\{?/\*|\*)'; then continue; fi
+  fi
   UNJUSTIFIED="${UNJUSTIFIED}${line}\n"
 done <<< "$MAGIC_LINES"
 

package/ds-canonical/hooks/check_story_invariants.sh

@@ -517,13 +517,17 @@ rule_story_baseline_reference() {
     fi
 
     # 偵測明顯 simplified mock anti-pattern
-    if echo "$CONTENT" | grep -qE '<SidebarHeader>[[:space:]]*<span'; then
+    # 2026-06-03 修(同 R8 bug class):tr 換行→空格 flatten(grep 逐行無法跨行)+ tag anchor 加 [^>]*> 容忍屬性
+    # (真實 JSX 是 <ChromeHeader className=...> 多行,原 <ChromeHeader> 死匹配漏)。
+    local CONTENT_FLAT7
+    CONTENT_FLAT7=$(echo "$CONTENT" | tr '\n' ' ')
+    if echo "$CONTENT_FLAT7" | grep -qE '<SidebarHeader[^>]*>[[:space:]]*<span'; then
       echo "❌ R7 anti-pattern:<SidebarHeader><span> — 應 wrap WorkspaceBrand-like ItemAvatar block(per sidebar.stories IconCollapse baseline)" >&2
     fi
-    if echo "$CONTENT" | grep -qE '<SidebarMenuButton>[^<]*<[A-Z][a-zA-Z]+ className="size-'; then
+    if echo "$CONTENT_FLAT7" | grep -qE '<SidebarMenuButton[^>]*>[^<]*<[A-Z][a-zA-Z]+[[:space:]]+className="size-'; then
       echo "❌ R7 anti-pattern:<SidebarMenuButton><Icon className=\"size-N\"> — 應用 startIcon prop + tooltip prop(per sidebar.stories MAIN_NAV map)" >&2
     fi
-    if echo "$CONTENT" | grep -qE '<ChromeHeader>[^<]*<span className="[^"]*flex-1'; then
+    if echo "$CONTENT_FLAT7" | grep -qE '<ChromeHeader[^>]*>.{0,160}<span[[:space:]]+className="[^"]*flex-1'; then
       echo "❌ R7 anti-pattern:<ChromeHeader><span flex-1> — 應 SidebarTrigger + h1 緊鄰 gap-2(per sidebar.stories PageContent baseline)" >&2
     fi
   fi
@@ -562,10 +566,15 @@ rule_story_archetype_registry() {
     CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // ""')
   fi
 
-  # Allow override
+  # Allow override — 2026-06-03 修(同 fragment-vs-file bug class,對抗稽核抓到):Edit 只送 new_string
+  # 片段,@story-baseline-allow marker 在檔頭(不在每次 edit 片段)→ 編輯有 marker 的 story 任一非
+  # marker 行就被 R8 誤擋。補查整檔 disk head(對齊 R7 L499 disk-check 做法)。
   if echo "$CONTENT" | head -10 | grep -qE '@story-baseline-allow:'; then
     return 0
   fi
+  if [ -f "$FILE_PATH" ] && head -10 "$FILE_PATH" 2>/dev/null | grep -qE '@story-baseline-allow:'; then
+    return 0
+  fi
 
   # Read antiPatterns regex from registry(per component)
   # Iterate Sidebar/DataTable/ChromeHeader components
@@ -581,9 +590,14 @@ rule_story_archetype_registry() {
     PATTERNS=$(jq -r --arg c "$COMP" '.components[$c].antiPatterns[]? | select(.severity == "block") | .regex' "$REGISTRY" 2>/dev/null)
     [ -z "$PATTERNS" ] && continue
 
+    # 2026-06-03 修:CONTENT 換行 → 空格再 grep。真實 JSX 是多行(<ChromeHeader> 與 <span> 分行),
+    # 而 grep -E 是 line-oriented + registry regex 用 [[:space:]] 可攜語法 → 不正規化的話多行 antiPattern
+    # 靜默漏 = 假 P0(對抗稽核抓到)。tr 後整段成單行,[[:space:]]* / .* 才能跨原換行匹配。
+    local CONTENT_FLAT
+    CONTENT_FLAT=$(echo "$CONTENT" | tr '\n' ' ')
     while IFS= read -r PATTERN; do
       [ -z "$PATTERN" ] && continue
-      if echo "$CONTENT" | grep -qE "$PATTERN"; then
+      if echo "$CONTENT_FLAT" | grep -qE "$PATTERN"; then
         echo "⚠️  R8 story_archetype_registry violation:" >&2
         echo "   $FILE_PATH wrap <$COMP> matches anti-pattern:" >&2
         echo "   regex: $PATTERN" >&2
@@ -598,6 +612,48 @@ rule_story_archetype_registry() {
   done
 }
 
+# ─────────────────────────────────────────────────────────────────────────────
+# R9 — hand-craft overlay / chrome header(2026-06-04 codify per upload-manager 面板 drift)
+# Story 內手刻 `<div ... px-[var(--layout-space-loose)] ... border-b border-divider ...>`
+# = 浮層 / chrome header signature → 必消費 SurfaceHeader / PopoverHeader / DialogHeader primitive。
+# 零誤判簽名(DS-wide 量測:px-loose + border-b border-divider 同 div 僅手刻 overlay header 用 —
+# doc-table row 用 px-4 硬寫;真 overlay header 寫 `<SurfaceHeader>`,className 不外露)。
+# Anchor:upload-manager 面板原手刻 `<div px-loose py-2 border-b border-divider>`(py-2≠py-tight /
+# 殼 rounded-md≠lg / border-divider≠border / bg-surface≠raised),既有 3 道網全漏:
+#   R1-C(要 div 有 absolute + 附近 onClose/dismiss)、_chrome_header_handcraft(skip stories +
+#   只比 h-[chrome-header-height] signature)、R7/R8(只比已註冊 primitive 名)。adversarial workflow 確認。
+# ─────────────────────────────────────────────────────────────────────────────
+rule_handcraft_overlay_header() {
+  # skip primitive / overlay 家(它們定義 / 示範 header primitive 本身)。
+  # 含全部 isOverlay 元件家(2026-06-04 adversarial workflow R9-SKIP-001:補 HoverCard/Tooltip/DropdownMenu/FileViewer)。
+  case "$FILE_PATH" in
+    */overlay-surface/*|*/header-canonical/*|*/ChromeHeader/*|*/Dialog/*|*/Sheet/*|*/Popover/*|*/Coachmark/*|*/Tabs/*|*/HoverCard/*|*/Tooltip/*|*/DropdownMenu/*|*/FileViewer/*) return 0 ;;
+  esac
+  # allow escape(檔頭 OR 本次片段)
+  if echo "$NEW_CONTENT" | head -10 | grep -qE '@story-baseline-allow:'; then return 0; fi
+  if [ -f "$FILE_PATH" ] && head -10 "$FILE_PATH" 2>/dev/null | grep -qE '@story-baseline-allow:'; then return 0; fi
+  local FLAT
+  # 2026-06-04 adversarial workflow 抓 R9 regex 3 漏洞,robustify:
+  #   (1) drop 純註解行(^//、^*、^/*、^{/*)再 flatten → 避免 commented-out / 描述用 JSX 含 pattern 誤判(FP-002);
+  #       不 strip 行內 // (避免 mutilate https:// URL 造成 FN)。
+  #   (2) token 間用 [^">]*(非 [^>]*)→ px-loose 與 border-b 必在「同一 className 字串」內,不跨 " 屬性邊界
+  #       (FP-001:data-style="border-b border-divider" 不再誤判)。
+  #   (3) border-b[[:space:]]+border-divider(非單空格)→ 多行 className flatten 後多空格不漏(FN-001,同 R8 multiline bug class)。
+  FLAT=$(echo "$NEW_CONTENT" | grep -vE '^[[:space:]]*(//|\*|/\*|\{/\*)' | tr '\n' ' ')
+  if echo "$FLAT" | grep -qE '<div[^>]*px-\[var\(--layout-space-loose\)\][^">]*border-b[[:space:]]+border-divider|<div[^>]*border-b[[:space:]]+border-divider[^">]*px-\[var\(--layout-space-loose\)\]'; then
+    {
+      echo "❌ R9 hand-craft overlay / chrome header:${FILE_PATH}"
+      echo "   偵測到 <div ... px-[var(--layout-space-loose)] ... border-b border-divider> = 手刻浮層 / chrome header。"
+      echo "   必消費 <SurfaceHeader>(patterns/overlay-surface)/ <PopoverHeader> / <DialogHeader>;"
+      echo "   面板殼用 Popover 同款 chrome token(rounded-lg border-border bg-surface-raised elevation-200)。"
+      echo "   理由:px-loose + divider border 的 header chrome 是 overlay-surface SSOT(px-loose py-tight + border-b);手刻 = drift。"
+      echo "   Anchor:2026-06-04 upload-manager 面板手刻 header(py-2≠py-tight / 殼 token 全偏),user 抓。"
+      echo "   豁免:檔頭加 // @story-baseline-allow: <reason>。"
+    } >&2
+    record_worst 2
+  fi
+}
+
 # ─── Run rules ───
 rule_anatomy
 rule_slot_split
@@ -607,5 +663,6 @@ rule_name_jargon
 rule_description_jargon
 rule_story_baseline_reference
 rule_story_archetype_registry
+rule_handcraft_overlay_header
 
 exit $WORST

package/ds-canonical/hooks/lib/_chrome_header_handcraft.sh

@@ -55,7 +55,10 @@ if echo "$NEW_CONTENT" | grep -qE '@chrome-header-handcraft-allow:'; then
 fi
 
 # Detect handcraft signature: h-[var(--chrome-header-height)] paired with border-b border-divider
-HANDCRAFT_HIT=$(echo "$NEW_CONTENT" | grep -cE 'h-\[var\(--chrome-header-height\)\][^"]*border-b[^"]*border-divider' || true)
+# 2026-06-03 修(同 R8 multiline bug class,對抗稽核抓到):tr 換行→空格 flatten。真實 JSX className
+# 跨行(h-[...] 與 border-b 分行)+ [^"]* 跨屬性匹配 → 不 flatten 的話多行靜默漏(現 warn-only,但
+# Phase 3 升 P0 後會 false-negative)。tr 後整段成單行,[^"]* 才能跨原換行匹配。
+HANDCRAFT_HIT=$(echo "$NEW_CONTENT" | tr '\n' ' ' | grep -cE 'h-\[var\(--chrome-header-height\)\][^"]*border-b[^"]*border-divider' || true)
 
 if [ "$HANDCRAFT_HIT" -gt "0" ]; then
   printf '⚠️ CHROME HEADER HANDCRAFT(soft P1,Phase 3 將升 P0):\n' >&2

package/ds-canonical/hooks/tests/test_check_chrome_header_handcraft.sh

@@ -101,6 +101,17 @@ export const Bar = () => (
 '
 expect_warn "5. handcraft signature → warn" "CHROME HEADER HANDCRAFT"
 
+# 5b. 2026-06-03 回歸防護(同 R8 multiline bug class,對抗稽核抓到):h-[chrome-header-height] 與
+#     border-divider 跨多行 className(真實 JSX 格式)→ warn。修前 grep 逐行 + [^"]* 跨屬性 → 多行靜默漏。
+run_hook_write "/repo/packages/design-system/src/components/Baz/baz.tsx" '
+export const Baz = () => (
+  <div className="h-[var(--chrome-header-height)]
+    flex items-center px-loose
+    border-b border-divider" />
+)
+'
+expect_warn "5b. handcraft 多行 className → warn(回歸防護)" "CHROME HEADER HANDCRAFT"
+
 # 6. Escape allowlist → silent
 run_hook_write "/repo/packages/design-system/src/components/Bar/bar.tsx" '// @chrome-header-handcraft-allow: tabs cva pattern
 export const Bar = () => (

package/ds-canonical/hooks/tests/test_check_consumer_ds_primitive_misuse.sh

@@ -138,6 +138,16 @@ expect_block "8. P1 <CircularProgress size={24}> → BLOCK"
 run_hook "$PROD_TSX" 'export const L = () => <DS.CircularProgress size="lg" />'
 expect_silent "9. P1 nearmiss <CircularProgress size=\"lg\"> → silent"
 
+# 9b. 2026-06-03 回歸防護(同 R8 bug class):屬性跨多行的真實 JSX → BLOCK。修前 grep 逐行 +
+#     [^>]+ 跨屬性匹配 → 多行 component 靜默繞過全部 anti-pattern(= BLOCKER false-negative,對抗稽核抓到)。
+run_hook "$PROD_TSX" 'export const L = () => (
+  <DS.CircularProgress
+    variant="blue"
+    size={48}
+  />
+)'
+expect_block "9b. P1 多行屬性 <CircularProgress size={48}> → BLOCK(回歸防護)"
+
 # ── P2 RadioGroupItem(broad-vs-narrow symmetry)───────────────────────────────
 
 # 10. POSITIVE:RadioGroupItem 裸用,無 SelectionItem 無 label → BLOCK

package/ds-canonical/hooks/tests/test_check_consumer_no_ds_catalog.sh

@@ -191,6 +191,16 @@ expect_pass_silent "17. legit business composition demo → silent"
 run_hook "Edit" "$CONSUMER_FILE" ""
 expect_pass_silent "18. empty content → silent"
 
+# 19. 2026-06-03 回歸防護(fragment-vs-file bug class):Edit 只送 new_string 片段,
+#     但 @consumer-catalog-allow marker 在檔頭(不在每次 edit 片段)→ 修前編輯有 marker 的 portal
+#     檔任一非 marker 行就被誤擋(AllDsComponents basename = catalog pattern)。本 hook 是 PostToolUse
+#     (檔已落 disk)→ 補查整檔 marker。建真實 disk 檔(含 marker)+ Edit 無 marker 片段 → 必 silent。
+DISK_PORTAL="$TMP_DIR/apps/template/src/AllDsComponents.stories.tsx"
+mkdir -p "$(dirname "$DISK_PORTAL")"
+printf '%s\n' "// @consumer-catalog-allow: documented proxy portal" "export const ImportSmoke = () => <div/>;" > "$DISK_PORTAL"
+run_hook "Edit" "$DISK_PORTAL" "  <p>some unrelated edited line without the marker</p>"
+expect_pass_silent "19. Edit 片段無 marker + 檔頭 disk marker → silent(回歸防護)"
+
 echo ""
 echo "=== Summary ==="
 echo "Passed: $PASS / $((PASS + FAIL))"

package/ds-canonical/hooks/tests/test_check_field_family_invariants.sh

@@ -56,6 +56,15 @@ function F() { return <span variant="naked" className="inline-flex items-center"
 '
 expect_exit "A.1.2 naked + no SSOT → BLOCK" 2 "naked row-mode propagation"
 
+# 2b. 2026-06-03 回歸防護(同 R8 bug class):naked + items-center 跨多行 className(真實 JSX 格式)
+#     + no SSOT → BLOCK。修前 grep 逐行 → 多行 className 靜默漏 = P0 false-negative(對抗稽核抓到)。
+run_hook "/r/packages/design-system/src/components/BadMulti/bad-multi.tsx" '
+function F() { return <span variant="naked" className="inline-flex
+  bg-white
+  items-center" /> }
+'
+expect_exit "A.1.2b naked + 多行 className → BLOCK(回歸防護)" 2 "naked row-mode propagation"
+
 # 3. allowlist → pass
 run_hook "/r/packages/design-system/src/components/Edge/edge.tsx" '
 // @naked-row-mode-allow: popover content

package/ds-canonical/hooks/tests/test_check_layout_space_magic_numbers.sh

@@ -7,7 +7,8 @@
 #   - BLOCKER(exit 2):content 任一行命中 Tailwind spacing magic-number regex
 #       \b(p|px|py|pt|pb|pl|pr|gap|space-x|space-y|m|mx|my|mt|mb|ml|mr)-(0\.5|[1-9][0-9]?(\.[0-9])?)\b
 #     且該行 **無** escape marker `@layout-space-magic-ok:`
-#   - Escape:同行加 `// @layout-space-magic-ok: <rationale>` → 該行被濾掉
+#   - Escape:同行 OR 前一行加 `// @layout-space-magic-ok: <rationale>` → 該行被濾掉
+#     (前一行支援 2026-06-03 補實作 — JSX className 行無法放同行 //,必靠前一行 {/* */})
 #   - 非 Edit/Write/MultiEdit tool / 非 .tsx,.ts / DS src / 空 content → silent exit 0
 #
 # M34 broad-vs-narrow symmetry:
@@ -157,6 +158,15 @@ run_hook "Write" "$APP_TSX" "content" \
   'const Stack = () => <div className="gap-1">x</div>; // @layout-space-magic-ok: 4px icon stack, non-consumer-layout'
 expect_silent "N4. magic line with @layout-space-magic-ok escape → silent"
 
+# N4b. 2026-06-03 回歸防護:escape marker 在「前一行」→ silent。JSX className 行無法放同行 //,
+#      原 code 只查同行(doc 卻宣稱支援前一行)→ JSX escape 實質失效;修後前一行 marker 必被認。
+run_hook "Write" "$APP_TSX" "content" \
+  'const C = () => (
+  {/* @layout-space-magic-ok: dev artifact wrapper, non-consumer-layout */}
+  <div className="p-4">x</div>
+);'
+expect_silent "N4b. magic line with escape on PRECEDING line → silent(回歸防護)"
+
 # N5. DS source file is excluded from scope → silent (even WITH magic number)
 run_hook "Write" "$DS_TSX" "content" \
   'const Btn = () => <button className="px-4 py-2 gap-2">click</button>;'

package/ds-canonical/hooks/tests/test_check_story_invariants.sh

@@ -14,7 +14,7 @@
 #      block-severity antiPattern → P0 record_worst 2,2026-06-02 升 P0)
 #
 # Test 重點:silent skip / 各 rule fire / allowlist marker escape。
-# 不測 R3(需 spec.md frontmatter);R8 P0 block-severity 已測(#11,2026-06-02)。
+# 不測 R3(需 spec.md frontmatter);R8 P0 block-severity 已測(#11 單行 / #12-14 多行回歸防護,2026-06-03)。
 
 set -u
 
@@ -215,6 +215,136 @@ export const Default = () => (
 '
 expect_block "11. R8 simplified-mock <SidebarHeader><span> → P0 BLOCK" "R8 story_archetype_registry"
 
+# 12. R8 MULTI-LINE Sidebar drift(2026-06-03 回歸防護;修前 grep -E line-oriented + \s 當字面 's' → 多行靜默漏 = 假 P0):
+#     <SidebarHeader> 與 <span> 分行(真實 JSX 縮排格式)→ 修後(hook tr 換行→空格 + regex [[:space:]])應 BLOCK
+run_hook "PreToolUse" "Write" "$STORIES_R8" '
+// @story-baseline: @qijenchen/design-system/components/Sidebar/sidebar.stories.tsx#IconCollapse
+export const Default = () => (
+  <Sidebar>
+    <SidebarHeader>
+      <span>Acme</span>
+    </SidebarHeader>
+  </Sidebar>
+);
+'
+expect_block "12. R8 多行 <SidebarHeader> 換行 <span> → P0 BLOCK(回歸防護)" "R8 story_archetype_registry"
+
+# 13. R8 MULTI-LINE ChromeHeader drift:<ChromeHeader> 與 <span flex-1> 分行 → 修後應 BLOCK
+#     (修前 [\s\S]*? 在 BSD grep -E 是字元類非「任意字元」+ line-oriented → 雙重漏)
+STORIES_CH="/foo/my-project/packages/design-system/src/components/AppShell/app-shell-ch.stories.tsx"
+run_hook "PreToolUse" "Write" "$STORIES_CH" '
+// @story-baseline: @qijenchen/design-system/components/Sidebar/sidebar.stories.tsx#IconCollapse
+export const Default = () => (
+  <ChromeHeader>
+    <SidebarTrigger />
+    <span className="flex-1 text-body-lg">儀表板</span>
+  </ChromeHeader>
+);
+'
+expect_block "13. R8 多行 <ChromeHeader> 換行 <span flex-1> → P0 BLOCK" "R8 story_archetype_registry"
+
+# 14. R8 false-positive 防護:正確多行 ChromeHeader(h1 緊鄰、無 flex-1 span)+ 另一 story 遠處(距 >160 字)
+#     有無關 flex-1 span → .{0,160} 長度界擋住跨 story 誤匹配(greedy .* boolean 等同 lazy,故必設界)→ NO block
+run_hook "PreToolUse" "Write" "$STORIES_CH" '
+// @story-baseline: @qijenchen/design-system/components/Sidebar/sidebar.stories.tsx#IconCollapse
+export const Correct = () => (
+  <ChromeHeader>
+    <SidebarTrigger />
+    <h1 className="text-body-lg font-medium">儀表板</h1>
+  </ChromeHeader>
+);
+export const Unrelated = () => (
+  <div className="grid grid-cols-3 gap-4 rounded-lg border border-border bg-surface p-6 mt-4">
+    <div className="text-body-sm text-muted">統計面板區塊內容說明文字</div>
+    <span className="flex-1">無關的彈性間距元素</span>
+  </div>
+);
+'
+expect_pass_silent "14. R8 正確多行 ChromeHeader + 遠處無關 flex-1(>160 字)→ 不誤判"
+
+# 15. R8 disk @story-baseline-allow 豁免(2026-06-03 回歸防護,fragment-vs-file bug class,對抗稽核抓到):
+#     檔頭有 @story-baseline-allow 的 disk 檔 + Edit 只送無 marker 片段(含 antiPattern)→ R8 不擋
+#     (補查整檔 disk head;修前只查片段 → 編輯有 marker 的 story 任一非 marker 行就被 R8 誤擋)。
+#     斷言 EXIT=0(R8 未 record_worst 2);R7 anti-pattern stderr 警告與否不影響此斷言。
+DISK_STORY_R8="$TMP_DIR/r8-disk-allow.stories.tsx"
+printf '%s\n' "// @story-baseline-allow: legacy migration RFC-123" "export const X = () => (<Sidebar><SidebarHeader><span>A</span></SidebarHeader></Sidebar>)" > "$DISK_STORY_R8"
+run_hook "PreToolUse" "Edit" "$DISK_STORY_R8" '  <SidebarHeader><span>Acme</span></SidebarHeader>'
+if [ "$EXIT" = "0" ]; then
+  echo "  PASS  15. R8 disk @story-baseline-allow + Edit 無 marker 片段 → R8 不擋(回歸防護)"; PASS=$((PASS+1))
+else
+  echo "  FAIL  15. R8 disk marker exempt (expected exit 0, got exit=$EXIT)"
+  echo "  --- stderr ---"; echo "$STDERR_TEXT" | sed 's/^/    /'; echo "  --- end ---"
+  FAIL=$((FAIL+1)); FAILED_TESTS="${FAILED_TESTS}\n  - 15. R8 disk marker"
+fi
+
+# 16. R9 hand-craft overlay/chrome header(2026-06-04 codify per upload-manager 面板 drift):
+#     story 內手刻 <div px-[var(--layout-space-loose)] ... border-b border-divider> → P0 BLOCK
+run_hook "PreToolUse" "Write" "$TMP_DIR/r9-handcraft.stories.tsx" '
+export const Panel = () => (
+  <div className="max-w-md rounded-lg border bg-surface shadow-[var(--elevation-200)]">
+    <div className="flex items-center justify-between px-[var(--layout-space-loose)] py-2 border-b border-divider">
+      <span className="text-body font-medium">正在上傳 3 個項目</span>
+    </div>
+  </div>
+);
+'
+expect_block "16. R9 手刻 <div px-loose border-b border-divider> overlay header → P0 BLOCK" "R9 hand-craft overlay"
+
+# 17. R9 false-positive 防護:正確消費 SurfaceHeader + PopoverTitle → 不擋(silent)
+run_hook "PreToolUse" "Write" "$TMP_DIR/r9-correct.stories.tsx" '
+export const Panel = () => (
+  <div className="max-w-md flex flex-col rounded-lg border-border bg-surface-raised shadow-[var(--elevation-200)]">
+    <SurfaceHeader className="justify-between [--chrome-slot-h:1.25rem]">
+      <div className="flex-1 min-w-0"><PopoverTitle>正在上傳 3 個項目</PopoverTitle></div>
+    </SurfaceHeader>
+  </div>
+);
+'
+expect_pass_silent "17. R9 正確消費 SurfaceHeader+PopoverTitle → 不誤判"
+
+# 18. R9 false-positive 防護:doc-table row 用 px-4(非 loose token)+ border-b → 不擋
+run_hook "PreToolUse" "Write" "$TMP_DIR/r9-doctable.stories.tsx" '
+export const Tbl = () => (<div className="px-4 py-2.5 border-b border-divider bg-neutral-hover">表頭列</div>);
+'
+expect_pass_silent "18. R9 doc-table px-4 + border-b(非 loose token)→ 不誤判"
+
+# 19. R9 escape:檔頭 @story-baseline-allow → 不擋
+run_hook "PreToolUse" "Write" "$TMP_DIR/r9-allow.stories.tsx" '// @story-baseline-allow: legacy panel demo
+export const P = () => (<div className="px-[var(--layout-space-loose)] py-2 border-b border-divider" />);
+'
+expect_pass_silent "19. R9 @story-baseline-allow 豁免 → 不擋"
+
+# 20. R9 FN-001 回歸(2026-06-04 adversarial workflow):多行 className flatten 後多空格 → 仍 BLOCK
+#     (修前單空格 regex 漏;改 border-b[[:space:]]+border-divider)
+run_hook "PreToolUse" "Write" "$TMP_DIR/r9-multispace.stories.tsx" 'export const P = () => (
+  <div
+    className="flex justify-between px-[var(--layout-space-loose)] py-2
+      border-b
+      border-divider"
+  >正在上傳</div>
+);
+'
+expect_block "20. R9 多行/多空格 className 手刻 header → BLOCK(FN-001 修)" "R9 hand-craft overlay"
+
+# 21. R9 FP-001 防護:border-b border-divider 在 data-* 屬性(非 className)→ 不擋
+#     (修前 [^>]* 跨屬性誤判;改 [^\">]* 限同 className 字串)
+run_hook "PreToolUse" "Write" "$TMP_DIR/r9-crossattr.stories.tsx" '
+export const P = () => (<div className="px-[var(--layout-space-loose)]" data-x="border-b border-divider">x</div>);
+'
+expect_pass_silent "21. R9 border-divider 在 data-* 屬性 → 不誤判(FP-001 修)"
+
+# 22. R9 FP-002 防護:純註解行含 pattern → 不擋(drop comment-only line 後 flatten)
+run_hook "PreToolUse" "Write" "$TMP_DIR/r9-comment.stories.tsx" '// 範例(禁): <div className="px-[var(--layout-space-loose)] border-b border-divider">
+export const P = () => (<SurfaceHeader>x</SurfaceHeader>);
+'
+expect_pass_silent "22. R9 純註解行含 pattern → 不誤判(FP-002 修)"
+
+# 23. R9 skip-list 補 isOverlay 家(FileViewer)→ 不擋(R9-SKIP-001)
+run_hook "PreToolUse" "Write" "/foo/my-project/packages/design-system/src/components/FileViewer/fv.stories.tsx" '
+export const P = () => (<div className="px-[var(--layout-space-loose)] border-b border-divider">x</div>);
+'
+expect_pass_silent "23. R9 skip FileViewer(isOverlay 家)→ 不檢查"
+
 echo ""
 echo "=== Summary ==="
 echo "Passed: $PASS / $((PASS + FAIL))"

package/ds-canonical/references/story-baseline-registry.json

@@ -16,13 +16,13 @@
       "antiPatterns": [
         {
           "id": "sidebar-header-simplified-span",
-          "regex": "<SidebarHeader>\\s*<span",
+          "regex": "<SidebarHeader[^>]*>[[:space:]]*<span",
           "severity": "block",
           "rationale": "SidebarHeader 必 wrap WorkspaceBrand-like ItemAvatar block(per sidebar.stories#IconCollapse baseline);simplified <span> mock = drift"
         },
         {
           "id": "sidebar-menu-button-inline-icon",
-          "regex": "<SidebarMenuButton>[^<]*<[A-Z][a-zA-Z]+\\s+className=\"size-",
+          "regex": "<SidebarMenuButton[^>]*>[^<]*<[A-Z][a-zA-Z]+[[:space:]]+className=\"size-",
           "severity": "block",
           "rationale": "SidebarMenuButton 必用 startIcon prop + tooltip prop;children inline icon = drift"
         }
@@ -69,7 +69,7 @@
       "antiPatterns": [
         {
           "id": "chromeheader-span-flex-1",
-          "regex": "<ChromeHeader>[\\s\\S]*?<span\\s+className=\"[^\"]*flex-1[^\"]*\">",
+          "regex": "<ChromeHeader[^>]*>.{0,160}<span[[:space:]]+className=\"[^\"]*flex-1[^\"]*\">",
           "severity": "block",
           "rationale": "ChromeHeader title 該用 <h1 className=\"text-body-lg font-medium\"> 緊鄰 SidebarTrigger,不該用 <span flex-1> 撐空間造成 toggle + title 巨大間距"
         }

package/ds-canonical/rules/meta-patterns.md

@@ -60,7 +60,7 @@
 | **M20** | **AI 自問 best-practice + 自動 self-improve**(不靠 user 提醒)。Stop hook `rule_infra_best_practice_score`(R5 in `stop_passive_logging.sh`,2026-05-13 folded from retired `stop_meta_self_audit.sh`)每 turn 跑 score → < 80 / regression ≥ 5 log to `score-history.jsonl`;next-turn UserPromptSubmit `inject_pending_self_audit.sh` 注入 BLOCKER prompt。**Threshold 數值 SSOT**:`session_start_governance_check.sh`(L19-22 + L173)+ CLAUDE.md `# 治理 canonical` 行數預算表;本 M-rule 不重述具體 cap,避免多 home 漂移(2026-05-22 prune codify per Rule-of-3 violation fix)。**+ Sub-rule M33 (folded 2026-05-22)**:Stop hook overfire → AI conservative-defer 反 pattern。同 stop hook fire ≥ 5 次 within session → AI 自動 hedge / 撤回 claim / 「下個 session」defer **可做工作**。真理由 vs 偽 prereq 區辨 — (a)真 prereq 缺(cross-frame test fixture 等)= 具體 deliverable need;(b)偽 prereq(「context budget」「省工」「下個 session」)= conditioned hedge,user 反覆催 = 真理由不存在。**Rule**:AI reply 含「下個 session」「context budget」「省工」keyword 且前 1 turn user 已拍板「全部做完」/「繼續」/「沒理由不做」→ BLOCKER。對齊 Atlassian「stop using vague defer」+ Linux kernel patch review。 | user 10 次問「best-practice 嗎」直到外部 benchmark 確認真 gap;2026-05-13 claim-verify-gap stop hook fire 12+ 次 → 我每 reply 自動 hedge → user 多次糾正「沒理由不做」 |
 | **M21** | **新元件 / 新 sub-component 抽象前必過 prop variant test**。當新元件名 = `<Existing>+suffix`(Time / Range / Color / Light / Dark / Filled / Outline / Compact / Rich)→ 強烈 signal 應為 prop variant on `<Existing>`。3-test 通過才能分(全失敗 → prop):(1) `<Existing>` 加 prop 無法達成同 DOM/behavior?(2) ≥3 家 world-class DS 用分離元件而非 prop(必 cite source)?(3) value 結構或 contract 真的不同(如 Range = [start, end])?Hook check_premature_abstraction(retired/未實作;mindset enforcement)。 | DateTimePicker 從 DatePicker 拆 → 撤回合併 `<DatePicker showTime>`(2026-05-02);DataTableFilterPanel 5-file → 撤回 sub-file pattern |
 | **M22** | **Benchmark claim 必附 inline source citation**(不可憑印象)。寫 spec / tsx 含「Ant / Material / Polaris / Atlassian / Carbon / shadcn / Radix」等 world-class DS claim,必同段附:(a) inline URL(domain 對應 DS 官網 / GitHub source);(b) GitHub source path + line ref `#L42`;(c) screenshot reference `snapshots/...`;(d) 顯式撤回 `@benchmark-unverified`。Hook `check_benchmark_citation.sh` 機械化警告(P1 soft)。每次 implement 前跑 WebFetch 取真 source,不憑印象解碼。 | claim「Ant showTime range = 2 calendars」憑印象,實證 source code `multiplePanel = false` = 1 calendar(2026-05-02 鬼話事件)|
-| **M23** | **DS 內既有 canonical 優先於外部 benchmark**。寫 visual decision(color / size / spacing / typography / state)/ prop name namespace 前必先 grep DS 既有 codified token / variant / pattern / prop;命中 → 必對齊;沒命中 → 才引 world-class + 同步補 canonical。**禁止**:外部 benchmark(M22 cite OK)直接覆蓋 DS 內已有 canonical。Mindset #2「優先消費既有」的 visual layer。判斷流程:(a) grep 該屬性 / prop 既有 token/variant/usage;(b) 命中 canonical?有 → 用,沒 → 走 M22 cite 然後 codify;(c) **prop name conflict 子規則**(former M27,2026-05-15 collapsed):外部 framework prop name(TanStack `size` / Radix `disabled` / dnd-kit attrs 等)跟 DS 既有 prop 同字不同義 → wrap-and-rename(DS-internal naming + pre-process map);(d) **nearest same-purpose canonical wins 子規則**(former M35,2026-05-22 folded):寫 stories / UI composition wrap 既有 primitive 前必先 grep + Read primitive 的「完整佈局」production canonical story(eg. `sidebar.stories.tsx#IconCollapse`)抄 archetype 結構 / helper / variant — 不准憑記憶寫 simplified mock。**Cite 存在 ≠ consume 落實**(codex 2026-05-20 verdict)。最相近同目的 canonical 用法 > 泛用 component spec / 寬鬆 pattern wording。Registry SSOT `.claude/references/story-baseline-registry.json` + hook `check_story_invariants.sh R8 story_archetype_registry`。 | 2026-05-03 chevron color:DS `text-foreground` (icon-only Button neutral-9 85%) vs 我憑「Ant 5 家 muted」覆蓋 → 自開新 tier 違反一致設計語言。2026-05-06 column width:DS 49+ 處 `size: 'sm'\|'md'\|'lg'` density vs TanStack `size: 280` px = 同 prop 不同義 → `meta.width` wrap。2026-05-20 AppShell-vs-Sidebar drift:simplified mock + jargon + wrong variant + 不消費 primitive props。Hook `check_data_table_size_num_to_meta_width.sh` + `check_story_invariants.sh R8` |
+| **M23** | **DS 內既有 canonical 優先於外部 benchmark**。寫 visual decision(color / size / spacing / typography / state)/ prop name namespace 前必先 grep DS 既有 codified token / variant / pattern / prop;命中 → 必對齊;沒命中 → 才引 world-class + 同步補 canonical。**禁止**:外部 benchmark(M22 cite OK)直接覆蓋 DS 內已有 canonical。Mindset #2「優先消費既有」的 visual layer。判斷流程:(a) grep 該屬性 / prop 既有 token/variant/usage;(b) 命中 canonical?有 → 用,沒 → 走 M22 cite 然後 codify;(c) **prop name conflict 子規則**(former M27,2026-05-15 collapsed):外部 framework prop name(TanStack `size` / Radix `disabled` / dnd-kit attrs 等)跟 DS 既有 prop 同字不同義 → wrap-and-rename(DS-internal naming + pre-process map);(d) **nearest same-purpose canonical wins 子規則**(former M35,2026-05-22 folded):寫 stories / UI composition wrap 既有 primitive 前必先 grep + Read primitive 的「完整佈局」production canonical story(eg. `sidebar.stories.tsx#IconCollapse`)抄 archetype 結構 / helper / variant — 不准憑記憶寫 simplified mock。**Cite 存在 ≠ consume 落實**(codex 2026-05-20 verdict)。最相近同目的 canonical 用法 > 泛用 component spec / 寬鬆 pattern wording。**手刻浮層 / chrome header 子規則(2026-06-04 加)**:做「像 popover / dialog 的浮層面板」前必先 grep + Read `patterns/overlay-surface`(SurfaceHeader/Body/Footer)+ `Popover`(chrome token + PopoverHeader/PopoverTitle)SSOT;**手刻 `<div px-loose border-b border-divider>` header 或 `<div rounded bg-surface shadow-elevation>` 殼 = drift**,必消費 primitive。Registry SSOT `.claude/references/story-baseline-registry.json` + hook `check_story_invariants.sh R8 story_archetype_registry` **+ R9 hand_craft_overlay_header(零誤判 px-loose+border-divider 簽名,BLOCKER)**。**forcing-function 教訓**:M1/M23(d) 是 mindset,但 mindset 沒有完整 hook 兜底 = 紙老虎(會憑印象手刻);新場景若既有 hook 無 antiPattern 覆蓋 → 補 hook rule 才算落地。 | 2026-05-03 chevron color:DS `text-foreground` (icon-only Button neutral-9 85%) vs 我憑「Ant 5 家 muted」覆蓋 → 自開新 tier 違反一致設計語言。2026-05-06 column width:DS 49+ 處 `size: 'sm'\|'md'\|'lg'` density vs TanStack `size: 280` px = 同 prop 不同義 → `meta.width` wrap。2026-05-20 AppShell-vs-Sidebar drift:simplified mock + jargon + wrong variant + 不消費 primitive props。**2026-06-04 upload-manager 面板手刻 header + 殼**(`py-2`≠`py-tight` / `rounded-md`≠`lg` / `border-divider`≠`border` / `bg-surface`≠`raised`),既有 3 道網全漏(R1-C 要 absolute+dismiss / `_chrome_header_handcraft` skip stories / R7-R8 只比已註冊 primitive 名)→ adversarial workflow 抓 + 加 R9 補洞。Hook `check_data_table_size_num_to_meta_width.sh` + `check_story_invariants.sh R8/R9` |
 | **M24** | **State 顯著性 precedence:disabled > muted > emphasis**。元件在 disabled state 時,內部所有文字載體(label / value / placeholder / icon)統一切 disabled token(`text-fg-disabled` neutral-6),**不**繼續 muted token(`text-fg-muted` neutral-7)。muted 是裝飾,disabled 是語意 state — state 勝 emphasis。同理:error / warning state 內 placeholder 應對應 state token。Hook `check_field_family_invariants.sh` A.4(原 check_disabled_placeholder_color folded,live P1 stderr)。 | 2026-05-04 5+ violation:`bareInputStyles` 永遠 muted / `select.tsx` 3 處 plain&tag empty 不分 mode / `textarea.tsx` 同;Input.tsx 唯一做對。User 5+ 次糾正才 codify |
 | **M25** | **Layered chain invariant 必整鏈 forward(viewport-aware overlay scroll 範例)**。Overlay surface(Popover / HoverCard / Dialog / Sheet)的 viewport-aware scroll 機制要求 root → SurfaceBody 之間**所有中間 wrapper 都 forward `flex flex-col h-full`**;任何中間 div 沒 forward → SurfaceBody flex-1 失效 → body 不 scroll。同類 chain pattern:density 透傳 / fieldCtx 鏈 / theme subtree(M3 portal 逃逸對偶)。Hook `check_pattern_invariants.sh` C.1(原 check_overlay_panel_scroll_chain folded,live P1 WARN)。 | 2026-05-04:Filter / Sort panel root `<div w-[640px]>` 無 flex-col → user 縮 viewport 時 body 不 scroll。NameCard 因自設 max-h flex-col 才繞過(無中間 wrapper) |
 | **M26** | **Behavior / visual canonical decision 前必跑 WebFetch + WebSearch 取 ≥ 3 source,不可憑印象 propose**。M22 升級版 — M22 管「寫 spec / tsx 含 claim 必附 cite」(實作後),M26 管「propose / 決策前必先 fetch」(實作前)。Pipeline:(1) WebFetch 3 家世界級 source(Atlassian / Material / Polaris / Ant / Carbon / Apple HIG / shadcn / Radix);(2) 全 403 → WebSearch fallback 用 snippet,**明示「search-only confidence」**;(3) WebFetch + WebSearch 都失敗 → STOP propose,告知 user「無法 verify,要看 screenshot/實機」。Hook `check_propose_without_benchmark.sh`(2026-05-26 backfill — 前期 doc claim 但 file missing;UserPromptSubmit 偵測 user prompt 含 propose / visual / behavior decision keyword + 近 20 turn WebFetch/WebSearch < 2 → soft inject 提醒)。 | 2026-05-05:user 反覆糾「為什麼每次都沒 webfetch 只憑印象」— Jira drag handle / cell display 兩題我憑印象 propose 多輪;升級成硬規範 |

package/ds-canonical/skills/deep-audit-cross-codex/SKILL.md

@@ -80,7 +80,7 @@ detect_mode() {
 
 **PURE-JUDGMENT dim 真跑證據強制(2026-05-30 generalize,user 問「包括所有 infra 稽核?」)**:judgment dim(無 deterministic script / write-time hook 兜底者,含 infra 62/66/68/72 fork-onboarding/runtime/API-surface)report 必逐 dim show「DS-wide N files scanned + file:line findings / 或『0 after 全掃』」真跑證據,**禁只 mention dim 號**。report-validator `check_audit_post_report_validator.sh` Validator G 機械強制(evidence marker 數 < judgment dim 數 = BLOCKER)。DETERMINISTIC(22)+ HOOK(42)dim 由 CI / write-time hook 兜底(含 22/26 infra dim),不在此 risk。
 
-### A.1b — Story-claim-vs-code adversarial verification(MANDATORY,NO-SAMPLE,per-component)
+### A.1b — Claim-vs-code + docblock + spec-internal adversarial verification(MANDATORY,NO-SAMPLE,per-component)
 
 **2026-05-30 anchor(user verbatim 質問「之前他媽都在偷懶?」)**:獨立 adversarial 再審抓到 **403 findings / 64 單元 / 0 全乾淨**,其中 **202 個 FALSE_CLAIM**(anatomy/a11y/principles/spec 系統性記載 code 根本沒有的行為:Calendar 宣稱方向鍵導覽 / Tooltip·HoverCard 宣稱 focus trap / Alert 記不存在的 `actions` prop / Select 宣稱「用原生 select」但桌機自建 cmdk / AspectRatio spec 說「無 wrapper」但 code wrap)。**根因**:前期 audit 把 story-content dim(12/24/25/30/43 等)當「散文層 looks-fine 掃」跑,**沒 adversarial 讀 .tsx(+ wrap 的 lib)逐句比對宣稱**。這是「偷懶」的具體 failure mode。
 
@@ -90,6 +90,10 @@ detect_mode() {
 0. **機械 gate 先跑(deterministic,2026-06-02 加)**:`npm run typecheck:stories`(deterministic 抓 stories 的 `{var}`-undefined / prop 型別錯 —— **這是 SizeMatrix `{size}` crash 的真防線**;主 tsc -b exclude stories 故必跑此)+ `node scripts/storybook-smoke-test.mjs --full`(runtime crash render 掃)。先過才進 adversarial read。Anchor:2026-06-02 Field SizeMatrix `{size}` JSX-undefined crash 隨 beta.44 ship。**注**:smoke 全覆蓋 coverage-gate(防靜默-skip 假綠燈)attempted 但 CI server 規模化降級(~60 story 後 timeout 撞 20-min budget)→ **defer**(需 robust-server / browser-recycle + 可靠測試環境);故 typecheck:stories 是目前 deterministic 主防線。
 1. **per-component(NO-SAMPLE,全 62 component + 全 pattern)** dispatch adversarial agent。
 2. 每 agent 必 **Read 元件 .tsx + 其 wrap 的 lib(Radix/cmdk/react-day-picker/sonner 等)source**,對該元件**所有** anatomy / a11y / principles / spec 宣稱**逐句**比對:鍵盤 map / ARIA role / focus 行為 / prop 存在性 / 視覺 token / 預設值 / native-vs-custom。
+   **+ 2026-06-04 補兩 lens(Dim 15 cross-doc 明文涵蓋但前期被「散文 skim」漏的同 class failure;非抽樣、非無覆蓋,是「有 dim 淺跑」)**:
+   - **(a) 元件 `.tsx` 自己的 docblock / inline 註解 vs 同檔 code**:A.1b 原設計把 `.tsx` 當「真相來源」去驗別人(story/spec),**從不反驗它自己的註解** → docblock claim 的 padding / typography mode / hover / 行為 vs code 真實值,逐行比。
+   - **(b) spec 段落間描述性一致(spec-internal cross-section)**:A.1b 原驗 claim-vs-code,**不驗 spec-段-vs-段** → 同一 spec 內 Mode 表 typography 標籤 / padding 值 / gap 值 / surface 行為,跨 section 不可打架。
+   - **Anchor**:2026-06-04 user 抓「deep-audit 多次沒發現」—— tsx docblock(`閱讀模式 1.5` / `hover:bg-neutral-hover`,自 2026-04-23 stale)+ spec Mode 表 typography stale,全是 Dim 15 該抓、卻被當散文掃漏。納入此強制 adversarial(Validator F per-component 覆蓋率閘一併保證),不再可 skim。
 3. **「自上次 audit 無 code 改動」≠ 可跳過** —— content 宣稱可在 code 沒變下就是假的(前期正是用此藉口跳過 = 違規)。
 4. output per-component:`{component, claimsVerified: N, falseClaims: [{fileLine, 宣稱, 真實 code 行為}]}`。
 5. findings 併入 A.2 triage(FALSE_CLAIM 對齊 doc-to-code = autonomous;substantive design-language tension = HOLD propose)。

package/ds-canonical/skills/design-system-audit/SKILL.md

@@ -75,7 +75,7 @@ Grouped by theme. Each runs as an independent subagent; many can parallelize.
 | # | Audit | What it catches |
 |---|-------|-----------------|
 | 14 | **命名一致性** | PascalCase folder / kebab-case file / hook naming / spec chapter 中文 / identifier 英文 / single-file 語言統一 |
-| 15 | **Cross-doc 一致性** | CLAUDE.md 自身 + cross-spec full dup(Rule-of-3)+ tsx docblock-spec drift + stale upgrade markers。詳 `audit-prompts.md` Dim 15 |
+| 15 | **Cross-doc 一致性** | CLAUDE.md 自身 + cross-spec full dup(Rule-of-3)+ tsx docblock-spec drift + stale upgrade markers + **(2026-06-04 加)docblock-vs-同檔-code + spec 段內描述性一致(Mode 表 / typography / padding / gap cross-section)**。詳 `audit-prompts.md` Dim 15。**Enforcement 升級**:本 dim 易被「散文 skim」淺跑漏(2026-06-04 anchor:tsx docblock `閱讀模式`/`hover-bg` 自 2026-04-23 stale 多次沒抓)→ 改由 `/deep-audit-cross-codex` A.1b **強制 adversarial per-component**(Validator F 覆蓋率閘),不再可 skim |
 
 ### Group F — Architecture compliance (P1 priority, session-learned)
 

package/ds-story-manifest.json

@@ -5,9 +5,9 @@
     "consumedBy": [
       ".claude/hooks/check_consumer_story_baseline.sh",
       "scripts/composition-fidelity-visual-diff.mjs",
-      "product-workspace apps/template/src/AllDsComponents.stories.tsx (DsCanonicalPortal)"
+      "product-workspace apps/template/src/AllDsComponents.stories.tsx (ImportSmoke portal → DS Storybook link)"
     ],
-    "generatedAt": "2026-06-03T00:56:52.022Z"
+    "generatedAt": "2026-06-04T02:30:20.840Z"
   },
   "components": {
     "accordion": {
@@ -770,7 +770,9 @@
           "design-system-components-fileitem-展示--compact",
           "design-system-components-fileitem-展示--hover-swap",
           "design-system-components-fileitem-展示--clickable",
-          "design-system-components-fileitem-展示--compact-mixed"
+          "design-system-components-fileitem-展示--compact-mixed",
+          "design-system-components-fileitem-展示--upload-manager-surface",
+          "design-system-components-fileitem-展示--upload-manager-compact-surface"
         ],
         "設計規格": [
           "design-system-components-fileitem-設計規格--overview",
@@ -797,7 +799,8 @@
           "design-system-components-fileupload-展示--resume-upload",
           "design-system-components-fileupload-展示--bulk-image-upload",
           "design-system-components-fileupload-展示--with-file-list",
-          "design-system-components-fileupload-展示--custom-children"
+          "design-system-components-fileupload-展示--custom-children",
+          "design-system-components-fileupload-展示--button-variant"
         ],
         "設計規格": [
           "design-system-components-fileupload-設計規格--overview",
@@ -1681,5 +1684,5 @@
     }
   },
   "totalComponents": 62,
-  "totalStories": 911
+  "totalStories": 914
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qijenchen/design-system",
-  "version": "0.1.0-beta.52",
+  "version": "0.1.0-beta.53",
   "private": false,
   "description": "World-class design system — components, patterns, tokens, hooks (single source of truth for team distribution).",
   "type": "module",

package/src/components/Empty/empty.tsx

@@ -27,10 +27,16 @@ export interface EmptyProps extends React.HTMLAttributes<HTMLDivElement> {
   description?: string
   /** 行動按鈕(可選) */
   action?: React.ReactNode
+  /**
+   * Disabled context(2026-06-03 加 — FileUpload disabled 等情境消費):title / description 轉
+   * `text-fg-disabled`(語意 disabled token,非 opacity)。icon glyph 也 → fg-disabled(icon 是文字一環);icon-circle bg 維持 muted。
+   * 預設 false,不影響既有 consumer。
+   */
+  disabled?: boolean
 }
 
 const Empty = React.forwardRef<HTMLDivElement, EmptyProps>(
-  ({ icon, title, description, action, className, ...props }, ref) => {
+  ({ icon, title, description, action, disabled = false, className, ...props }, ref) => {
     // 字體 tier:讀 RowSizeContext(menu 內自動對齊 menu items 的字體）
     // 沒有 context(standalone）→ fallback 'md' → text-body (14px)
     const rowSize = useRowSize('md')
@@ -45,7 +51,8 @@ const Empty = React.forwardRef<HTMLDivElement, EmptyProps>(
         iconElement = icon
       } else {
         const Icon = icon as LucideIcon
-        iconElement = <Avatar icon={Icon} size={48} color="neutral" />
+        // disabled:glyph → fg-disabled([&_svg]:!… 蓋過 Avatar 內聯 color;circle bg 維持 muted)。icon 是文字一環,隨 disabled 變淡。
+        iconElement = <Avatar icon={Icon} size={48} color="neutral" className={disabled ? '[&_svg]:!text-fg-disabled' : undefined} />
       }
     }
 
@@ -59,7 +66,7 @@ const Empty = React.forwardRef<HTMLDivElement, EmptyProps>(
           <div className="mb-4">{iconElement}</div>
         )}
         {title && (
-          <span className="text-body-lg font-medium text-foreground">
+          <span className={cn('text-body-lg font-medium', disabled ? 'text-fg-disabled' : 'text-foreground')}>
             {title}
           </span>
         )}
@@ -69,7 +76,7 @@ const Empty = React.forwardRef<HTMLDivElement, EmptyProps>(
               // 字體跟 RowSizeContext 對齊:sm/md = text-body (14px),lg = text-body-lg (16px)
               // 在 menu 內自動對齊 menu items;standalone 時 fallback text-body
               descFont,
-              (title || action) ? 'text-fg-secondary' : 'text-fg-muted',
+              disabled ? 'text-fg-disabled' : (title || action) ? 'text-fg-secondary' : 'text-fg-muted',
               // Empty title 永遠 body-lg(16)→ 用 reading-lg token(label tier 決定)
               title && 'mt-[var(--item-gap-label-desc-reading-lg)]',
             )}

package/src/components/FileItem/file-item.anatomy.stories.tsx

@@ -101,7 +101,7 @@ export const ColorMatrix: Story = {
         <H3>Status × 元素 色彩矩陣</H3>
         <Desc>
           FileItem 本身無色彩變體——text 走 item-anatomy row primitive 共用 token
-          (`--foreground` / `--fg-secondary`);background 依 mode 固定(rich = `--surface` + border / compact Type B = `--secondary` / compact Type A = transparent),**無 hover-bg**(見下方 Container background table)。
+          (`--foreground` / `--fg-secondary`);background 依 mode 固定(rich = `--surface` + border / compact 無 status = `--secondary` / compact 有 status = transparent),**無 hover-bg**(見下方 Container background table)。
           Status 才驅動色彩:progress bar 色(inProgress / success / error)+ status icon 色(check / X)+ description 色(error 時升階)。
         </Desc>
         <div className="overflow-x-auto mb-4">
@@ -162,7 +162,7 @@ export const ColorMatrix: Story = {
       <div>
         <H3>Container background(per mode,**無 hover-bg**)</H3>
         <Desc>
-          FileItem 設計準則(2026-04-23):**永不顯示 hover-bg**。三種型態皆已 permanent-anchored(rich = border card / compact Type B = bg-secondary / compact Type A = 底部 progress bar),再加 hover-bg 是 double-emphasis 視覺雜。affordance 只靠 `cursor-pointer`(onClick 時)+ hover-swap icon fade。詳 spec「Hover 行為 canonical」。
+          FileItem 設計準則(2026-04-23):**永不顯示 hover-bg**。三種型態皆已 permanent-anchored(rich = border card / compact 無 status = bg-secondary / compact 有 status = 底部 progress bar),再加 hover-bg 是 double-emphasis 視覺雜。affordance 只靠 `cursor-pointer`(onClick 時)+ hover-swap icon fade。詳 spec「Hover 行為 canonical」。
         </Desc>
         <div className="overflow-x-auto">
           <table className="text-caption border-collapse">
@@ -171,8 +171,8 @@ export const ColorMatrix: Story = {
             </thead>
             <tbody>
               <tr><Td mono>rich(all status)</Td><Td><span className="inline-flex items-center gap-1.5"><Swatch value="--surface" size="sm" /><span className="font-mono">--surface</span> + border</span></Td><Td>永遠是 card(border + rounded + bg-surface)</Td></tr>
-              <tr><Td mono>compact Type B(no status)</Td><Td><span className="inline-flex items-center gap-1.5"><Swatch value="--secondary" size="sm" /><span className="font-mono">--secondary</span>(= neutral-3)</span></Td><Td>靜態 pill,對齊 Badge low / ProgressBar track SSOT</Td></tr>
-              <tr><Td mono>compact Type A(with status)</Td><Td><span className="font-mono">transparent</span></Td><Td>底部 progress bar 作 permanent affordance(分隔線型)</Td></tr>
+              <tr><Td mono>compact 無 status</Td><Td><span className="inline-flex items-center gap-1.5"><Swatch value="--secondary" size="sm" /><span className="font-mono">--secondary</span>(= neutral-3)</span></Td><Td>靜態 pill,對齊 Badge low / ProgressBar track SSOT</Td></tr>
+              <tr><Td mono>compact 有 status</Td><Td><span className="font-mono">transparent</span></Td><Td>底部 progress bar 作 permanent affordance(分隔線型)</Td></tr>
               <tr><Td mono>hover(任意 mode)</Td><Td><span className="font-mono">無變化</span></Td><Td>permanent-anchored → 不加 hover-bg。cursor-pointer 作 affordance(onClick 時)</Td></tr>
               <tr><Td mono>error</Td><Td><span className="font-mono">容器不變</span></Td><Td>只升階 description / bar / icon,不染容器——避免整 row 轉紅蓋過其他 metadata</Td></tr>
             </tbody>