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

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

@@ -22,7 +22,8 @@ import * as AspectRatioPrimitive from '@radix-ui/react-aspect-ratio'
  * Consumer 傳 `ratio={n/m}` 數字計算(如 16/9 = 1.7777)。
  *
  * ── 常見消費者 ──
- * Coachmark media / Carousel item image / Card thumbnail(未來)/ Chart preview
+ * Coachmark media(coachmark.tsx)/ FileViewer 圖片預覽(file-viewer.tsx)/ Carousel item image、Card thumbnail(未來)
+ *(Chart 現用 raw aspect-video 非消費者 — 2026-07-04 grep 驗證)
  */
 
 export type AspectRatioProps = React.ComponentPropsWithoutRef<typeof AspectRatioPrimitive.Root>
@@ -47,7 +48,7 @@ export const aspectRatioMeta = {
   sizes: {
 
   },
-  // 2026-06-05 fix(deep-audit):純 structural container,無互動狀態(spec.md L101「無 hover/focus/active/disabled」)。
+  // 2026-06-05 fix(deep-audit):純 structural container,無互動狀態(spec「為何無 ColorMatrix / SizeMatrix / StateBehavior」段;段名指法免行號漂移)。
   // 原 ['default','hover','active','focus-visible','disabled'] 是 Phase 1 mechanical placeholder,與 spec 矛盾。
   states: ['default'],
   tokens: {

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

@@ -32,7 +32,7 @@ const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }
 
 const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
   <section className="mb-12">
-    <h2 className="text-heading-3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
+    <h2 className="text-h3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
     {children}
   </section>
 )

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

@@ -71,51 +71,31 @@ Avatar 是視覺身份標識——代表一個人、一個實體（專案、組
 hover ProfileCard 是 preview,所有 preview 必提供「看完整資料」的路徑。
 缺 `onViewMore` 使用者點不到完整 profile → hover 成單向死路。對齊 Slack / Linear / Notion / Figma / Gmail hover-profile popover 必有 "View profile" link 的世界級 pattern。詳 `../ProfileCard/profile-card.spec.md`「View more」canonical。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
-**適用範圍(ALL person avatars,無例外)**:
-- PeoplePicker tag / table cell 頭像 / sidebar user / comment author / avatar 堆疊
-- Dialog / Sheet body 的 member list
-- FileItem rich 的 author avatar
-- Menu / Dropdown 的 assignee / owner
-- Chat / thread / notification 頭像
-
-**世界級對照**(hover → profile 是 default,不是 opt-in):
-- Slack:hover user avatar → profile popover(default)
-- Figma:hover member avatar → profile card(default)
-- Linear:hover assignee avatar → user card(default)
-- Notion:hover person tag → user card(default)
-- GitHub:hover username + avatar → user hover card(default)
+**適用範圍(ALL person avatars,無例外)**:PeoplePicker tag / table cell 頭像 / sidebar user / comment author / avatar 堆疊 / Dialog·Sheet member list / FileItem rich author / Menu·Dropdown assignee·owner / chat·thread·notification 頭像。
+
+**世界級對照**(hover → profile 是 default,不是 opt-in):Slack / Figma / Linear / Notion / GitHub —— hover person avatar(或 username)→ profile popover / user card,全部 default 行為。
 
 **例外(ProfileCard 不適用,但 hoverCard 通用行為仍可用)**:
 - Entity avatar(專案 / 組織 logo / app icon)— 不代表人員,**不自動套 ProfileCard**(ProfileCard 是人專用內容模板:64px 圓形 + presence 狀態 + Chat/通話 動作,實體沒有)。但 `hoverCard` prop 本身是**通用行為**(型別 `React.ReactNode`,avatar.tsx `AvatarProps.hoverCard`),entity / square avatar **仍可配 hoverCard 顯示其他內容**(如實體資訊卡);此時 focus ring 自動跟隨 square 形狀(rounded-md)。未來若需實體資訊卡,做成**平行的內容元件**(對齊 Atlassian `ProfileCard` / `TeamProfileCard` 分離 + GitHub `data-hovercard-type` 各 type 獨立內容),**不泛化 ProfileCard**。
 - Bot / automated account avatar(Atlas / Octocat 等)— 本 DS 後續視需求決
 
-**為什麼必 default**:
-- Person avatar 單獨無 context(只有照片 + 首字),user 不知是誰(世界級對照詳上方清單)
-- Opt-in 模式會讓一半的 consumer 忘記加,DS 品質不可控
-
-**違規檢測(M10 proactive scan)**:
-`grep '<Avatar.*alt=\{'` 全 src,檢查有無 person name(非 entity)alt 且沒 `hoverCard` prop。
-未來會加 hook `check_avatar_hovercard.sh` 自動攔截。
+**為什麼必 default**:Person avatar 單獨無 context(只有照片 + 首字),user 不知是誰;opt-in 模式會讓一半 consumer 忘記加,DS 品質不可控。**違規檢測(M10 proactive scan)**:`grep '<Avatar.*alt=\{'` 全 src,檢查 person name(非 entity)alt 且沒 `hoverCard` prop 者;目前無專用 hook,靠 grep 掃描。
 
 **Keyboard 可達 canonical(2026-04-22 D4 UX audit 補齊)**:
 當 Avatar 有 `hoverCard` prop,Avatar wrapper **必 keyboard focusable**,讓 keyboard-only user 也能 reach ProfileCard popover。Avatar 元件內部自動套:
