@qijenchen/design-system 0.1.0-beta.83 → 0.1.0-beta.85

package/src/components/AspectRatio/aspect-ratio.stories.tsx

@@ -1,13 +1,12 @@
 // @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 type { Meta, StoryObj } from '@storybook/react'
 import { AspectRatio } from './aspect-ratio'
 
 /**
  * AspectRatio 展示——固定長寬比容器,常用於圖片 / 截圖 / illustration 鎖比例。
- * 展示範例對標世界級產品的真實情境(Airbnb listing hero、Stripe product 卡、
- * Instagram 方圖、YouTube cinematic banner),consumer 包 <img className="w-full
- * h-full object-cover" /> 是標準用法。設計規則詳見 `aspect-ratio.spec.md`。
+ * 展示範例對標世界級產品的真實情境(Stripe product 卡、YouTube cinematic banner),
+ * consumer 包 <img className="w-full h-full object-cover" /> 是標準用法。
+ * 全比例對照矩陣由設計規格層 StandardRatios owns。設計規則詳見 `aspect-ratio.spec.md`。
  */
 
 const meta: Meta = {
@@ -17,37 +16,11 @@ const meta: Meta = {
 export default meta
 type Story = StoryObj
 
-// ── Helpers ───────────────────────────────────────────────────────────────────
-
-const Figure = ({
-  children, caption,
-}: { children: React.ReactNode; caption: string }) => (
-  <figure className="flex flex-col gap-2">
-    {children}
-    <figcaption className="text-footnote text-fg-muted">{caption}</figcaption>
-  </figure>
-)
-
 // ── Stories ───────────────────────────────────────────────────────────────────
-
-export const HeroBanner16x9: Story = {
-  name: '16:9 主視覺橫幅',
-  render: () => (
-    <div className="max-w-[720px]">
-      <h3 className="text-body font-bold text-foreground mb-1">Airbnb listing hero</h3>
-      <p className="text-caption text-fg-muted mb-5 max-w-[600px] leading-relaxed">
-        寬螢幕影片、feature 截圖、listing cover 標配——16/9 是最主流的 web hero ratio(Vercel、Airbnb、Linear hero section)。
-      </p>
-      <AspectRatio ratio={16 / 9} className="bg-muted rounded-lg overflow-hidden">
-        <img
-          src="https://picsum.photos/seed/airbnb-hero/800/450"
-          alt="Beachfront cottage in Santorini"
-          className="w-full h-full object-cover"
-        />
-      </AspectRatio>
-    </div>
-  ),
-}
+// HeroBanner16x9 / SquareAvatar1x1 / CommonRatios retired 2026-07-14 per audit Dim 24(story 重複性):
+// 比例是數值 prop 非 affordance,逐值 story 無獨立教學原則;全比例對照矩陣已由
+// anatomy StandardRatios(aspect-ratio.anatomy.stories.tsx,5 ratio 含 21/9 / 3/4)owns。
+// 展示層保留真實業務場景:ProductPhoto4x3(教 CLS 防坍塌)+ Ultrawide21x9(cinematic 寬幅情境)。
 
 export const ProductPhoto4x3: Story = {
   name: '4/3 產品照片 + 防版面跳動對照',
@@ -94,29 +67,6 @@ export const ProductPhoto4x3: Story = {
   ),
 }
 
-export const SquareAvatar1x1: Story = {
-  name: '1:1 社群方形貼文',
-  render: () => (
-    <div className="max-w-[600px]">
-      <h3 className="text-body font-bold text-foreground mb-1">Instagram-style 方形貼文</h3>
-      <p className="text-caption text-fg-muted mb-5 max-w-[600px] leading-relaxed">
-        方形貼文預覽、avatar、icon preview 標配——1/1 讓 feed grid 對齊一致。
-      </p>
-      <div className="grid grid-cols-3 gap-1">
-        {['coffee', 'mountain', 'city', 'sunset', 'plant', 'food'].map(seed => (
-          <AspectRatio key={seed} ratio={1} className="bg-muted overflow-hidden">
-            <img
-              src={`https://picsum.photos/seed/${seed}/400/400`}
-              alt={seed}
-              className="w-full h-full object-cover"
-            />
-          </AspectRatio>
-        ))}
-      </div>
-    </div>
-  ),
-}
-
 export const Ultrawide21x9: Story = {
   name: '21:9 影院橫幅',
   render: () => (
@@ -136,35 +86,3 @@ export const Ultrawide21x9: Story = {
   ),
 }
 
-export const CommonRatios: Story = {
-  name: '常用 比例 一覽',
-  render: () => (
-    <div className="flex flex-col gap-8 max-w-[720px]">
-      <p className="text-caption text-fg-muted max-w-[600px] leading-relaxed">
-        DS 標準 ratio 視覺對照——選擇對應情境的數值。
-      </p>
-      <div className="grid grid-cols-2 gap-4">
-        <Figure caption="16/9 — 寬螢幕 hero / 影片">
-          <AspectRatio ratio={16 / 9} className="bg-muted rounded-md overflow-hidden">
-            <img src="https://picsum.photos/seed/r16-9/640/360" alt="" className="w-full h-full object-cover" />
-          </AspectRatio>
-        </Figure>
-        <Figure caption="4/3 — 產品照 / 截圖">
-          <AspectRatio ratio={4 / 3} className="bg-muted rounded-md overflow-hidden">
-            <img src="https://picsum.photos/seed/r4-3/600/450" alt="" className="w-full h-full object-cover" />
-          </AspectRatio>
-        </Figure>
-        <Figure caption="1/1 — 方形 / avatar">
-          <AspectRatio ratio={1} className="bg-muted rounded-md overflow-hidden">
-            <img src="https://picsum.photos/seed/r1-1/400/400" alt="" className="w-full h-full object-cover" />
-          </AspectRatio>
-        </Figure>
-        <Figure caption="3/4 — 直式 portrait">
-          <AspectRatio ratio={3 / 4} className="bg-muted rounded-md overflow-hidden">
-            <img src="https://picsum.photos/seed/r3-4/450/600" alt="" className="w-full h-full object-cover" />
-          </AspectRatio>
-        </Figure>
-      </div>
-    </div>
-  ),
-}

package/src/components/Avatar/avatar.anatomy.stories.tsx

@@ -164,7 +164,8 @@ export const Overview = {
         </div>
         <div className="flex gap-8">
           <div className="flex flex-col items-center gap-2">
-            <Avatar size={40} alt="Alice" color="blue" shape="circle" />
+            {/* circle = 人物 → 真實人像(2026-07-08 demo 人像真實化);square = 實體 → icon */}
+            <Avatar size={40} src="https://i.pravatar.cc/80?u=alice-chen" alt="Alice" shape="circle" />
             <span className="text-[11px] font-mono text-fg-muted">circle（預設）</span>
             <span className="text-[10px] text-fg-muted">rounded-full</span>
           </div>
@@ -644,6 +645,9 @@ export const StateBehavior = {
         <H3>Fallback chain（src 失敗 → icon → alt → User）</H3>
         <Desc>Avatar 不是互動元件,沒有 hover / focus / active。實際「狀態」是內容降級——src 載入失敗時自動依優先順序往下回退,確保永遠不會出現破圖。</Desc>
       </div>
+      {/* 刻意示範 fallback chain:失敗 URL / 無 src 各列**必須**維持原樣(降級行為規格,
+          2026-07-08 demo 人像真實化 sweep 豁免保留;ColorMatrix / SizeMatrix 的 Text 列同理 —
+          color / text-mode 軸只在無圖時可見) */}
       <div className="overflow-x-auto">
         <table className="border-collapse text-caption">
           <thead><tr><Th>來源</Th><Th>渲染</Th><Th>條件</Th></tr></thead>
@@ -679,7 +683,7 @@ export const StateBehavior = {
       <div className="flex items-center gap-6">
         {(['online', 'away', 'busy', 'offline'] as const).map(s => (
           <div key={s} className="flex flex-col items-center gap-2">
-            <Avatar size={40} alt="Ada" color="indigo" status={s} />
+            <Avatar size={40} src="https://i.pravatar.cc/80?u=ada-chen" alt="Ada" status={s} />
             <span className="text-[11px] font-mono text-fg-muted">{s}</span>
           </div>
         ))}
@@ -695,7 +699,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"・alt 必傳：即使有圖片,alt 同時是「圖片載入失敗時的文字 fallback」與「螢幕報讀時的身份說明」。人員頭像的 alt 建議含姓名與在線狀態(例:「陳冠霖(在線)」),組織 / 專案頭像用品牌或專案名;極少數純裝飾用途才用空字串。\n\n・沒有 alt 時的降級:圖片模式會自動降級為首字或 icon,不會留下沒有任何報讀內容的空頭像。\n\n・在線狀態點不另發報讀:右下角的狀態小點不會被螢幕報讀單獨朗讀,在線狀態整合進頭像本身的 alt 文字。這樣一長串成員名單就不會同時朗讀一堆「在線 / 離線」造成讀屏洪水。\n\n・hover 名片可用鍵盤抵達:當頭像帶有 hoverCard 時,頭像本身會變成可用 Tab 聚焦的按鈕並顯示聚焦框,鍵盤使用者也能打開名片浮層。"}</p>
+      <p className="whitespace-pre-line">{"・alt 必傳：即使有圖片,alt 同時是「圖片載入失敗時的文字 fallback」與「螢幕報讀時的身份說明」。人員頭像的 alt 建議含姓名與在線狀態(例:「陳冠霖(在線)」),組織 / 專案頭像用品牌或專案名;極少數純裝飾用途才用空字串。\n\n・沒有 alt 時的降級:圖片模式會自動降級為首字或 icon,不會留下沒有任何報讀內容的空頭像。\n\n・在線狀態點不另發報讀:右下角的狀態小點不會被螢幕報讀單獨朗讀,在線狀態整合進頭像本身的 alt 文字。這樣一長串成員名單就不會同時朗讀一堆「在線 / 離線」造成讀屏洪水。\n\n・hover 名片可用鍵盤抵達:當頭像帶有 hoverCard 時,頭像本身會變成可用 Tab 聚焦的圖像(role=img)並顯示聚焦框,鍵盤使用者也能打開名片浮層(頭像刻意不宣告成按鈕 / aria-haspopup,對齊 Radix / GitHub hover card 的零 popup ARIA 慣例)。"}</p>
     </div>
   ),
 }

package/src/components/Avatar/avatar.principles.stories.tsx

@@ -86,14 +86,15 @@ export const UsageGuidance: Story = {
           note="判斷法:「這代表『誰』還是『做什麼』?」誰 / 什麼實體 → Avatar;做什麼 / 某個概念 → Icon"
         >
           <div className="border border-divider rounded-lg bg-surface py-1">
-            <MenuItem avatar={{ alt: 'Ada Chen' }}>Ada Chen 的留言</MenuItem>
+            {/* 人員 → 真實人像;團隊 / 組織 → 首字 + 色彩(非人臉,letter mark 是 Slack workspace idiom)*/}
+            <MenuItem avatar={{ src: 'https://i.pravatar.cc/48?u=ada-chen', alt: 'Ada Chen' }}>Ada Chen 的留言</MenuItem>
             <MenuItem avatar={{ alt: 'Engineering Team', color: 'blue' }}>Engineering Team 專案</MenuItem>
           </div>
           {/* 視覺圖例(legend),非 list item */}
           <div className="flex items-center gap-3 flex-wrap mt-2">
             {/* @anatomy-exempt-next */}
             <div className="flex items-center gap-2">
-              <Avatar alt="Ada Chen" size={24} />
+              <Avatar src="https://i.pravatar.cc/48?u=ada-chen" alt="Ada Chen" size={24} />
               <span className="text-footnote text-fg-muted">人員</span>
             </div>
             <div className="flex items-center gap-2">
@@ -124,6 +125,8 @@ export const FallbackRule: Story = {
         title="有 src → 顯示圖片;沒有 src / 圖片載入失敗 → 顯示 initials"
         note="Fallback 用 `alt` 取首字母(一律取第一個字元並轉大寫,不分中英)。背景色由 `color` prop 決定"
       >
+        {/* 刻意示範 initials fallback:後三顆**必須**無 src(fallback 順序示範,
+            2026-07-08 demo 人像真實化 sweep 豁免保留) */}
         <div className="flex items-center gap-3">
           <Avatar alt="Ada Chen" size={40} src="https://i.pravatar.cc/80?img=1" />
           <Avatar alt="Ada Chen" size={40} />
@@ -145,10 +148,10 @@ export const WithBadgeOverlayRule: Story = {
         note="用 Avatar 的 `status` prop(不是手刻 `<Badge dot>`)—— 顏色走 presence semantic token(`--status-online` 等,獨立於 success / error / warning),位置固定 avatar 右下角,尺寸程式化 28%"
       >
         <div className="flex items-center gap-4">
-          <Avatar alt="Ada" size={40} status="online" />
-          <Avatar alt="Alex" size={40} status="busy" />
-          <Avatar alt="Ben" size={40} status="away" />
-          <Avatar alt="Bella" size={40} status="offline" />
+          <Avatar src="https://i.pravatar.cc/80?u=ada-chen" alt="Ada" size={40} status="online" />
+          <Avatar src="https://i.pravatar.cc/80?u=alex-wang" alt="Alex" size={40} status="busy" />
+          <Avatar src="https://i.pravatar.cc/80?u=ben-liu" alt="Ben" size={40} status="away" />
+          <Avatar src="https://i.pravatar.cc/80?u=bella-wu" alt="Bella" size={40} status="offline" />
         </div>
         <Label>↑ online / busy / away / offline ── 狀態點本身不另發語音標籤,在線狀態整合進頭像的 alt 文字(例 alt="Ada(在線)"),避免一長串成員名單同時朗讀造成讀屏洪水</Label>
       </Rule>
@@ -158,9 +161,9 @@ export const WithBadgeOverlayRule: Story = {
         note="用 Avatar 的 `badgeCount` prop(不是手刻 `<Badge count>`)—— 內部消費 DS Badge critical variant + surface ring,max=99 自動處理 99+"
       >
         <div className="flex items-center gap-4">
-          <Avatar alt="Ada" size={40} badgeCount={3} />
-          <Avatar alt="Alex" size={40} badgeCount={12} />
-          <Avatar alt="Ben" size={40} badgeCount={128} />
+          <Avatar src="https://i.pravatar.cc/80?u=ada-chen" alt="Ada" size={40} badgeCount={3} />
+          <Avatar src="https://i.pravatar.cc/80?u=alex-wang" alt="Alex" size={40} badgeCount={12} />
+          <Avatar src="https://i.pravatar.cc/80?u=ben-liu" alt="Ben" size={40} badgeCount={128} />
         </div>
         <Label>↑ count 3 / 12 / 128(超過 99 顯示 "99+")</Label>
       </Rule>
@@ -170,9 +173,9 @@ export const WithBadgeOverlayRule: Story = {
         note="兩者是**不同角、不同語義**的 slot(presence=這個人的線上狀態,右下;count=此對話未讀量,右上),對齊 `badge.spec.md`「Avatar 可疊 status + count」canonical + Slack / Teams / iMessage / LINE 標配。**signal crowding 只禁「同一角疊兩個同類 indicator」**(如右上同時 count + dot),不禁不同角不同語義的兩個訊號"
       >
         <div className="flex items-center gap-4">
-          <Avatar alt="Ada" size={40} status="online" badgeCount={3} />
-          <Avatar alt="Alex" size={40} status="busy" />
-          <Avatar alt="Ben" size={40} badgeCount={12} />
+          <Avatar src="https://i.pravatar.cc/80?u=ada-chen" alt="Ada" size={40} status="online" badgeCount={3} />
+          <Avatar src="https://i.pravatar.cc/80?u=alex-wang" alt="Alex" size={40} status="busy" />
+          <Avatar src="https://i.pravatar.cc/80?u=ben-liu" alt="Ben" size={40} badgeCount={12} />
         </div>
         <Label>↑ Ada 同時 presence(右下)+ count(右上)並存;Alex 只 presence;Ben 只 count</Label>
       </Rule>
@@ -189,13 +192,14 @@ export const HoverCardIntegrationRule: Story = {
         note="ProfileCard 是 DS 設計準則 人員 hover 內容元件(avatar + name + subtitle + actions + status + fields 統一佈局)。Avatar 的 hoverCard prop 接 ProfileCard,不可手刻 JSX — 手刻會漂移出 ProfileCard 對齊 / 間距 / status token 規則"
       >
         <Avatar
+          src="https://i.pravatar.cc/80?u=ada-chen"
           alt="Ada Chen"
           size={40}
           hoverCard={
             <ProfileCard
               name="Ada Chen"
               subtitle="Design Engineer · 台北"
-              avatar={{ alt: 'Ada Chen' }}
+              avatar={{ src: 'https://i.pravatar.cc/80?u=ada-chen', alt: 'Ada Chen' }}
               status="online"
               statusMessage="Out of Office: Back on Monday!"
               actions={<ProfileCardDefaultActions />}
@@ -216,7 +220,7 @@ export const HoverCardIntegrationRule: Story = {
       >
         <div className="flex items-start gap-8">
           <div className="flex flex-col gap-2">
-            <Avatar alt="Alex Wang" size={48}
+            <Avatar src="https://i.pravatar.cc/96?u=alex-wang" alt="Alex Wang" size={48}
               hoverCard={
                 <ProfileCard name="Alex Wang" subtitle="Engineer · 已離職" onViewMore={() => {}} />
               }
@@ -230,7 +234,7 @@ export const HoverCardIntegrationRule: Story = {
             <div className="border border-divider rounded-lg bg-surface py-1 w-full">
               <MenuItem
                 size="lg"
-                avatar={{ alt: 'Alex Wang' }}
+                avatar={{ src: 'https://i.pravatar.cc/64?u=alex-wang', alt: 'Alex Wang' }}
                 description={<span className="text-error">已離職</span>}
               >
                 Alex Wang

package/src/components/Avatar/avatar.spec.md

@@ -163,7 +163,7 @@ Avatar 堆疊的「+N」hover 也出 **HoverCard**（不是 Tooltip）——列
 | `circle`（預設） | 人物（照片、姓名） |
 | `square` | 實體（專案、組織、App、品牌） |
 
-**判斷標準：「這個 avatar 代表一個人，還是一個東西？」** 圓角由 `.tsx` inline style 決定（無 cva）：`circle` = `9999px`、`square` = `4px`（avatar.tsx `radius` ternary）。
+**判斷標準：「這個 avatar 代表一個人，還是一個東西？」** 圓角由 `.tsx` inline style 決定（無 cva），消費 radius token：`circle` = `var(--radius-full)`、`square` = `var(--radius-md)`（avatar.tsx `radius` ternary；不硬寫裸值，token 調整時自動跟隨）。
 
 ---
 
@@ -244,7 +244,7 @@ Avatar `badgeCount` 內部消費 DS `<Badge variant="critical" max={99}>`,加上
 - **無 `alt` 時 fallback**:image 模式自動降級 initials / icon;一律不靜默渲染無 SR 標的元素。
 - **Status dot SR 處理**:status dot 內部 span `aria-hidden`(presence 訊號整合進 parent `alt`),避免 `role="status"` live region 在 member list 造成 SR 洪水(詳「Status dot a11y」段)。
 - **`badgeCount` 語意**:內部消費 `<Badge variant="critical">`,由 Avatar 傳入 `aria-label="N unread"` 提供計數語義(Badge 本身只有 `role="status"`,不自產 aria-label);`badgeCount <= 0` 不渲染避免空 announce。
-- **HoverCard 整合**:Avatar 帶 `hoverCard` prop 時自動 `tabIndex=0` + `role="img"` + `aria-label`(取 `alt`)+ `focus-visible:ring-2`,確保 keyboard user 能 Tab 進入觸發 ProfileCard popover;**不掛 `role="button"` / `aria-haspopup`**(2026-07-06 拆除;role="img" 為 2026-07-07 axe 補修,詳「Keyboard 可達 canonical」段)。
+- **HoverCard 整合**:Avatar 帶 `hoverCard` prop 時自動 `tabIndex=0` + `role="img"` + `aria-label`(取 `alt`;**與 `badgeCount` 並用時 count 併入同一 aria-label** — `role="img"` 使子孫 presentational、內層 Badge 計數語義被壓平,故外層 label = `${alt}, ${badgeAriaLabel ?? 'N unread'}`,對齊 Slack 單一 accessible name 做法,2026-07-14 補修)+ `focus-visible:ring-2`,確保 keyboard user 能 Tab 進入觸發 ProfileCard popover;**不掛 `role="button"` / `aria-haspopup`**(2026-07-06 拆除;role="img" 為 2026-07-07 axe 補修,詳「Keyboard 可達 canonical」段)。
 - **Image alt 語意**:meaningful image(person photo / brand logo)用實質 `alt`;decorative-only(極少)走 `alt=""`,但 Avatar 本質是身份識別,decorative 用法應改用 Icon 元件。
 
 ---

package/src/components/Avatar/avatar.stories.tsx

@@ -24,6 +24,8 @@ export const Modes = {
         </p>
       </div>
       <div className="flex items-center gap-6">
+        {/* 刻意示範內容模式優先序:Text fallback / 預設 User icon 兩項**必須**無 src(fallback 行為
+            示範 story,2026-07-08 demo 人像真實化 sweep 豁免保留) */}
         {[
           { label: 'Image', el: <Avatar size={40} src="https://i.pravatar.cc/80?u=a" alt="Alice" /> },
           { label: 'Icon', el: <Avatar size={40} icon={Building2} color="blue" /> },
@@ -95,13 +97,13 @@ export const InContext = {
         <div className="flex flex-col gap-2">
           <span className="text-caption font-medium text-fg-secondary">無 description（inline）</span>
           <div className="w-[280px] border border-divider rounded-lg py-1 bg-surface">
-            <MenuItem avatar={{ src: "https://i.pravatar.cc/48?u=a1", alt: "Alice" }}>
+            <MenuItem avatar={{ src: "https://i.pravatar.cc/48?u=alice-chen", alt: "Alice" }}>
               Alice Chen
             </MenuItem>
-            <MenuItem avatar={{ alt: "Bob", color: "blue" }}>
+            <MenuItem avatar={{ src: "https://i.pravatar.cc/48?u=bob-wang", alt: "Bob", color: "blue" }}>
               Bob Wang
             </MenuItem>
-            <MenuItem avatar={{ alt: "Carol", color: "purple" }}>
+            <MenuItem avatar={{ src: "https://i.pravatar.cc/48?u=carol-lee", alt: "Carol", color: "purple" }}>
               Carol Lee
             </MenuItem>
           </div>
@@ -110,19 +112,19 @@ export const InContext = {
           <span className="text-caption font-medium text-fg-secondary">有 description（block）</span>
           <div className="w-[320px] border border-divider rounded-lg py-1 bg-surface">
             <MenuItem
-              avatar={{ src: "https://i.pravatar.cc/64?u=a2", alt: "Alice" }}
+              avatar={{ src: "https://i.pravatar.cc/64?u=alice-chen", alt: "Alice" }}
               description="前端工程師"
             >
               Alice Chen
             </MenuItem>
             <MenuItem
-              avatar={{ alt: "Carol", color: "magenta" }}
+              avatar={{ src: "https://i.pravatar.cc/64?u=carol-lee", alt: "Carol", color: "magenta" }}
               description="產品設計師"
             >
               Carol Lee
             </MenuItem>
             <MenuItem
-              avatar={{ alt: "Dave", color: "turquoise" }}
+              avatar={{ src: "https://i.pravatar.cc/64?u=dave-lin", alt: "Dave", color: "turquoise" }}
               description="跨部門協作專案"
             >
               Dave Lin

package/src/components/Avatar/avatar.tsx

@@ -5,7 +5,7 @@ import type { LucideIcon } from 'lucide-react'
 import { cn } from '@/lib/utils'
 import { CAT_SUBTLE_TOKENS, CAT_SOLID_TOKENS, type CategoricalColor } from '@/design-system/tokens/categorical-color'
 import { HoverCard, HoverCardTrigger, HoverCardContent } from '@/design-system/components/HoverCard/hover-card'
-import { HOVER_DELAY_RICH_MS, HOVER_DELAY_CLOSE_MS } from '@/design-system/tokens/motion/motion'
+import { MOTION_DELAY_RICH_MS, MOTION_DELAY_CLOSE_MS } from '@/design-system/tokens/motion/motion'
 import { Badge } from '@/design-system/components/Badge/badge'
 import { useResolvedFieldDisabled, useTableIsScrolling } from '@/design-system/components/Field/field-context'
 
@@ -174,7 +174,10 @@ const AvatarInner = React.forwardRef<HTMLDivElement, AvatarProps>(
     const fontSizePx = Math.round(numSize * 0.5)
     const variantKey: VariantKey = solid ? 'solid' : 'subtle'
     const colors = COLOR_MAP[variantKey]?.[color] ?? COLOR_MAP.subtle.neutral
-    const radius = shape === 'circle' ? '9999px' : '4px'
+    // 2026-07-14 dim-20 修:inline style 不能用 rounded-* class,但可消費 radius token
+    // (radius.spec.md:18 canonical「所有 4px 圓角一律用 rounded-md」+ :86 禁硬寫值;
+    // token 改值 Avatar 跟隨 — M17 SSOT 傳播)。
+    const radius = shape === 'circle' ? 'var(--radius-full)' : 'var(--radius-md)'
 
     // 決定內容
     const showImage = src && !imgError
@@ -249,14 +252,19 @@ const AvatarInner = React.forwardRef<HTMLDivElement, AvatarProps>(
     // 是 ARIA 禁用組合(axe aria-prohibited-attr,serious;2026-07-06 拆 role="button" 後裸露)。
     // Avatar 語義本質 = 身份圖像 → `role="img"` 讓 aria-label 合法、子孫自動 presentational、
     // 且不對 AT 承諾任何互動行為 — 與「拆假承諾」拍板意圖一致(emoji span / MUI Avatar img alt 同款語義)。
+    // a11y:role="img" 讓子孫 presentational → 內層 Badge 的 count 語義被壓平,SR 讀不到。
+    // 解:badgeCount 併入外層 aria-label(對齊 Slack「單一 accessible name 含未讀數」做法)。
     const focusableProps = hoverCard
       ? {
           tabIndex: 0,
           role: 'img',
-          'aria-label': alt ?? 'View profile',
+          'aria-label':
+            typeof badgeCount === 'number' && badgeCount > 0
+              ? `${alt ?? 'View profile'}, ${badgeAriaLabel ?? `${badgeCount} unread`}`
+              : (alt ?? 'View profile'),
         }
       : {}
-    // 2026-05-31:focus ring 圓角跟隨 shape(circle→rounded-full / square→rounded-md,對齊 body 的 `radius` 變數 '9999px'/'4px'),
+    // 2026-05-31:focus ring 圓角跟隨 shape(circle→rounded-full / square→rounded-md,對齊 body 的 `radius` 變數 var(--radius-full)/var(--radius-md)),
     // 原寫死 rounded-full 會讓方形 avatar(實體)配 hoverCard 時出現圓形 ring。hoverCard 為通用行為(任意內容),
     // 方形 avatar 合法可配(內容非 ProfileCard 而已),故 ring 必跟形狀。
     const focusableClass = hoverCard
@@ -312,7 +320,7 @@ const AvatarInner = React.forwardRef<HTMLDivElement, AvatarProps>(
     if (!hoverCard || isTableScrolling) return baseEl
 
     return (
-      <HoverCard openDelay={HOVER_DELAY_RICH_MS} closeDelay={HOVER_DELAY_CLOSE_MS}>
+      <HoverCard openDelay={MOTION_DELAY_RICH_MS} closeDelay={MOTION_DELAY_CLOSE_MS}>
         <HoverCardTrigger asChild>
           {baseEl}
         </HoverCardTrigger>

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

@@ -85,7 +85,7 @@ export const UsageGuidance: Story = {
             size="sm"
             iconOnly
             startIcon={MessageSquare}
-            aria-label="訊息 (150+)"
+            aria-label="訊息 (150 則)"
             overlayBadge={<Badge count={150} max={99} variant="critical" />}
           />
           <Label>3 vs 42 vs 99+ 觸發不同 urgency 感</Label>

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

@@ -189,6 +189,8 @@ Badge count 模式的數字使用 `text-[10px]`（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 — 存在性指示
 
 **何時用**：「有東西」本身就是訊號，具體數量不重要或無意義。

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

@@ -48,8 +48,10 @@ export const Dot: Story = {
   name: '圓點模式',
   render: () => (
     <div className="flex items-center gap-4">
-      <Badge dot variant="critical" />
-      <Badge dot variant="high" />
+      {/* dot 無文字 → 必帶 aria-label(badge.spec.md 禁止事項:「dot 模式不帶 aria-label——
+          無文字的 dot 對 screen reader 完全不存在」) */}
+      <Badge dot variant="critical" aria-label="有緊急待處理事項" />
+      <Badge dot variant="high" aria-label="有新通知" />
       <span className="text-caption text-fg-muted">6×6px attention 點 —— 只 critical / high(單一注意點,不分 medium/low)</span>
     </div>
   ),

package/src/components/Breadcrumb/breadcrumb.principles.stories.tsx

@@ -274,11 +274,13 @@ export const LongPathRule: Story = {
 
       <Rule
         title="❌ 不折疊、讓長路徑橫向撐破版面"
-        note="窄容器或 mobile 上完整路徑會換行或被截斷,體驗比中段折疊還糟。折疊是主動的資訊階層處理"
+        note="Breadcrumb 單行不換行(flex-nowrap),窄容器或 mobile 上完整路徑會溢出邊界、被裁切或逼出橫向捲動,體驗比中段折疊還糟。折疊是主動的資訊階層處理"
       >
-        <div className="max-w-sm border border-border rounded-md p-3">
+        {/* maxItems={99} 停用 auto-collapse:負例要示範「不折疊」時六層真的撐破窄容器。
+            若用預設 maxItems=4,compositionalContent 會把中段折成 ⋯,反而變成正例 → demo 失效。 */}
+        <div className="max-w-sm border border-border rounded-md p-3 overflow-x-auto">
           <Breadcrumb>
-            <BreadcrumbList>
+            <BreadcrumbList maxItems={99}>
               <BreadcrumbItem><BreadcrumbLink href="#">組織</BreadcrumbLink></BreadcrumbItem>
               <BreadcrumbSeparator />
               <BreadcrumbItem><BreadcrumbLink href="#">部門</BreadcrumbLink></BreadcrumbItem>
@@ -293,7 +295,7 @@ export const LongPathRule: Story = {
             </BreadcrumbList>
           </Breadcrumb>
         </div>
-        <Label warn>↑ 窄容器塞不下六層,折斷到第二行或超出,不如折疊中段</Label>
+        <Label warn>↑ 窄容器塞不下六層,單行溢出邊界(需橫向捲動才看得完),不如折疊中段</Label>
       </Rule>
     </div>
   ),

package/src/components/Breadcrumb/breadcrumb.stories.tsx

@@ -56,12 +56,13 @@ export const InteractiveEllipsis: Story = {
   name: '可互動省略',
   render: () => (
     <div className="flex flex-col gap-4">
+      {/* 內部實作(對 consumer 不可見):BreadcrumbEllipsis 永遠 render <button> + DropdownMenuTrigger
+          asChild 注入 dropdown 行為;hover 走 neutral(fg-muted → foreground + neutral hover bg,消費
+          ItemInlineActionButton),刻意與 BreadcrumbLink 的 primary-hover 語言區隔。 */}
       <div className="text-caption text-fg-muted max-w-xl">
-        BreadcrumbEllipsis 永遠是 <code>&lt;button&gt;</code>,搭配
-        <code> DropdownMenuTrigger asChild </code>把 dropdown 行為注入。
-        點擊 <code>⋯</code> 開選單顯示折疊路徑;hover 走 neutral(fg-muted → foreground
-        + neutral hover bg,消費 ItemInlineActionButton),與 BreadcrumbLink 的
-        primary-hover 區隔。對齊 Material / Atlassian / Ant Design 作法。
+        點 <code>⋯</code> 會開選單,列出被折疊起來的中間層級。滑鼠移上去時 <code>⋯</code> 用中性灰的高亮
+        (和一般連結的主色高亮刻意分開,讓「展開選單」和「跳到某一層」兩種動作一眼可辨),對齊 Material /
+        Atlassian / Ant Design 的做法。
       </div>
       <Breadcrumb>
         <BreadcrumbList>

package/src/components/Breadcrumb/breadcrumb.tsx

@@ -127,7 +127,8 @@ const BREADCRUMB_TEXT_CLASS: Record<BreadcrumbSize, string> = {
   lg: 'text-body-lg',
 }
 
-// Separator / ellipsis icon 尺寸 — 對齊 uiSize.spec.md「Icon Size Tier」(field-height-sm/md→16,lg→20)
+// Separator chevron + BreadcrumbLink/Item start icon 尺寸 — 對齊 uiSize.spec.md「Icon Size Tier」(field-height-sm/md→16,lg→20)。
+// 注意:BreadcrumbEllipsis 不消費此常數,固定 md(16px icon,見 BreadcrumbEllipsis 定義),size='lg' 時不隨 chevron 放大到 20
 // 2026-05-18 改 per user 拍板「A 先改 16/16/20」+「做完」approval:
 // 撤回 text-flow 例外設計,Breadcrumb chevron 跟其他 chrome icon 同 tier。
 // World-class 對齊:Atlassian Breadcrumb chevron 16 default / Material 3 / Ant Design 同。
@@ -598,7 +599,7 @@ export const breadcrumbMeta = {
 
   },
   sizes: {
-    // 值源 = code SSOT:BREADCRUMB_SIZE_TEXT(sm/md=text-body, lg=text-body-lg)+ BREADCRUMB_ICON_SIZE(sm/md=16, lg=20)。
+    // 值源 = code SSOT:BREADCRUMB_TEXT_CLASS(sm/md=text-body, lg=text-body-lg)+ BREADCRUMB_ICON_SIZE(sm/md=16, lg=20)。
     // Breadcrumb 是文字列無固定高度 token,故不列 height(對照 Tag meta 有自身 h-* 才列)。
     sm: { iconSize: 16, typography: 'body' },
     md: { iconSize: 16, typography: 'body' },

package/src/components/BulkActionBar/bulk-action-bar.spec.md

@@ -159,7 +159,9 @@ interface BulkActionBarLabels {
   count: (n: number) => string         // default 「已選 {n} 項」
   clear: string                         // default 「清除選取」(X aria-label)
   hiddenSuffix: (hidden: number) => string  // default 「· {hidden} 個被 filter 隱藏」
-  toolbarAriaLabel: string              // default 「批次操作」
+  ariaLabel?: string                    // root role="group" 的 aria-label(2026-07-06 新主 key;未傳 fallback toolbarAriaLabel)
+  /** @deprecated 2026-07-06 role 已降級 "group"(見 a11y 段),改用 ariaLabel;此 key 保留 backward-compat,值仍作 fallback。default 「批次操作」 */
+  toolbarAriaLabel: string
 }
 ```
 
@@ -177,7 +179,7 @@ interface BulkActionBarLabels {
 
 ## a11y 預設
 
-- BulkActionBar 整體用 `role="toolbar"` + `aria-label`(default `"批次操作"`,可 override)
+- BulkActionBar 整體用 `role="group"` + `aria-label`(default `"批次操作"`,由 `labels.ariaLabel ?? labels.toolbarAriaLabel` 決定,可 override)。**降級 rationale(2026-07-06 user 拍板)**:原宣告 `role="toolbar"` 但未實作 APG toolbar 方向鍵 roving 契約(AT 告知「工具列」但方向鍵無反應 = 空承諾);改 `role="group"` 語意誠實,Tab 序照 DOM(見下)。Gmail / Linear bulk bar 實務同款。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 - count 文字用 `aria-live="polite"` + `aria-atomic="true"`(selection 變更時 SR 整句重讀「已選 3 項」)
 - Clear button:`aria-label="清除選取"`
 - Hint banner 用 `role="status"` + `aria-live="polite"`(state 切換時通知)

package/src/components/Button/button.principles.stories.tsx

@@ -195,7 +195,7 @@ export const PrimaryRule: Story = {
         title="✅ 卡片清單 CTA 用 tertiary"
         note="重複出現的 CTA 應使用 tertiary，避免頁面充斥填滿按鈕，稀釋 primary 的信號強度"
       >
-        {['專案 A', '專案 B', '專案 C'].map(name => (
+        {['官網改版', '行動裝置 App', '設計系統'].map(name => (
           <div key={name} className="border border-border rounded-lg px-4 py-3 flex items-center gap-3 min-w-40">
             <span className="text-body flex-1">{name}</span>
             <Button variant="tertiary" size="xs">開啟</Button>

package/src/components/Button/button.spec.md

@@ -368,7 +368,7 @@ const ICON_ONLY_BASE = 'aspect-square p-0 min-w-0 gap-0'
 
 Button 自動加 **`data-unbounded="true"`** attribute 當 **`variant === 'text'` OR `dismiss === true`** 任一成立。這是 DS-wide 視覺邊界 marker,讓容器(如 SurfaceHeader)可用 CSS selector 對無視覺邊界 button 套 layout 調整。
 
-**實際應用**:`SurfaceHeader` / `SurfaceFooter` 內建 CSS rule(SSOT 在 `overlay-surface.tsx` `CHROME_UNBOUNDED_SLOT`,此處僅引述不重述完整公式):
+**實際應用**:`SurfaceHeader` 內建 CSS rule(SSOT 在 `overlay-surface.tsx` `CHROME_UNBOUNDED_SLOT`,此處僅引述不重述完整公式;`SurfaceFooter` 不套此 rule):
 ```css
 [&_[data-unbounded]]:my-[calc((var(--chrome-slot-h,calc(var(--font-body-lg-size)*1.5))-var(--field-height-sm))/2)]
 ```
@@ -413,7 +413,7 @@ Button 自動加 **`data-unbounded="true"`** attribute 當 **`variant === 'text'
 - ❌ `startIcon` 不得放超過一個
 - ❌ `link` variant 不得嵌入段落文字——用 HTML `<a>` 代替
 - ❌ 不得直接使用 `variant="destructive"` 或 `variant="ghost"`——shadcn 內部 alias，僅供框架元件使用
-- ❌ `danger` 僅支援 `primary`、`secondary`、`text`——`tertiary` + danger 與 secondary 視覺完全相同（冗餘），`link` + danger 語義矛盾（連結暗示導覽，非破壞）
+- ❌ `danger` 僅支援 `primary`、`secondary`、`text`——`tertiary` + danger 無對應 compoundVariant,會靜默渲染成一般 tertiary（灰、無紅色 danger 視覺,並非等同 secondary),`link` + danger 語義矛盾（連結暗示導覽，非破壞）
 - ❌ `pressed` 不得用於多選一——應使用 Segmented Control
 - ❌ `pressed` 不得套用於 `primary` / `link`——主要操作不應 toggle、link 語意為導覽
 - ❌ `iconOnly` 不可與 `endIcon` 或 `badge` 並用——會破壞正方形結構

package/src/components/Button/button.tsx

@@ -396,6 +396,17 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
 
     const resolvedDanger = dangerProp || (variantProp as string) === 'destructive'
 
+    // Dev-mode warning:danger 僅 primary / secondary / text 有 compoundVariant。
+    // tertiary / link + danger 無匹配 compound → **靜默渲染成一般 tertiary / link**(灰、無紅色
+    // danger 視覺)— consumer 可能出「不紅的刪除鍵」而不自知。Spec SSOT:button.spec.md
+    // 「禁止事項」danger 條(2026-07-14 deep-audit 補 warn,對齊既有 overlayBadge / iconOnly warn pattern)。
+    if (process.env.NODE_ENV !== 'production' && resolvedDanger && (resolvedVariant === 'tertiary' || resolvedVariant === 'link')) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[DS Button] \`danger\` 不支援 variant="${resolvedVariant}"(無對應 compoundVariant,會靜默渲染成一般 ${resolvedVariant},無紅色 danger 視覺)。危險操作請改用 primary(立即不可逆)/ secondary(可反悔)/ text(低度)。SSOT:button.spec.md「禁止事項」danger 條。`
+      )
+    }
+
     // ButtonGroup context：vertical group 自動注入 fullWidth
     const groupCtx = React.useContext(ButtonGroupContext)
     const resolvedFullWidth = fullWidth || !!groupCtx.fullWidth
@@ -561,11 +572,15 @@ export const buttonMeta = {
     lg: { fieldHeight: 36, iconSize: 20, typography: 'body-lg' },
   },
   // 'pressed' = toggle on 持續態(data-[state=on],emphasis 淡藍底/neutral 灰底;2026-07-07 meta 詞彙統一補列)
-  states: ['default', 'hover', 'active', 'pressed', 'focus-visible', 'disabled'],
+  // 'loading' = CircularProgress spinner 取代 startIcon + aria-busy + click guard(2026-07-14 deep-audit
+  // 補列,原漏 → auto-compile 生成矩陣缺 loading;對齊 anatomy StateBehavior Loading 行 + tsx loading 分支)
+  states: ['default', 'hover', 'active', 'pressed', 'loading', 'focus-visible', 'disabled'],
   tokens: {
     // 2026-07-04 audit 補齊:原只列 primary variant 家族;按 buttonVariants cva 真實 class 補
-    // secondary/tertiary/text/link/danger 消費的 token(auto-compile token 矩陣依此)
-    bg: ['--primary', '--primary-hover', '--primary-active', '--primary-subtle', '--bg-disabled', '--surface', '--neutral-hover', '--neutral-active', '--neutral-selected'],
+    // secondary/tertiary/text/link/danger 消費的 token(auto-compile token 矩陣依此)。
+    // 2026-07-14 deep-audit 二次補齊(掃 cva 全 bg-* class):+ neutral-selected-hover / neutral-selected-active
+    // (neutral pressedTone compound 消費)+ error / error-hover / error-active(primary+danger bg-error 系)
+    bg: ['--primary', '--primary-hover', '--primary-active', '--primary-subtle', '--bg-disabled', '--surface', '--neutral-hover', '--neutral-active', '--neutral-selected', '--neutral-selected-hover', '--neutral-selected-active', '--error', '--error-hover', '--error-active'],
     fg: ['--on-emphasis', '--fg-disabled', '--foreground', '--primary', '--error', '--error-hover', '--error-active'],
     ring: ['--ring'],
   },