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

package/src/components/Badge/badge.principles.stories.tsx

@@ -0,0 +1,391 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Bell, Inbox, Archive, FileText, MessageSquare, Settings } from 'lucide-react'
+import { Badge } from './badge'
+import { Button } from '@/design-system/components/Button/button'
+
+const meta: Meta = {
+  title: 'Design System/Components/Badge/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+const Rule = ({
+  title, note, children,
+}: {
+  title: string; note?: string; children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-muted mb-5 max-w-[720px] leading-relaxed">{note}</p>}
+    {/* items-start 讓 direct children 保持自然寬度(避免 iconOnly Button 等在 flex-col 被
+        stretch 撐滿 max-w-md 的 bug)。需要 full-width row 的 child 自己 w-full / self-stretch */}
+    <div className="flex flex-col gap-4 max-w-md items-start">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+// ── WhenToUse — 何時使用 Badge ──────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / DotVsCountRule(2026-04-26 v3 canonical)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div className="flex flex-col gap-12">
+      {/* 何時用 — 原 WhenToUse */}
+      <div className="prose prose-sm max-w-prose">
+      <p>適合 Badge 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/Badge/展示" name="正圓 vs 膠囊"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">正圓 vs 膠囊</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Badge/展示" name="圓點模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Dot 模式</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Badge/展示" name="數量上限"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Max 上限</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">判斷不確定時:先確認使用者真正需要的是「有沒有新東西」(用 Dot)還是「有多少」(用數字)。若兩者都不貼切,代表這裡可能不該放 Badge——改用文字標籤或其他狀態指示。</p>
+    </div>
+
+      {/* vs 近親 — DotVsCountRule — 原 DotVsCountRule */}
+      <div>
+      <Rule
+        title="Count — 數字本身有意義（3 vs 30 觸發不同 urgency）"
+        note="未讀訊息 / 錯誤數 / 購物車品項——使用者會根據數字決定行動優先序"
+      >
+        <div className="flex items-center gap-4">
+          <Button
+            variant="tertiary"
+            size="sm"
+            iconOnly
+            startIcon={MessageSquare}
+            aria-label="訊息 (3)"
+            overlayBadge={<Badge count={3} variant="critical" />}
+          />
+          <Button
+            variant="tertiary"
+            size="sm"
+            iconOnly
+            startIcon={MessageSquare}
+            aria-label="訊息 (42)"
+            overlayBadge={<Badge count={42} variant="critical" />}
+          />
+          <Button
+            variant="tertiary"
+            size="sm"
+            iconOnly
+            startIcon={MessageSquare}
+            aria-label="訊息 (150 則)"
+            overlayBadge={<Badge count={150} max={99} variant="critical" />}
+          />
+          <Label>3 vs 42 vs 99+ 觸發不同 urgency 感</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="Dot — 存在性指示（「有新東西」即訊號）"
+        note="新功能提示、unsaved changes、在線狀態——具體數量不重要或無意義。Dot overlay 的設計準則:只疊在 iconOnly button / 單一 icon / avatar 上(容器本身就是單一視覺重心)。text + icon button 的右上角離 icon 太遠,dot 會像飄在空中的裝飾,語義不成立。"
+      >
+        <div className="flex items-center gap-4">
+          <Button
+            variant="tertiary"
+            size="sm"
+            iconOnly
+            startIcon={Settings}
+            aria-label="設定(有新功能)"
+            overlayBadge={<Badge dot variant="critical" aria-label="有新功能" />}
+          />
+          <Label>「設定有新功能」—— iconOnly Button `overlayBadge` prop,dot 中心貼齒輪 icon 的 top-right corner(不是按鈕角)</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ text + icon button 右上疊 dot"
+        note="按鈕寬度遠大於 icon,dot 跑到按鈕右邊緣,離 icon 太遠視覺上不連結。使用者不會把 dot 和齒輪 icon 的「有新功能」語義配對起來"
+      >
+        <div className="flex items-center gap-4">
+          {/* ❌ anti-pattern demo intentionally kept: text+icon Button + overlay dot —— 整個 Rule 的主軸就是
+              「dot 飄在 button chrome 角不是 icon 角」,此處保留 old `relative + absolute` pattern 作為
+              視覺反例,讓讀者看到 dot 為何離 icon 很遠 */}
+          <div className="relative inline-flex">
+            <Button variant="tertiary" size="sm" startIcon={Settings}>設定</Button>
+            <Badge dot variant="critical" className="absolute -top-1 -right-1" aria-label="有新功能" />
+          </div>
+          <Label warn>↑ dot 飄在「設定」文字右上角的空處,跟齒輪 icon 毫無視覺連結</Label>
+        </div>
+        <Label>改法:(a) 按鈕改 iconOnly + dot 疊 icon 角落、(b) 移除 dot 改用內部文字 badge(目前 DS 無 text-only badge,屬 tech debt)、(c) 移到 text 後 inline 小字「設定(新)」</Label>
+      </Rule>
+
+      <Rule
+        title="判斷法：「使用者想知道『有沒有』還是『多少』？」"
+        note="知道有就夠 → dot / 需要數量判斷 urgency → count"
+      >
+        <Label>若 count 永遠顯示 99+(threshold 失去區別力),改用 dot 或升高 max</Label>
+      </Rule>
+    </div>
+    </div>
+  ),
+}
+
+export const DefaultLowRule: Story = {
+  name: '預設低強度,有理由才升級',
+  render: () => (
+    <div>
+      <Rule
+        title="選 level 時問：使用者錯過會怎樣？"
+        note="從 low 起跳,只有當內容本身 urgency 更高才升級。Critical 的紅色從「罕見」獲得信號價值——過度使用會稀釋紅色在產品內的「急迫」意義"
+      >
+        <div className="flex items-center gap-4">
+          <div className="flex items-center gap-2">
+            <Archive size={16} />
+            <span className="text-body">Archive</span>
+            <Badge count={128} variant="low" />
+          </div>
+          <Label>low — 錯過無影響（被動計數）</Label>
+        </div>
+        <div className="flex items-center gap-4">
+          <div className="flex items-center gap-2">
+            <MessageSquare size={16} />
+            <span className="text-body">留言</span>
+            <Badge count={12} variant="medium" />
+          </div>
+          <Label>medium — 輕微不便（可延後看）</Label>
+        </div>
+        <div className="flex items-center gap-4">
+          <div className="flex items-center gap-2">
+            <Bell size={16} />
+            <span className="text-body">待辦</span>
+            <Badge count={7} variant="high" />
+          </div>
+          <Label>high — 有感影響（工作堆積）</Label>
+        </div>
+        <div className="flex items-center gap-4">
+          <div className="flex items-center gap-2">
+            <Inbox size={16} />
+            <span className="text-body">未讀私訊</span>
+            <Badge count={3} variant="critical" />
+          </div>
+          <Label>critical — 直接傷害（錯過溝通）</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ 把 passive count 當 critical（訊號稀釋）"
+        note="Archive / Trash 這類被動計數升 critical → 紅色遍地都是,使用者麻木,真正急迫的通知被稀釋"
+      >
+        <div className="flex items-center gap-2">
+          <Archive size={16} />
+          <span className="text-body">Archive</span>
+          <Badge count={128} variant="critical" />
+        </div>
+        <Label warn>↑ Archive 有多少郵件不需要 critical 紅色觸發 action——使用者只在整理時才看,用 low 即可</Label>
+      </Rule>
+
+      <Rule
+        title="自我檢查：一個畫面最多 1-2 個 critical badge"
+        note="超過代表把不急迫的事標成 critical。紅色稀缺性才有信號價值"
+      >
+        <Label>打開任何 app 的主頁面,數一下紅色 badge——超過 2 個就該降級</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const ContrastFloorRule: Story = {
+  name: '對比 下限（容器對比下限）',
+  render: () => (
+    <div>
+      <Rule
+        title="最終強度,取「內容急迫度」和「容器最低需求」兩者中的較高者"
+        note="容器需求是下限(底色太深時,badge 最少要到哪個強度才看得清),不是上限——內容本身夠急迫時,還是可以再往上升。兩個條件各自獨立把強度往上推"
+      >
+        <div className="flex items-center gap-3">
+          <span className="text-footnote text-fg-muted w-20">Case 1:</span>
+          <Button
+            variant="tertiary"
+            size="sm"
+            iconOnly
+            startIcon={Bell}
+            aria-label="通知 (3)"
+            overlayBadge={<Badge count={3} variant="high" />}
+          />
+          <Label>內容急迫度=high,容器要求只到 low → 用 high(內容急迫度已經高於容器最低需求)</Label>
+        </div>
+        <div className="flex items-center gap-3">
+          <span className="text-footnote text-fg-muted w-20">Case 2:</span>
+          {/* ❌ anti-pattern demo intentionally kept: text+icon Button + overlay Badge
+              展示 semantic 錯配(primary 容器逼 passive count 升 critical);同時保留
+              text+icon+overlay 的幾何 anti-pattern — badge 飄在 button chrome 角而非 icon 角 */}
+          <div className="relative inline-flex">
+            <Button variant="primary" startIcon={Bell}>通知</Button>
+            <Badge count={3} variant="critical" className="absolute -top-1 -right-1" />
+          </div>
+          <Label warn>內容急迫度=low(被動計數),但 primary 按鈕底色深,容器要求逼到 high/critical → 被迫升級(這代表設計擺錯位置)</Label>
+        </div>
+        <div className="flex items-center gap-3">
+          <span className="text-footnote text-fg-muted w-20">Case 3:</span>
+          <Button
+            variant="tertiary"
+            size="sm"
+            iconOnly
+            startIcon={Bell}
+            aria-label="錯誤 (5)"
+            overlayBadge={<Badge count={5} variant="critical" />}
+          />
+          <Label>內容急迫度=critical 業務需求本身就急 → 用 critical,容器最低需求不會把它往下壓</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="Case 2 是設計錯配訊號——重新考慮放置"
+        note="passive count 被 primary button 逼到 high/critical,semantic 跟 visual 不搭。解決不是一直升 level,是重新思考這 badge 該不該在這裡"
+      >
+        <Label>改用 dot 模式 / 移到外部 label / 乾脆不放 badge</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 為了「能在深色容器上看見」把 passive count 升 critical"
+        note="扭曲 level 語意——把「被動資訊」包裝成「需立即處理」,誤導使用者的注意力分配"
+      >
+        {/* ❌ anti-pattern demo intentionally kept: text+icon Button + overlay Badge
+            本 story 主軸是 semantic level 錯配(passive 被迫 critical),demo 幾何用
+            舊 pattern 保留「text+icon + overlay」本身就是 anti-pattern 的視覺訊號 */}
+        <div className="relative inline-flex">
+          <Button variant="primary" startIcon={Archive}>Archive</Button>
+          <Badge count={128} variant="critical" className="absolute -top-1 -right-1" />
+        </div>
+        <Label warn>↑ Archive 的 128 被強制 critical 紅色 → 使用者誤以為「要去看」,實際只是總數</Label>
+      </Rule>
+
+      <Rule
+        title="✓ 正確做法:按鈕降級 + badge 回歸 low"
+        note="Archive 是歸檔/整理動作,不是 primary CTA——本來就該是 tertiary。按鈕降級後容器 contrast floor 放寬,badge 可以用 passive 原本的 low level,semantic 跟 visual 一致,訊號清楚。「想要 primary 按鈕 + critical badge」通常是資訊架構設定錯——重看:這顆按鈕真的是頁面主 CTA 嗎?"
+      >
+        {/* Note: 本 story 聚焦 level semantic 對照(critical → low);幾何仍是
+            text+icon Button + overlay,非 iconOnly overlay 設計準則。若要幾何也對齊
+            設計準則 應改為 iconOnly + `overlayBadge` prop,或移除 overlay 改 inline badge */}
+        <div className="relative inline-flex">
+          <Button variant="tertiary" startIcon={Archive}>Archive</Button>
+          <Badge count={128} variant="low" className="absolute -top-1 -right-1" />
+        </div>
+        <Label>↑ tertiary Archive + low badge(灰底灰字)—— 「有 128 筆被歸檔」passive 展示,不誘導 click</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const AccessibilityRule: Story = {
+  name: '無障礙必備',
+  render: () => (
+    <div>
+      <Rule
+        title="Parent 元件的 aria-label 必須整合 badge 資訊"
+        note="Badge 預設 role=「status」(live region 可播報計數變化),但仍應由 parent 的 aria-label 整合完整 context——「通知 (3 則未讀)」比「通知」+「3」更清楚"
+      >
+        <Button
+          variant="tertiary"
+          size="sm"
+          iconOnly
+          startIcon={Bell}
+          aria-label="通知 (3 則未讀)"
+          overlayBadge={<Badge count={3} variant="critical" />}
+        />
+        <Label>✓ aria-label="通知 (3 則未讀)" — screen reader 一次讀出完整資訊</Label>
+      </Rule>
+
+      <Rule
+        title="Dot 模式必須給 aria-label"
+        note="Dot 無文字,screen reader 完全看不到——沒 aria-label 等於對 a11y 使用者不存在"
+      >
+        <div className="flex items-center gap-4">
+          <Badge dot variant="critical" aria-label="有新訊息" />
+          <span className="text-body">✓ 有 aria-label</span>
+        </div>
+        <div className="flex items-center gap-4">
+          <Badge dot variant="critical" />
+          <span className="text-body">❌ 沒 aria-label</span>
+        </div>
+        <Label warn>↑ 沒 aria-label 的 dot → screen reader 使用者不知道「有東西」</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 單靠顏色傳達 urgency（color-blind 失效）"
+        note="Badge 的 level 靠顏色(紅/藍/灰)——color-blind 使用者可能分不清 critical vs high。必須搭配 aria-label、count 數字、或容器上的其他視覺指示"
+      >
+        <div className="flex items-center gap-4">
+          <Badge dot variant="critical" aria-label="緊急" />
+          <Badge dot variant="high" aria-label="重要" />
+        </div>
+        <Label>↑ critical(橘)vs high(藍)只靠顏色——color-blind 使用者分不清,必須靠 aria-label 明確語意,不能只靠顏色</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const PlacementRule: Story = {
+  name: '三種放置模式',
+  render: () => (
+    <div>
+      <Rule
+        title="Overlay — 疊加在視覺重心（iconOnly / avatar / 純 icon）"
+        note="標準 API:`<Button overlayBadge={...}>` — badge 中心對齊 icon 的 top-right corner(Material BadgedBox / iOS App Icon)。不手刻 relative + absolute,避免 badge 飄到 button chrome 邊緣"
+      >
+        <Button
+          variant="tertiary"
+          size="sm"
+          iconOnly
+          startIcon={Bell}
+          aria-label="通知 (3)"
+          overlayBadge={<Badge count={3} variant="critical" />}
+        />
+      </Rule>
+
+      <Rule
+        title="Inline — 跟 label 並列（計數展示）"
+        note="Tab / Menu item / Section title 旁邊顯示計數。不用 absolute,gap 控制間距"
+      >
+        <div className="flex items-center gap-2">
+          <FileText size={16} />
+          <span className="text-body">文件</span>
+          <Badge count={12} variant="low" />
+        </div>
+        <Label>↑ 「文件 (12)」一體展示,不是 overlay</Label>
+      </Rule>
+
+      <Rule
+        title="Standalone — 獨立狀態指示"
+        note="通常是 dot 模式,跟 description 文字並列作為狀態 indicator"
+      >
+        <div className="flex items-center gap-2">
+          <Badge dot variant="critical" aria-label="同步失敗" />
+          <span className="text-body">同步失敗</span>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ 一個元件同時疊多個同類 badge"
+        note="同一 trigger 疊兩個不同 urgency 的同類訊號(count + dot 都是通知重要性)→ 使用者無法判斷哪個重要。合併成一個 badge。不同角、不同語義 OK(Avatar 右下 presence + 右上 count 是合法,見「Avatar + badgeCount + status」demo)"
+      >
+        {/* ❌ anti-pattern demo intentionally kept: Button `overlayBadge` prop 只支援單一 badge
+            (設計準則 就是避免 signal crowding);本 rule 主軸是「不該這樣做」,用舊
+            `relative + absolute` 手刻兩個 badge 作為視覺反例 */}
+        <div className="relative inline-flex">
+          <Button variant="tertiary" size="sm" iconOnly startIcon={Bell} aria-label="通知" />
+          <Badge count={3} variant="critical" className="absolute -top-1 -right-1" />
+          <Badge dot variant="high" className="absolute -bottom-1 -right-1" />
+        </div>
+        <Label warn>↑ 同一顆 Bell 按鈕同時表達「未讀 3」和「有更新(dot)」—— 兩個都是通知訊號,語義重疊 → 使用者混淆</Label>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/Badge/badge.spec.md

@@ -1,6 +1,6 @@
 ---
 component: Badge
-family: 3
+family: self-contained
 variants:
   critical:
     when: "最高優先級通知 — 錯誤計數 / 緊急徽章（Gmail 未讀 / iOS notification red dot）"
@@ -24,7 +24,6 @@ benchmark:
   - Polaris Badge: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Badge
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
 
 # Badge 設計原則
 
@@ -41,8 +40,7 @@ Badge 是通知計數指示器，用於未讀數量、待辦計數、狀態紅
 ## 何時用
 
 - **通知計數**：收件匣未讀數（3）、待辦事項數（12）、notification center 新訊息數
-- **狀態紅點**（dot 模式）：新功能提示、「有新內容」不需具體數字
-- **版本 / 角色標記**：「Beta」、「Pro」、「Admin」（當視覺重量需要比 Tag 更輕時）
+- **狀態紅點**（dot 模式,只 critical/high）：新功能提示、「有新內容」不需具體數字的單一 attention 點
 - **疊加在互動元件右上角**：Button iconOnly + Badge 通知 icon（鈴鐺 + 3）
 
 ## 何時不用
@@ -53,6 +51,7 @@ Badge 是通知計數指示器，用於未讀數量、待辦計數、狀態紅
 | 狀態描述（In stock / Out of stock）| `Tag` + 色彩 | 狀態語意用 Tag 的 variant 系統（green/yellow/red）更明確 |
 | 過濾 / 選擇（filter chip）| `Chip` | Badge 不可互動，Chip 是 filter 選取 |
 | Loading 指示 | `CircularProgress` | Badge 是數字或 dot,loading 用旋轉動畫 |
+| 版本 / 角色標記(「Beta」「Pro」「Admin」)| `Tag` | Badge 僅 count / dot 兩模式,**無文字承載**(text-only badge 屬 tech debt,見 principles story);文字標記走 Tag |
 
 ---
 
@@ -62,14 +61,23 @@ Badge 是通知計數指示器，用於未讀數量、待辦計數、狀態紅
 
 **核心原則：Default LOW, escalate only with reason.**
 
-Badge 的 level **反映內容的緊急程度，不是 container 的視覺權重**——從 low 起跳，只有當通知內容本身值得更多注意力時才升級。這樣 critical 的紅色從「罕見」獲得信號價值，過度使用會讓使用者麻木、無法分辨真正的急迫。
+Badge 的 level **反映內容的緊急程度，不是 container 的視覺權重**——從 low 起跳，只有當通知內容本身值得更多注意力時才升級。這樣 critical 的 notification 色(deep-orange)從「罕見」獲得信號價值，過度使用會讓使用者麻木、無法分辨真正的急迫。
 
 | Variant | 視覺 | 使用者錯過會怎樣 |
 |---------|------|------------------|
 | `low`（起點）★ cva default | 灰底灰字（neutral-3 + neutral-7） | **無影響**——只是「目前有這麼多」的資訊，不讀也沒關係 |
 | `medium` | 淺藍底藍字（bg-info-subtle） | **輕微不便**——少了資訊但不影響主要流程 |
 | `high` | 藍底白字（bg-info） | **有感影響**——工作會堆積、待辦會過期，但不是立即傷害 |
-| `critical` | 紅底白字（bg-notification） | **直接傷害**——錯過訊息會造成資料遺失 / 錯過機會 / 帳戶問題 |
+| `critical` | deep-orange 底白字（bg-notification = `--color-deep-orange-6`,hue 38;非 categorical red hue 25） | **直接傷害**——錯過訊息會造成資料遺失 / 錯過機會 / 帳戶問題 |
+
+### Dot 變體（只 `critical` / `high`,2026-06-05 user 拍板 Option A）
+
+**dot 模式只接 `critical` / `high` 兩個高訊號 attention 色,不提供 `medium` / `low` dot。** dot = 「這裡有東西要看」的單一 attention 點(預設 `critical`);6px 純色圓點無文字、只能靠顏色傳達——淡灰(low)/ 淺藍(medium)的 6px 點幾乎看不見,也傳達不了「值得注意」,**不 earn existence**。
+
+- **世界級對照**:Material small-badge = 單色 attention dot;Ant Badge `status` dot = success/error/warning/**default(灰)**,語意 status 非 severity;Polaris = 語意 status tone,無 low/medium/high dot;Atlassian presence/status dot 另開元件。**無一家把 dot 做成 4 級 severity 刻度**。
+- **medium / low 仍完整保留於 count badge**(有文字承載對比,淡底合理)。
+- **型別機械強制**:`BadgeProps` 為 discriminated union,`dot: true` 時 `variant` 限 `'critical' | 'high'`(傳 medium/low → compile error)。
+- 需「中性/inactive」的實心灰點 → 走 `--status-offline`(neutral-6 實心)presence 系統,非 Badge dot。
 
 ### 選 level 的流程
 
@@ -90,18 +98,18 @@ Badge 的 level **反映內容的緊急程度，不是 container 的視覺權重
 | 已完成 task 總數 | `low` | 成就指標，不期待使用者關注 |
 | 可用更新數量（套件、訂閱） | `medium` | 有參考價值，延遲看不影響 |
 | 評論 / 回覆計數 | `medium` | 社交互動，可延後處理 |
-| 新功能提示（NEW / Beta）| `high` | 重要但可延後，非必要立即處理 |
+| 新功能提示(dot)| `high` | 重要但可延後，非必要立即處理 |
 | 待辦事項計數 | `high` | 工作會堆積，有感影響 |
 | Active toggle 顯示計數（如 Filter [3]、Bold pressed 的套用數）| `high`（或 `medium`）| Active 狀態補充資訊，不是急迫訊號 |
 | 通知中心 bell icon 的數字 | `high` 或 `critical` | 視內部通知性質，全是急迫才 critical |
-| Email / Slack 未讀訊息 | `critical` | 錯過會錯過溝通，紅色觸發 action |
+| Email / Slack 未讀訊息 | `critical` | 錯過會錯過溝通，notification 色觸發 action |
 | 錯誤計數（表單 / CI） | `critical` | 必須立即處理才能繼續 |
 | 帳戶警告（付款失敗、到期） | `critical` | 有金錢 / 服務中斷風險 |
 
 ### 色彩硬規則（不可違反）
 
-- **❌ Critical 不是紅色就是錯誤**——critical 永遠 `bg-notification`（紅）。改色等於改信號語意，稀釋紅色在產品內的「急迫」意義
-- **❌ High 不能用紅色**——會跟 critical 搶信號。藍色是「重要但不急」的全球共識
+- **❌ Critical 不是 notification 色就是錯誤**——critical 永遠 `bg-notification`(deep-orange-6)。改色等於改信號語意，稀釋 notification 色在產品內的「急迫」意義
+- **❌ High 不能用 notification 色**——會跟 critical 搶信號。藍色是「重要但不急」的全球共識
 - **❌ 不能為了「視覺統一」把所有 badge 降 level**——使用者需要看到 level 差異才能分配注意力，全部 low 等於沒 badge
 - **❌ 不能為了「強調」把 low 升 level**——升 level 改變的是「這件事多重要」的承諾，不是消費者的偏好
 
@@ -143,7 +151,7 @@ Contrast floor **是下限不是上限**——不限制 semantic 繼續往上。
 | checked（pressed state，通常淺灰或 subtle 底） | `low` / `medium` | ✓ 多數直接用；bg 較深時 floor 提高 |
 | primary / secondary+danger（飽和深底） | `high` | low/medium 被迫 bump；high/critical 直接用 |
 
-**Critical 的紅白對比在任何底色上都清楚**——不存在「critical 看不清」的場景。
+**Critical 的深底白字對比在任何底色上都清楚**——不存在「critical 看不清」的場景。
 
 ### Case 2 是設計錯配訊號
 
@@ -158,13 +166,13 @@ Contrast floor **是下限不是上限**——不限制 semantic 繼續往上。
 
 ---
 
-## 字體例外：`text-[10px]`（documented sub-footnote）
+## 字體例外：`text-[10px]`（documented micro-indicator 例外）
 
-Badge count 模式的數字使用 `text-[10px]`,低於 typography 系統最小的 `--font-footnote`（12px）。這是 **Badge 獨有的合法例外**：
+Badge count 模式的數字使用 `text-[10px]`（10px,與 typography 系統最小的 `--font-footnote` 同值;12px 是 `--font-caption`）。不消費 `text-footnote` utility——該 utility 綁 line-height 1.3 且語意為法律文字/來源標注,Badge count 需要 `leading-none`（circle 內數字置中 canonical）。這是 **Badge 獨有的合法例外**：
 
 - **為什麼不加新 typography token**: 10px 是「count indicator 專用尺寸」,全系統**只有 Badge / OverflowIndicator 兩處**使用；創一個 `--font-micro` token 只為這兩個消費者會過度 generalization
-- **為什麼合法**: Badge count 是輔助 indicator（次要訊號）,12px 字寬在 16×16 的圓形 Badge 內缺乏 padding 呼吸(字徑/圓徑比例過密)。對照世界級:Material Badge 10sp、Polaris Badge 字級小於 body、GitHub Counter 10-11px 都小於 body footnote <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-- **其他元件不得比照**: 若新元件覺得需要 `text-[10px]`,先問「真的不是 footnote 12px 可以解決嗎」,99% 情境 footnote 夠用;真有需求跟 Badge / OverflowIndicator 歸同一 micro-indicator family 討論
+- **為什麼合法**: Badge count 是輔助 indicator（次要訊號）,caption（12px）字寬在 16×16 的圓形 Badge 內缺乏 padding 呼吸(字徑/圓徑比例過密)。此例外由 badge 自身幾何與資訊層級決定，不建立跨元件字級 tier。
+- **其他元件不得比照**: 若新元件覺得需要 `text-[10px]`,先問「真的不是 caption 12px 可以解決嗎」,99% 情境 caption 夠用;真有需求跟 Badge / OverflowIndicator 歸同一 micro-indicator family 討論
 
 ---
 
@@ -180,6 +188,8 @@ Badge count 模式的數字使用 `text-[10px]`,低於 typography 系統最小
 
 **實作**：固定高度小於 Field 元件（保持輔助層級）；個位數時為正圓，多位數時變膠囊——由 count 長度自動決定形狀。具體 token / class 見 `.tsx` cva。
 
+**空值 / 零值**：`count` 不傳（`undefined`/`null`）→ 整顆不渲染（badge.tsx `count == null → return null`）；`count={0}` → 照實渲染「0」。0 = 無訊號（多數通知場景）→ consumer 在 0 時不傳 count；0 有意義（報表計數）才傳。本 DS 不做 `showZero` 開關（Ant [ant.design/components/badge](https://ant.design/components/badge) / MUI [mui.com/material-ui/api/badge](https://mui.com/material-ui/api/badge/) 皆 `showZero` 預設 false = 零值預設隱藏；本 DS 以「不傳 count」表達同語意，零值語意由 consumer 資料層決定，元件不猜）。
+
 ### Dot — 存在性指示
 
 **何時用**：「有東西」本身就是訊號，具體數量不重要或無意義。
@@ -230,7 +240,7 @@ Q2. 容器是「單一視覺重心」嗎?(iconOnly button / 純 icon / avatar)
     → NO → Q3
 
 Q3. Badge 自己獨立呈現狀態嗎?(無宿主元件)
-    → YES → Standalone(「● 離線 Alex」狀態 row)
+    → YES → Standalone(「● 同步失敗」狀態 row)
 ```
 
 **為什麼 Inline 在企業更常見**：
@@ -257,8 +267,8 @@ Q3. Badge 自己獨立呈現狀態嗎?(無宿主元件)
 ```
 
 - **語意**：元件主內容（icon / avatar）+ 補充通知
-- **實作**：badge **絕對定位相對於 icon / avatar 視覺重心**,不相對於 interactive chrome。Button `overlayBadge` prop 內部用 `<span className="relative inline-flex">` 包 icon、badge 中心對齊 icon top-right corner(Material BadgedBox canonical)。**不再允許** consumer 手刻 `<div relative><Button/><Badge absolute/></div>`——padding 差距會讓 badge 飄到 chrome 角 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-- **世界級對照**：Material BadgedBox / iOS App Icon / Ant Design Badge — 全部 wrap 視覺重心(icon / avatar),不 wrap interactive chrome(button padding) <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- **實作**：badge **絕對定位相對於 icon / avatar 視覺重心**,不相對於 interactive chrome。Button `overlayBadge` prop 內部用 `<span className="relative inline-block">`(明確鎖 width/height = iconSize)包 icon、badge 中心對齊 icon top-right corner。**不再允許** consumer 手刻 `<div relative><Button/><Badge absolute/></div>`——padding 差距會讓 badge 飄到 chrome 角。
+- **Anchor invariant**：overlay badge wrap 視覺重心(icon / avatar),不 wrap 含 padding 的 interactive chrome。
 - **aria**：parent 元件的 `aria-label` 包含 badge 資訊（見「無障礙」）
 
 ### Overlay 適用元件 canonical(2026-04-20)
@@ -272,7 +282,7 @@ Q3. Badge 自己獨立呈現狀態嗎?(無宿主元件)
 - ❌ **text + icon Button**:按鈕寬度遠大於 icon,badge 跑到按鈕右邊緣,離 icon 太遠,視覺上 dot / count 跟 icon 語義無法配對。使用者不會把 "飄在按鈕邊緣的小點" 和齒輪 icon 的 "有新功能" 連結起來。改用:(a) 按鈕改 iconOnly、(b) 移除 overlay 改 inline badge 在 text 後。
 - ❌ **Primary / 主 CTA button**:contrast floor 會逼 badge 升階到 critical,扭曲 passive count 的語意(見「Contrast floor」rule)。Archive 這種歸檔動作本來就不該是 primary;正確做法是按鈕降級 tertiary + badge 回歸 low。
 
-世界級對照:iOS / Material / macOS / Slack 的 badge dot 永遠貼在 **App icon 或單一 icon** 上,從不疊在「icon + text」的 inline button 右上角。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+Badge dot 只附著在 **App icon、avatar 或單一 icon**；禁止疊在「icon + text」的 inline button 右上角，因為複合 label 沒有單一穩定視覺 anchor。
 
 ### 2. Inline（跟 label 並列）
 
@@ -295,8 +305,8 @@ Tab / Menu item / Section title 旁邊顯示計數。
 
 ```tsx
 <div className="flex items-center gap-2">
-  <Badge dot variant="critical" aria-label="離線" />
-  <span>離線</span>
+  <Badge dot variant="critical" aria-label="同步失敗" />
+  <span>同步失敗</span>
 </div>
 ```
 
@@ -328,7 +338,7 @@ Badge 必須讓 screen reader 使用者獲得**同等資訊**——不能只靠
 
 ### 色彩不獨立承載意義（color-blind）
 
-Badge 的 level 靠顏色區分（紅 / 藍 / 灰）——color-blind 使用者可能無法分辨 critical vs high。
+Badge 的 level 靠顏色區分(deep-orange / 藍 / 灰)——color-blind 使用者可能無法分辨 critical vs high。
 
 **必須**搭配：
 - **Count 數字或 aria-label 傳達具體內容**（「3 則緊急錯誤」而非單純「紅色 badge 3」）
@@ -368,13 +378,23 @@ Badge 是**計數 / 狀態視覺指示器**,本身**非互動元件**:
 - Badge 通常依附在互動元件上(Button / Nav Item),那些元件有自己的 state——Badge 隨父層視覺連動,不擁有獨立 state。
 - 計數變化(`count` 更新)屬資料更新不是 UI state 切換。
 
-對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix` + `SizeMatrix`。
+對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix` + `SizeMatrix` + `Accessibility`。
 
 ---
 
 ## 相關
 
 - `../Tag/tag.spec.md` — 分類標籤、狀態標記（Badge vs Tag 的詳細對照在本 spec 定位段落）
+- `../Avatar/avatar.spec.md` — `badgeCount` 內部消費 `<Badge variant="critical">`（遵循本 spec）;`status` 是 Avatar 自有 presence dot（內部 `span` + inline backgroundColor,非 Badge 系統）,兩者可並存,詳該 spec
 - `../Button/button.spec.md` — iconOnly Button + Badge overlay 通知 icon 的組合模式
 - `../Chip/chip.spec.md` — 可互動 filter（不是 Badge 的用途）
 - `../CircularProgress/circular-progress.spec.md` — Loading 狀態指示(取代 Spinner)
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `avatar.spec.md`
+- `button.spec.md`
+- `overflow-indicator.spec.md`
+- `tag.spec.md`