-- `tabIndex=0`(可 Tab 到)
-- `role="button"` + `aria-haspopup="dialog"`(告訴 AT 這是可觸發 popover)
+- `tabIndex=0`(可 Tab 到;focus 時 Radix hover-card 自動開卡)
+- `role="img"` + `aria-label`(取 `alt`)——2026-07-07 CI axe 補修:aria-label 掛在無 role 的 generic `<div>` 是 ARIA 禁用組合(axe `aria-prohibited-attr`,serious);Avatar 語義本質 = 身份圖像,`role="img"` 讓命名合法、子孫自動 presentational、不對 AT 承諾任何互動行為
 - `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1`(keyboard focus 視覺 indicator)
+- **不掛 `role="button"` / `aria-haspopup`**(2026-07-06 user 拍板拆除):原本宣告了卻無 Enter/Space 行為、無 `aria-expanded` = 對 AT 的空承諾(D4 finding);對齊 Radix hover-card 官方(刻意零 popup ARIA,定位 sighted-user 輔助)+ GitHub hovercard(trigger 無 popup ARIA)
 - 若無 `hoverCard` → 純展示 `<div>` 不 focusable(避免 tabTrap 噪音)
 
-Rationale:Radix `HoverCardTrigger asChild` 不自動加 tabIndex 給 non-focusable child。若 Avatar wrapper 是 `<div>` 沒 tabIndex,keyboard user 無法 reach ProfileCard content,違反 WCAG 2.1.1(Keyboard)+ 4.1.2(Name, Role, Value)。此 canonical 確保 DS-wide 「person avatar → ProfileCard」同時對 keyboard / screen reader 可達。
+Rationale:Radix `HoverCardTrigger asChild` 不自動加 tabIndex 給 non-focusable child。若 Avatar wrapper 是 `<div>` 沒 tabIndex,keyboard user 無法 reach ProfileCard content,違反 WCAG 2.1.1(Keyboard)。此 canonical 確保 DS-wide「person avatar → ProfileCard」keyboard 可達,且 ARIA 只宣告真的有的行為。
 
 **Status dot a11y(2026-04-22 D4 UX audit 調整)**:Avatar status dot 內部 span 從原 `role="status"` + `aria-label="presence: online"` 改為 `aria-hidden`。Rationale:`role="status"` 是 live region,多 Avatars(member list / mention picker)會造成 SR 洪水噪音;presence 資訊應整合進 parent avatar 的 `aria-label`(world-class Slack / Teams / Discord 共通)— consumer 傳 `alt` 時自帶語意(e.g. `alt="Alan Chen (online)"`)。
 
 ### 溢出人員列表（+N）
 
-Avatar 堆疊的「+N」hover 也出 **HoverCard**（不是 Tooltip），因為：
-- 列表內的 person tag 需要 dismiss 功能（互動）
-- 每個 person tag hover 需要再出 name card（嵌套 HoverCard）
-- Tooltip 是非互動的，不支援上述需求
-
-架構：`+N → HoverCard（人員列表）→ 每個人名 → HoverCard（name card）`
+Avatar 堆疊的「+N」hover 也出 **HoverCard**（不是 Tooltip）——列表內 person tag 需要 dismiss 互動、每個 person tag hover 需再出 name card（嵌套 HoverCard），Tooltip 非互動不支援。架構：`+N → HoverCard（人員列表）→ 每個人名 → HoverCard（name card）`
 
 ### 純文字截斷 vs 人員頭像
 
@@ -264,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="button"` + `aria-haspopup="dialog"` + `focus-visible:ring-2`,確保 keyboard user 能 Tab 進入觸發 ProfileCard popover(詳「Keyboard 可達 canonical」段)。
+- **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」段)。
 - **Image alt 語意**:meaningful image(person photo / brand logo)用實質 `alt`;decorative-only(極少)走 `alt=""`,但 Avatar 本質是身份識別,decorative 用法應改用 Icon 元件。
 
 ---

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

@@ -41,7 +41,7 @@ export const Modes = {
 }
 
 /* @story-trait-rationale: Shapes / Colors / AllSizes retired 2026-05-17 per audit Dim 24 —
- *   anatomy.stories.tsx SizeMatrix(含 circle/square shape axis)+ ColorMatrix(9 hue × subtle/solid)
+ *   anatomy.stories.tsx SizeMatrix(含 circle/square shape axis)+ ColorMatrix(12 hue + neutral × subtle/solid)
  *   已 cover trait grids。展示層保留 typical real-product 情境(Modes / Fallback / Status / Count badge 等),
  *   避免跟 anatomy trait grid 重複。 */
 

package/src/components/Avatar/avatar.tsx

@@ -145,6 +145,16 @@ export interface AvatarProps extends React.HTMLAttributes<HTMLDivElement> {
 const AvatarInner = React.forwardRef<HTMLDivElement, AvatarProps>(
   ({ size = 32, shape = 'circle', src, alt, icon: Icon, color = 'neutral', solid = false, status, badgeCount, badgeAriaLabel, hoverCard, className, style, ...props }, ref) => {
     const [imgError, setImgError] = React.useState(false)
+    // 2026-07-05 D4:imgError 隨 src 變更 reset — 原 state 首次 onError 後永久 true,consumer 之後
+    // 換有效新 src(重傳頭像 / signed URL 刷新)時 showImage 永遠 false,<img> 不再掛載 → 新圖
+    // 永不嘗試載入、終身卡 initials fallback。React 官方 adjust-state-on-prop-change 寫法
+    //(render-time derived reset,較 useEffect 少一輪 render);對齊 Radix useImageLoadingStatus /
+    // MUI useLoaded 皆隨 src reset 的 canonical。
+    const [prevSrc, setPrevSrc] = React.useState(src)
+    if (prevSrc !== src) {
+      setPrevSrc(src)
+      setImgError(false)
+    }
     const documentTheme = useDocumentTheme()
     const isTableScrolling = useTableIsScrolling()
     // 2026-05-13 R3.5(per codex Q3 verdict + user 拍「想盡辦法 auto-handle prereq」):
@@ -227,16 +237,22 @@ const AvatarInner = React.forwardRef<HTMLDivElement, AvatarProps>(
     )
 
     const hasOverlay = status || typeof badgeCount === 'number'
-    // Keyboard access canonical(D4 UX audit 2026-04-22 finding):Avatar with `hoverCard`
-    // 需 keyboard 可達 — Radix `HoverCardTrigger asChild` 不自動加 tabIndex,non-focusable
-    // `<div>` 會讓 keyboard-only user 無法 reach ProfileCard popover(WCAG 2.1.1 / 4.1.2 違反)。
-    // 解:當 `hoverCard` 存在時,wrapper `<div>` 變 focusable(`tabIndex=0` + `role="button"` +
-    // `aria-haspopup="dialog"` + focus-visible ring)。若無 hoverCard 則維持純展示 `<div>`。
+    // Keyboard access canonical(D4 2026-04-22 finding;2026-07-06 user 拍板修正 ARIA 空承諾):
+    // Avatar with `hoverCard` 需 keyboard 可達 — Radix `HoverCardTrigger asChild` 不自動加
+    // tabIndex,non-focusable `<div>` 會讓 keyboard-only user 無法 reach popover(WCAG 2.1.1)。
+    // 解:`tabIndex=0` + `role="img"` + `aria-label` + focus ring(focus 時 Radix 自動開卡)。
+    // **不掛 `role="button"` / `aria-haspopup`**(2026-07-06 拆除):原本宣告了卻沒有
+    // Enter/Space 行為、沒有 aria-expanded = 對 AT 的空承諾;對齊 Radix hover-card 官方
+    // (刻意零 popup ARIA,hover card 定位 sighted-user 輔助)+ GitHub hovercard(trigger
+    // 純連結無 popup ARIA)。若無 hoverCard 則維持純展示 `<div>`。
+    // **`role="img"`(2026-07-07 CI axe 補修)**:aria-label 在無 role 的 generic `<div>` 上
+    // 是 ARIA 禁用組合(axe aria-prohibited-attr,serious;2026-07-06 拆 role="button" 後裸露)。
+    // Avatar 語義本質 = 身份圖像 → `role="img"` 讓 aria-label 合法、子孫自動 presentational、
+    // 且不對 AT 承諾任何互動行為 — 與「拆假承諾」拍板意圖一致(emoji span / MUI Avatar img alt 同款語義)。
     const focusableProps = hoverCard
       ? {
           tabIndex: 0,
-          role: 'button' as const,
-          'aria-haspopup': 'dialog' as const,
+          role: 'img',
           'aria-label': alt ?? 'View profile',
         }
       : {}
@@ -320,7 +336,6 @@ const AvatarInner = React.forwardRef<HTMLDivElement, AvatarProps>(
     )
   }
 )
-AvatarInner.displayName = 'AvatarInner'
 
 // ── AvatarData ─────────────────────────────────────────────────────────────
 // 資料型別，讓 consumer 傳資料而非 ReactNode。
@@ -336,8 +351,9 @@ export interface AvatarData {
   /**
    * Person avatar hover ProfileCard(DS-wide canonical,person avatar 預設必有,見 avatar.spec.md)。
    * Entity avatar(專案 / 組織 logo)不帶 → consumer 不傳 hoverCard 即豁免。
-   * 所有消費 AvatarData 的 primitive(MenuItem / DropdownMenu / SelectMenu / SelectionItem / ProfileCard)
-   * 需 forward 此 prop 到內部 <Avatar hoverCard={avatar.hoverCard} />。
+   * 消費 AvatarData 的 row primitive(MenuItem menu-item.tsx / SelectionItem selection-item.tsx,
+   * DropdownMenu / SelectMenu 經 MenuItem)需 forward 此 prop 到內部 <Avatar hoverCard={...} />。
+   * 例外:ProfileCard 內部 Avatar 不 forward(卡片本身就是 hover 目的地,nested hover-in-hover 不合理)。
    */
   hoverCard?: React.ReactNode
 }
@@ -347,12 +363,10 @@ export interface AvatarData {
 export const avatarMeta = {
   component: 'Avatar',
   family: null, // non-family composite / overlay / layout
-  variants: {
-
-  },
-  sizes: {
-
-  },
+  // 2026-07-04 audit 標記:Avatar 無 variant 軸、size 為任意 number(px,由 consumer context 決定
+  // — item-anatomy AVATAR_SIZE 查表 / ProfileCard 40 等),無 discrete tier → 兩欄留空為 intentional 非漏填
+  variants: {},
+  sizes: {},
   states: ['default', 'focus-visible', 'disabled'], // 2026-06-11 R2:本身無自有 hover/active(spec L279;hoverCard 互動屬 HoverCard),
   tokens: {
     bg: ['bg-surface-raised'],

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

@@ -25,8 +25,8 @@ const VARIANTS: VariantKey[] = ['critical', 'high', 'medium', 'low']
 type ColorSpec = { bg: string; text: string }
 
 const TOKEN_MAP: Record<VariantKey, ColorSpec> = {
-  critical: { bg: '--notification', text: 'white' },
-  high:     { bg: '--info',         text: 'white' },
+  critical: { bg: '--notification', text: '--on-emphasis' },
+  high:     { bg: '--info',         text: '--on-emphasis' },
   medium:   { bg: '--info-subtle',  text: '--info-text' },
   low:      { bg: '--secondary',    text: '--fg-muted' },
 }

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

@@ -167,13 +167,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 呼吸(字徑/圓徑比例過密)。對照世界級:Material Badge 10sp、Polaris Badge 字級小於 body、GitHub Counter 10-11px 都小於 body <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- **其他元件不得比照**: 若新元件覺得需要 `text-[10px]`,先問「真的不是 caption 12px 可以解決嗎」,99% 情境 caption 夠用;真有需求跟 Badge / OverflowIndicator 歸同一 micro-indicator family 討論
 
 ---
 
@@ -395,4 +395,5 @@ Badge 是**計數 / 狀態視覺指示器**,本身**非互動元件**:
 
 - `avatar.spec.md`
 - `button.spec.md`
+- `overflow-indicator.spec.md`
 - `tag.spec.md`

package/src/components/Badge/badge.tsx

@@ -77,8 +77,11 @@ const Badge = React.forwardRef<HTMLSpanElement, BadgeProps>(
   ({ variant, dot = false, count, max, className, role, ...props }, ref) => {
     // dot 預設 attention 色 = critical(非 cva 的 count default 'low');count 沿用 cva default 'low'。
     const effectiveVariant = variant ?? (dot ? 'critical' : 'low')
+    // 2026-07-05 D4 修(續 07-04 guard):count 模式 count == null → 整顆 return null 不渲染 —
+    // 原 guard 只擋文字,仍渲染 16px 空 pill + 空 role=status live region(Ant/Material 皆不渲染)。
+    if (!dot && count == null) return null
     const display = dot ? null : (
-      max != null && count != null && count > max ? `${max}+` : `${count}`
+      max != null && count! > max ? `${max}+` : `${count}`
     )
 
     // a11y(2026-04-25 axe aria-prohibited-attr fix):

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

@@ -36,7 +36,7 @@ export const Overview: Story = {
     <div className="flex flex-col gap-10">
       <div>
         <H3>Anatomy</H3>
-        <Desc>Breadcrumb 是純 HTML + Tailwind 元件(無 Radix primitive),基於 shadcn/ui Breadcrumb 結構橋接 DS token。使用 `&lt;nav aria-label="Breadcrumb"&gt;` 確保正確 a11y。</Desc>
+        <Desc>Breadcrumb 基於 shadcn/ui Breadcrumb 結構橋接 DS token,基礎結構為原生 HTML + Tailwind(asChild 用 Radix Slot;truncate Tooltip 與收合 DropdownMenu 消費 DS 內部元件)。使用 `&lt;nav aria-label="Breadcrumb"&gt;` 確保正確 a11y。</Desc>
         <Breadcrumb>
           <BreadcrumbList>
             <BreadcrumbItem>
@@ -439,7 +439,7 @@ export const CollapseMatrix: Story = {
             </BreadcrumbItem>
           </BreadcrumbList>
         </Breadcrumb>
-        <p className="text-footnote text-fg-muted mt-3">點 Ellipsis 按鈕(包在 DropdownMenuTrigger 內)以 DropdownMenu 展開中間層;BreadcrumbEllipsis 渲染的是完整可點擊按鈕(消費 ItemInlineActionButton,帶 aria-label / focus / hover bg)。declarative `items` 與 compositional 兩種用法都會自動接上 DropdownMenu 收合。</p>
+        <p className="text-footnote text-fg-muted mt-3">本 story 為靜態結構展示:手動 `&lt;BreadcrumbItem&gt;&lt;BreadcrumbEllipsis /&gt;` 只渲染 ⋯ 按鈕本身(消費 ItemInlineActionButton,帶 aria-label / focus / hover bg),未接 DropdownMenu — 此處點擊無展開行為。完整互動接線(Ellipsis 包在 DropdownMenuTrigger 內展開中間層)見展示層「可互動省略」story;declarative `items` 與 compositional 超過 `maxItems` 的自動收合路徑則由元件自動接上 DropdownMenu。</p>
       </div>
     </div>
   ),

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

@@ -244,16 +244,21 @@ export const LongPathRule: Story = {
               <BreadcrumbLink href="#">組織</BreadcrumbLink>
             </BreadcrumbItem>
             <BreadcrumbSeparator />
-            <DropdownMenu>
-              <DropdownMenuTrigger asChild>
-                <BreadcrumbEllipsis />
-              </DropdownMenuTrigger>
-              <DropdownMenuContent>
-                <DropdownMenuItem>部門</DropdownMenuItem>
-                <DropdownMenuItem>設計團隊</DropdownMenuItem>
-                <DropdownMenuItem>成員管理</DropdownMenuItem>
-              </DropdownMenuContent>
-            </DropdownMenu>
+            {/* 2026-07-04 修 broken demo:裸 DropdownMenu 會被 BreadcrumbList children filter 丟棄
+                (breadcrumb.tsx compositionalContent 只認 BreadcrumbItem)→ 包 BreadcrumbItem
+                (對齊 declarative 模式內部 ellipsis 作法) */}
+            <BreadcrumbItem>
+              <DropdownMenu>
+                <DropdownMenuTrigger asChild>
+                  <BreadcrumbEllipsis />
+                </DropdownMenuTrigger>
+                <DropdownMenuContent>
+                  <DropdownMenuItem>部門</DropdownMenuItem>
+                  <DropdownMenuItem>設計團隊</DropdownMenuItem>
+                  <DropdownMenuItem>成員管理</DropdownMenuItem>
+                </DropdownMenuContent>
+              </DropdownMenu>
+            </BreadcrumbItem>
             <BreadcrumbSeparator />
             <BreadcrumbItem>
               <BreadcrumbLink href="#">權限</BreadcrumbLink>

package/src/components/Breadcrumb/breadcrumb.spec.md

@@ -30,7 +30,7 @@ benchmark:
 ## 定位
 
 Breadcrumb 顯示「當前頁面在資訊階層中的位置」，同時提供快速回到上層的路徑導覽。
-基於 shadcn/ui Breadcrumb 結構（純 HTML + Tailwind，無 Radix primitive），橋接設計系統 token。
+基於 shadcn/ui Breadcrumb 結構（原生 nav / ol / li 語意 + Tailwind；`asChild` 多型渲染用 Radix Slot，truncate Tooltip 與 collapse DropdownMenu 消費 DS 內部 Radix-based 元件），橋接設計系統 token。
 
 **Breadcrumb 是「你在哪裡」的指示器，不是「你可以去哪裡」的選單**——反映當前路徑，不是全部可能路徑。
 
@@ -113,7 +113,7 @@ Breadcrumb 顯示「當前頁面在資訊階層中的位置」，同時提供快
 ## 對齊既有設計語言
 
 - **色彩三階層**（fg-secondary → foreground / primary-hover → fg-muted）跟 MenuItem / Tabs trigger / SegmentedControl 的三階層結構一致：**次要 → 主要（或 hover 強調） → 弱化**
-- **`primary-hover` 在 Breadcrumb 的用法是「互動時文字變藍」**，跟 Tabs underline / Chip border / SegmentedControl border 用 `primary-hover` 的 canonical 選中規則屬於同一個色彩語言（`primary-hover` = 互動高亮）
+- **`primary-hover` 在 Breadcrumb 的用法是「互動時文字變藍」**——屬於全系統「瞬時互動高亮」色彩語言（連結 hover 換色 canonical 同族，`primary-hover` = 瞬時態專用階）。注意與「持續選中」分軌：選中規則（Tabs underline / Chip / SegmentedControl selected）自 2026-07-06 拍板起用 primary **base**（semantic.css「選中狀態」段 SSOT）——瞬時弱、持續強
 - **分隔 icon 用 `ChevronRight`**（不用 `/` 字元）對齊 Button `endIcon` 的「方向指示」icon 選擇
 
 ---
@@ -177,6 +177,8 @@ Breadcrumb 顯示「當前頁面在資訊階層中的位置」，同時提供快
 | `ellipsis`(BreadcrumbEllipsis 包裝)| **0** | 永遠完整顯示 ⋯ |
 | `BreadcrumbSeparator` | **0** | 永遠完整(否則 path 視覺斷裂)|
 
+**Compositional 手動 ellipsis 注意**:compositional path 按位置自動分派 role(first=root / last=current / 其餘=middle,`breadcrumb.tsx` `cloneWithRole` 尊重顯式 role),手動 `<BreadcrumbItem><BreadcrumbEllipsis/></BreadcrumbItem>` 需顯式傳 `role="ellipsis"` 才拿到 shrink:0(否則按位置拿 middle / shrink:2);declarative `items` 與自動收合路徑由元件自動標 `role="ellipsis"`。
+
 **為何 flex-shrink hierarchy 不用 fixed max-width**:
 - 容器寬 / items 少 → 各 item 自然寬度,**不浪費剩餘空間**
 - 容器窄 / items 多 → 按 priority 縮(root 先 → middle → current 最後)
@@ -247,7 +249,7 @@ ColorMatrix 已建:展示 BreadcrumbLink / Page / Separator / Ellipsis 四種節
 
 ## A11y 預設
 
-**ARIA / Pattern**:純 HTML 結構元件(nav + ol + li + a/span),無第三方 primitive。a11y 來自原生 HTML 語意 — 外層 `<nav aria-label="Breadcrumb">`、當前頁 `<span role="link" aria-disabled="true" aria-current="page">`、分隔符 `aria-hidden`(不進無障礙樹)。對齊 [WAI-ARIA Breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/)。
+**ARIA / Pattern**:結構為原生 HTML(nav + ol + li + a/span),a11y 來自原生 HTML 語意(`asChild` 用 Radix Slot 只合併 prop、不管理焦點 / ARIA / 鍵盤;truncate Tooltip 與 collapse DropdownMenu 各自帶自身 a11y)— 外層 `<nav aria-label="Breadcrumb">`、當前頁 `<span role="link" aria-disabled="true" aria-current="page">`、分隔符 `aria-hidden`(不進無障礙樹)。對齊 [WAI-ARIA Breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/)。
 
 **為何當前頁加 `role="link" aria-disabled="true"`**:BreadcrumbPage 是「被 disable 的連結」— 把它標記成連結家族(`role="link"`)讓螢幕閱讀器把整條 breadcrumb 念成同一個連結序列,再以 `aria-disabled="true"` 告知不可操作(對齊 shadcn/ui Breadcrumb canonical `BreadcrumbPage`)。WAI-ARIA APG 允許 current 用 link + `aria-current`,shadcn 加 `aria-disabled` 是合理增強。
 

package/src/components/Breadcrumb/breadcrumb.tsx

@@ -205,8 +205,10 @@ const BreadcrumbList = React.forwardRef<HTMLOListElement, BreadcrumbListProps>(
     // Declarative mode(items prop provided):自動 render + auto-collapse
     const declarativeContent = React.useMemo(() => {
       if (!items) return null
-      const renderItem = (spec: BreadcrumbItemSpec, role: 'root' | 'middle' | 'current') => (
-        <BreadcrumbItem key={`${role}-${typeof spec.label === 'string' ? spec.label : Math.random()}`} role={role}>
+      // 2026-07-04 修:非字串 label 的 key 原用 Math.random() → 每次 render 新 key 造成
+      // BreadcrumbItem unmount/remount(重置 TruncatedLabel ResizeObserver 與 state)→ 改 stable idx key
+      const renderItem = (spec: BreadcrumbItemSpec, role: 'root' | 'middle' | 'current', idx: number) => (
+        <BreadcrumbItem key={`${role}-${typeof spec.label === 'string' ? spec.label : idx}`} role={role}>
           {role === 'current'
             ? <BreadcrumbPage startIcon={spec.startIcon}>
                 <TruncatedLabel fullText={typeof spec.label === 'string' ? spec.label : undefined}>{spec.label}</TruncatedLabel>
@@ -264,7 +266,7 @@ const BreadcrumbList = React.forwardRef<HTMLOListElement, BreadcrumbListProps>(
             </BreadcrumbItem>
           )
         } else {
-          rendered.push(renderItem(entry.spec, entry.role))
+          rendered.push(renderItem(entry.spec, entry.role, i))
         }
       })
       return rendered
@@ -596,7 +598,11 @@ 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)。
+    // Breadcrumb 是文字列無固定高度 token,故不列 height(對照 Tag meta 有自身 h-* 才列)。
+    sm: { iconSize: 16, typography: 'body' },
+    md: { iconSize: 16, typography: 'body' },
+    lg: { iconSize: 20, typography: 'body-lg' },
   },
   states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
   tokens: {

package/src/components/BulkActionBar/bulk-action-bar.anatomy.stories.tsx

@@ -54,7 +54,8 @@ export const Overview: Story = {
       <section>
         <H3>Selection state-driven 渲染(0 / N)</H3>
         <Desc>
-          <code>selection.length === 0</code> → null(不佔 layout)。<code>{`> 0`}</code> → 主 bar 浮現。
+          <code>selection.length === 0</code> 且無 <code>totalSelected</code> → null(不佔 layout);
+          有選取(含反向選取 <code>totalSelected {'>'} 0</code>,見 spec「Extend dataset pattern」)→ 主 bar 浮現。
           擴 dataset 的 hint banner 由 consumer 用 <code>Alert</code> 元件包在 BulkActionBar 上方/下方,
           不在 BulkActionBar 內部 hardcode(對齊 ref 圖)。
         </Desc>
@@ -185,7 +186,7 @@ export const Accessibility: Story = {
       <section>
         <H3>ARIA roles</H3>
         <ul className="list-disc list-inside text-caption text-fg-secondary space-y-1">
-          <li><code>role="toolbar"</code> on root + <code>aria-label="批次操作"</code>(可 i18n override)</li>
+          <li><code>role="group"</code> on root + <code>aria-label="批次操作"</code>(可 i18n override;2026-07-06 自 toolbar 降級——未實作 APG toolbar 方向鍵契約,group 語意誠實,Gmail / Linear 同款)</li>
           <li>Clear icon:<code>aria-label="清除選取"</code></li>
           <li>actions slot 內各 button 由 consumer 提供 aria-label / 文字</li>
           <li>Hint banner 用 Alert(自帶 <code>role="status"</code> + <code>aria-live="polite"</code>)</li>

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

@@ -17,9 +17,9 @@ benchmark:
 
 ## 定位
 
-選取多項 item(table row / list item)後浮現的批次操作列。**不獨立於選取狀態存在**——`selection.length === 0` 時隱藏,`> 0` 時浮現。
+選取多項 item(table row / list item)後浮現的批次操作列。**不獨立於選取狀態存在**——無選取時隱藏,有選取時浮現(完整判準含 `totalSelected` 反向選取例外,見「Extend dataset pattern」)。
 
-**Layout Family**:非 1-4 family — composite / multi-section(自 own layout,batch action 區 + count 區 + page-action 區 + hint banner)。
+**Layout Family**:非 1-4 family — composite / multi-section(自 own layout:clear 區 + count 區 + batch actions 區;**不含** page-level primary / hint banner,見下方同名段)。
 
 **世界級對照**:Linear bulk action toolbar / Polaris IndexTable bulk actions / Material DataGrid `<GridToolbar>` selection mode / Notion database row selection bar / Gmail / GitHub Issues 多選 toolbar。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
@@ -66,10 +66,10 @@ benchmark:
 ## 結構
 
 ```
-┌──────────────────────────────────────────────────────────────┐
-│ [✕] [{N} 已選 · M hidden by filter] │ [Action 1] [Action 2]   │
-│  ↑ clear  ↑ count + filter inline     ↑ batch actions(consumer)│
-└──────────────────────────────────────────────────────────────┘
+┌────────────────────────────────────────────────────────────────────┐
+│ [✕] [已選 {N} 項 · {M} 個被 filter 隱藏] │ [Action 1] [Action 2]   │
+│  ↑ clear  ↑ count + filter inline          ↑ batch actions(consumer)│
+└────────────────────────────────────────────────────────────────────┘
 ```
 
 - 全 md Buttons(`same-row consistency`,close X 同 size;rationale 見下方「Size canonical」)
@@ -82,7 +82,7 @@ benchmark:
 ### Slot
 
 - **`actions`**:consumer 提供 **md** Buttons(size rationale 見「Size canonical」);`variant=tertiary`(主)/ `tertiary danger`(destructive)— **不用 primary**(留 dialog 確認最終 action)
-- **count 區**:`{N} 已選`(內建)+ inline filter hidden status `· {M} 個被 filter 隱藏`(`hiddenByFilter` prop 傳入時)
+- **count 區**:`已選 {N} 項`(內建)+ inline filter hidden status `· {M} 個被 filter 隱藏`(`hiddenByFilter` prop 傳入時)
 - **clear**:`<Button iconOnly size=md variant=text dismiss />`(內建,觸發 `onClear`)
 
 #### Size canonical(2026-05-04 升 SSOT)
@@ -120,7 +120,7 @@ BulkActionBar 是 plain block(無 positioning 邏輯),consumer 用 flex column
 </div>
 ```
 
-**為什麼撤 top-replace**:Polaris IndexTable / Material DataGrid / GitHub / Gmail 等「替代 toolbar」做法在 selection 期間**喪失 filter / sort / search 功能**,user workflow 斷裂(「我選了 50 個再 filter 出 status=error 子集 batch action」這種常見 workflow 卡關)。本 DS 採 Linear / Notion / Apple Mail / iOS Files / Notion / Atlassian additive 派 — toolbar 永遠保留。
+**為什麼撤 top-replace**:Polaris IndexTable / Material DataGrid / GitHub / Gmail 等「替代 toolbar」做法在 selection 期間**喪失 filter / sort / search 功能**,user workflow 斷裂(「我選了 50 個再 filter 出 status=error 子集 batch action」這種常見 workflow 卡關)。本 DS 採 Linear / Notion / Apple Mail / iOS Files / Atlassian additive 派 — toolbar 永遠保留。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 ### Layout 行為(4 use case 全 covered by inline composition)
 
@@ -138,18 +138,19 @@ case 4 比較少見,consumer 知道自己 layout 時自加 wrapper 即可,DS pri
 ## API
 
 ```ts
-interface BulkActionBarProps {
-  /** 已選 ID,length === 0 時自動隱藏(回 null) */
+// extends HTMLAttributes:其餘 div 屬性(id / data-* / event handlers)spread 到 root
+interface BulkActionBarProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** 已選 ID;length === 0 且無 totalSelected 時自動隱藏(回 null,完整判準見「Extend dataset pattern」) */
   selection: readonly string[]
   /** Clear 觸發,user 點 X icon(consumer 在 page-level 監聽 Esc 觸發) */
   onClear?: () => void
   /** 批次 actions(consumer 提供 md Button,variant=tertiary 或 tertiary+danger,不用 primary) */
   actions?: React.ReactNode
-  /** Filter 模式:hidden 數量,顯示在 count 區 inline 「{N} 已選 · {M} 個被 filter 隱藏」 */
+  /** Filter 模式:hidden 數量,顯示在 count 區 inline 「已選 {N} 項 · {M} 個被 filter 隱藏」 */
   hiddenByFilter?: number
   /** 擴選整個 dataset 後的真總數;number 時 count 顯示此值,否則 fallback selection.length(見「Extend dataset pattern」) */
   totalSelected?: number | null
-  /** i18n labels(Partial,merge with default;對齊 Material localeText / Polaris i18n 慣例) */
+  /** i18n labels(Partial,merge with default;對齊 Material localeText / Polaris i18n 慣例 — @benchmark-unverified) */
   labels?: Partial<BulkActionBarLabels>
   className?: string
 }
@@ -168,7 +169,7 @@ interface BulkActionBarLabels {
 
 ### Extend dataset pattern(totalSelected)
 
-「本頁全選 → hint 點擊 → 擴選整個 dataset」2-step 後,consumer 把 `totalSelected` 設為 dataset 真總數,count 區改顯示該值(否則 fallback `selection.length`)——避免 Alert 顯「已選 5370」但 bar 仍顯「已選 50」的不同步(2026-05-13 ship)。對齊 Gmail / Linear / Notion 全選 dataset hint pattern。
+「本頁全選 → hint 點擊 → 擴選整個 dataset」2-step 後,consumer 把 `totalSelected` 設為 dataset 真總數,count 區改顯示該值(否則 fallback `selection.length`)——避免 Alert 顯「已選 5370」但 bar 仍顯「已選 50」的不同步(2026-05-13 ship)。對齊 Gmail / Linear / Notion 全選 dataset hint pattern。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 **可見性與反向選取(DataTable all 模式,2026-06-22)**:顯示判準 = `selection.length > 0 || (totalSelected ?? 0) > 0`。反向選取(`{ mode:'all', excluded }`)下若可見列全被 excluded、`selection`(可見代表)為空但 `totalSelected > 0`(全集仍有選取),bar **仍顯示**(否則「已選 N 個但 bar 消失」矛盾)。對應 `data-table.spec.md`「L2 選取」inverted 模型。
 
@@ -177,7 +178,7 @@ interface BulkActionBarLabels {
 ## a11y 預設
 
 - BulkActionBar 整體用 `role="toolbar"` + `aria-label`(default `"批次操作"`,可 override)
-- count 文字用 `aria-live="polite"` 通知 selection 變更(SR 讀「3 selected」)
+- count 文字用 `aria-live="polite"` + `aria-atomic="true"`(selection 變更時 SR 整句重讀「已選 3 項」)
 - Clear button:`aria-label="清除選取"`
 - Hint banner 用 `role="status"` + `aria-live="polite"`(state 切換時通知)
 - 鍵盤:Esc → `onClear()`(consumer 應監聽 page-level keydown 觸發);Tab 序按 DOM 順序 = clear(X)→ actions(count 是純文字 span,非互動元素 → 不參與 Tab)

package/src/components/BulkActionBar/bulk-action-bar.tsx

@@ -21,7 +21,10 @@ export interface BulkActionBarLabels {
   count: (n: number) => string
   clear: string
   hiddenSuffix: (hidden: number) => string
+  /** @deprecated 2026-07-06 role 已降級 "group"(user 拍板),改用 `ariaLabel`;此 key 保留 backward-compat(值仍作 fallback)。 */
   toolbarAriaLabel: string
+  /** root `role="group"` 的 aria-label(2026-07-06 新名;未傳 fallback toolbarAriaLabel)。 */
+  ariaLabel?: string
 }
 
 // code-quality-allow: dead-export — public API per spec.md(consumer spread + override)
@@ -41,7 +44,7 @@ export interface BulkActionBarProps extends React.HTMLAttributes<HTMLDivElement>
   onClear?: () => void
   /** 批次 actions(consumer 提供 md Button,variant=tertiary 或 tertiary+danger;不用 primary) */
   actions?: React.ReactNode
-  /** Filter 模式:hidden 數量,顯示在 count 區 inline「{N} 已選 · {M} 個被 filter 隱藏」 */
+  /** Filter 模式:hidden 數量,顯示在 count 區 inline「已選 {N} 項 · {M} 個被 filter 隱藏」 */
   hiddenByFilter?: number
   /**
    * 「擴選整個 dataset」狀態(2026-05-13 ship,per user 抓 Alert「已選 5370」但 BulkActionBar
@@ -89,8 +92,11 @@ const BulkActionBar = React.forwardRef<HTMLDivElement, BulkActionBarProps>(
     return (
       <div
         ref={ref}
-        role="toolbar"
-        aria-label={labels.toolbarAriaLabel}
+        // 2026-07-06 user 拍板:role "toolbar" → "group" — 原宣告 toolbar 但未實作 APG toolbar
+        // 方向鍵 roving 契約(AT 告知「工具列」但方向鍵無反應 = 空承諾);group 語意誠實,
+        // Tab 序照 DOM(spec 本有 canonical),Gmail / Linear bulk bar 實務同款。
+        role="group"
+        aria-label={labels.ariaLabel ?? labels.toolbarAriaLabel}
         className={cn(
           'flex items-center gap-2',
           'px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]',
@@ -120,7 +126,7 @@ const BulkActionBar = React.forwardRef<HTMLDivElement, BulkActionBarProps>(
             理由:count 是 state-bearing 主資訊(「你在 selection mode + N items」),非裝飾
             World-class 共識:Linear/Notion/Carbon/Polaris 均用 primary foreground;muted 化弱化 state signal
             hiddenByFilter suffix 維持 muted(這是次資訊,視覺層次正確) */}
-        {/* 2026-05-31 #3:aria-live 通知 SR 選取數變更;#20:補 font-medium 對齊 spec L90 + 上方 comment(state-bearing 主資訊) */}
+        {/* 2026-05-31 #3:aria-live 通知 SR 選取數變更;#20:補 font-medium 對齊 spec「Count text color canonical」表 + 上方 comment(state-bearing 主資訊) */}
         <span className="text-body text-foreground font-medium tabular-nums" aria-live="polite" aria-atomic="true">
           {/* 2026-05-13:totalSelected override 走 dataset 擴選後真總數,否則 fallback page-level selection.length */}
           {labels.count(typeof totalSelected === 'number' ? totalSelected : selection.length)}

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

@@ -26,9 +26,9 @@ const STATES: StateKey[] = ['default', 'hover', 'active', 'disabled']
 
 const TOKEN_MAP: Record<VariantKey, Record<StateKey, ColorSpec>> = {
   primary: {
-    default: { bg: '--primary', text: 'white', border: 'transparent' },
-    hover: { bg: '--primary-hover', text: 'white', border: 'transparent' },
-    active: { bg: '--primary-active', text: 'white', border: 'transparent' },
+    default: { bg: '--primary', text: '--on-emphasis', border: 'transparent' },
+    hover: { bg: '--primary-hover', text: '--on-emphasis', border: 'transparent' },
+    active: { bg: '--primary-active', text: '--on-emphasis', border: 'transparent' },
     disabled: { bg: '--bg-disabled', text: '--fg-disabled', border: 'transparent' },
   },
   secondary: {
@@ -59,9 +59,9 @@ const TOKEN_MAP: Record<VariantKey, Record<StateKey, ColorSpec>> = {
 
 const DANGER_MAP: Partial<Record<VariantKey, Record<StateKey, ColorSpec>>> = {
   primary: {
-    default: { bg: '--error', text: 'white', border: 'transparent' },
-    hover: { bg: '--error-hover', text: 'white', border: 'transparent' },
-    active: { bg: '--error-active', text: 'white', border: 'transparent' },
+    default: { bg: '--error', text: '--on-emphasis', border: 'transparent' },
+    hover: { bg: '--error-hover', text: '--on-emphasis', border: 'transparent' },
+    active: { bg: '--error-active', text: '--on-emphasis', border: 'transparent' },
     disabled: { bg: '--bg-disabled', text: '--fg-disabled', border: 'transparent' },
   },
   secondary: {

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

@@ -168,7 +168,7 @@ Tag md 和 Button xs 同 24px，但：
 
 - `startIcon`：最多一個，放在最左側
 - `badge` 和 `endIcon` 可同時出現在右側
-- `badge` 傳入 Badge 元件（通知計數指示器）。Badge 層級應匹配按鈕的視覺重量——深色底按鈕（primary、secondary+danger）只適合 `critical`，詳見 `badge.spec.md`
+- `badge` 傳入 Badge 元件（通知計數指示器）。Badge 層級受按鈕底色的 contrast floor 約束——深色底按鈕（primary、secondary+danger）floor 為 `high`（`high` / `critical` 可直接用；`low` / `medium` 被迫 bump 是設計錯配訊號），詳見 `badge.spec.md`「各容器的 contrast floor 對照」
 
 ---
 
@@ -362,7 +362,7 @@ const ICON_ONLY_BASE = 'aspect-square p-0 min-w-0 gap-0'
 - FileItem / DataTable **row delete(Trash icon)**→ 一般 Button xs 或 Inline Action(看 row size),**不套 dismiss**
 - Tag dismiss X / Input clear X → Inline Action(host chrome padding 內,不是 Button)
 
-完整 predicate 見 `patterns/element-anatomy/item-anatomy.spec.md`「Predicate」+「Dismiss canonical」。
+完整 predicate 見 `patterns/element-anatomy/inline-action.spec.md`「Predicate:Inline Action vs Button iconOnly」+「Dismiss canonical — X close only」（2026-04-24 自 item-anatomy.spec.md 抽出）。
 
 #### `data-unbounded` attribute(2026-04-22 v5 canonical)
 
@@ -456,6 +456,7 @@ N/A(action trigger,無資料層)。
 - `header-canonical.spec.md`
 - `item-anatomy.spec.md`
 - `overlay-surface.spec.md`
+- `pagination.spec.md`
 - `segmented-control.spec.md`
 - `switch.spec.md`
 - `tabs.spec.md`