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

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

@@ -0,0 +1,353 @@
+// @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 { Home } from 'lucide-react'
+import {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+} from './breadcrumb'
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+} from '@/design-system/components/DropdownMenu/dropdown-menu'
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/design-system/components/Tabs/tabs'
+import { Button } from '@/design-system/components/Button/button'
+
+const meta: Meta = {
+  title: 'Design System/Components/Breadcrumb/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+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>}
+    <div className="flex flex-col gap-3">{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 — 何時使用 Breadcrumb ──────────────────────
+
+// ── 最後一項 ────────────────────────────────────────────────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / VsTabsRule(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>Breadcrumb 顯示「目前頁面在資訊階層中的位置」,適合 ≥ 3 層的階層頁面。真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          電商多層分類、檔案管理器等深層頁面,路徑過長時中段折疊、點 ⋯ 可展開中間層 —— 見{' '}
+          <LinkTo kind="Design System/Components/Breadcrumb/展示" name="可互動省略"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">可互動省略</span></LinkTo>
+        </li>
+        <li>
+          路徑由路由 / CMS 資料動態產生,直接傳資料陣列、超過層數自動收合中段 —— 見{' '}
+          <LinkTo kind="Design System/Components/Breadcrumb/展示" name="宣告式 API + 自動收合"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">宣告式 API + 自動收合</span></LinkTo>
+        </li>
+        <li>
+          SPA 內點麵包屑要走前端路由、不整頁重載 —— 見{' '}
+          <LinkTo kind="Design System/Components/Breadcrumb/展示" name="整合 React Router / Next.js Link"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">整合 React Router / Next.js Link</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用相近的其他元件(見下方「跟相近元件怎麼分」的範例)。</p>
+    </div>
+
+      {/* vs 近親 — VsTabsRule — 原 VsTabsRule */}
+      <div>
+      <Rule
+        title="Breadcrumb — 「你在哪裡」的階層位置"
+        note="表達 parent-child 關係,使用者看 breadcrumb 知道「我從哪一層走到這裡」,點前面任一層可回到上層"
+      >
+        <div>
+          <Label>✅ 電商產品頁：顯示目前商品在分類樹的位置</Label>
+          <Breadcrumb>
+            <BreadcrumbList>
+              <BreadcrumbItem>
+                <BreadcrumbLink href="#">首頁</BreadcrumbLink>
+              </BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem>
+                <BreadcrumbLink href="#">家電</BreadcrumbLink>
+              </BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem>
+                <BreadcrumbLink href="#">手機</BreadcrumbLink>
+              </BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem>
+                <BreadcrumbPage>iPhone 15 Pro</BreadcrumbPage>
+              </BreadcrumbItem>
+            </BreadcrumbList>
+          </Breadcrumb>
+        </div>
+        <div>
+          <Label>✅ 文件系統：檔案深在多層資料夾裡</Label>
+          <Breadcrumb>
+            <BreadcrumbList>
+              <BreadcrumbItem>
+                <BreadcrumbLink href="#">我的雲端硬碟</BreadcrumbLink>
+              </BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem>
+                <BreadcrumbLink href="#">專案</BreadcrumbLink>
+              </BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem>
+                <BreadcrumbLink href="#">2026 Q2</BreadcrumbLink>
+              </BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem>
+                <BreadcrumbPage>產品規格書.pdf</BreadcrumbPage>
+              </BreadcrumbItem>
+            </BreadcrumbList>
+          </Breadcrumb>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ 用 Breadcrumb 做平行 view 切換 → 應該用 Tabs"
+        note="若三者是「同一層級的不同 view」(訂單 / 顧客 / 產品都是 dashboard 的不同頁),那是 Tabs。Breadcrumb 表達「上下層」,不是「並列切換」"
+      >
+        <div>
+          <Label>❌ 錯用：這三者是平行 view,沒有 parent-child 關係</Label>
+          <Breadcrumb>
+            <BreadcrumbList>
+              <BreadcrumbItem>
+                <BreadcrumbLink href="#">訂單</BreadcrumbLink>
+              </BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem>
+                <BreadcrumbLink href="#">顧客</BreadcrumbLink>
+              </BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem>
+                <BreadcrumbPage>產品</BreadcrumbPage>
+              </BreadcrumbItem>
+            </BreadcrumbList>
+          </Breadcrumb>
+          <Label warn>↑ 改用 Tabs</Label>
+          <Tabs defaultValue="products" className="mt-2">
+            <TabsList>
+              <TabsTrigger value="orders">訂單</TabsTrigger>
+              <TabsTrigger value="customers">顧客</TabsTrigger>
+              <TabsTrigger value="products">產品</TabsTrigger>
+            </TabsList>
+            <TabsContent value="orders" className="text-body text-fg-muted mt-2">訂單列表、篩選與批次出貨</TabsContent>
+            <TabsContent value="customers" className="text-body text-fg-muted mt-2">顧客名單、分群與生命週期價值</TabsContent>
+            <TabsContent value="products" className="text-body text-fg-muted mt-2">商品目錄、庫存與上下架狀態</TabsContent>
+          </Tabs>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ 單層頁面加 Breadcrumb"
+        note="只有一個 item 的 breadcrumb 沒導覽價值,只增加視覺噪音。單層頁面用 page title + 可選 back button 即可"
+      >
+        <Breadcrumb>
+          <BreadcrumbList>
+            <BreadcrumbItem>
+              <BreadcrumbPage>設定</BreadcrumbPage>
+            </BreadcrumbItem>
+          </BreadcrumbList>
+        </Breadcrumb>
+        <Label warn>↑ 只有一層,不需要 breadcrumb。直接用 page title</Label>
+      </Rule>
+    </div>
+    </div>
+  ),
+}
+
+export const LastItemRule: Story = {
+  name: '最後一項是位置標示，不是連結',
+  render: () => (
+    <div>
+      <Rule
+        title="最後一項用 BreadcrumbPage — 目前頁面,無處可點"
+        note="使用者已經在這一頁,點它去哪裡?世界級 DS(Material / Atlassian / Polaris)都把最後一項渲染成非互動文字。加上 aria-current='page' 給螢幕閱讀器"
+      >
+        <Breadcrumb>
+          <BreadcrumbList>
+            <BreadcrumbItem>
+              <BreadcrumbLink href="#">專案</BreadcrumbLink>
+            </BreadcrumbItem>
+            <BreadcrumbSeparator />
+            <BreadcrumbItem>
+              <BreadcrumbLink href="#">設計系統</BreadcrumbLink>
+            </BreadcrumbItem>
+            <BreadcrumbSeparator />
+            <BreadcrumbItem>
+              <BreadcrumbPage>元件庫（目前頁）</BreadcrumbPage>
+            </BreadcrumbItem>
+          </BreadcrumbList>
+        </Breadcrumb>
+        <Label>↑ 「元件庫」是目前頁,foreground 深色但不加粗、不可點</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 最後一項做成 link"
+        note="點下去會導回同一頁造成困惑。使用者預期點 link 會去新頁面,違反預期就是 broken UX"
+      >
+        <Breadcrumb>
+          <BreadcrumbList>
+            <BreadcrumbItem>
+              <BreadcrumbLink href="#">專案</BreadcrumbLink>
+            </BreadcrumbItem>
+            <BreadcrumbSeparator />
+            <BreadcrumbItem>
+              <BreadcrumbLink href="#">元件庫（錯：目前頁卻做成 link）</BreadcrumbLink>
+            </BreadcrumbItem>
+          </BreadcrumbList>
+        </Breadcrumb>
+        <Label warn>↑ 最後一項永遠是 BreadcrumbPage,不是 BreadcrumbLink</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+// ── 長路徑 ────────────────────────────────────────────────────────────────
+
+export const LongPathRule: Story = {
+  name: '長路徑中段折疊（保首尾）',
+  render: () => (
+    <div>
+      <Rule
+        title="> 4–5 層時中段折疊成 ⋯，首尾保留"
+        note="使用者關心「我從哪裡出發」(第一層)和「我在哪裡」(最後 1–2 層),中段是 context 可以摺疊。Ellipsis 可包在 DropdownMenu 讓使用者展開折疊的中間項"
+      >
+        <Breadcrumb>
+          <BreadcrumbList>
+            <BreadcrumbItem>
+              <BreadcrumbLink href="#">組織</BreadcrumbLink>
+            </BreadcrumbItem>
+            <BreadcrumbSeparator />
+            {/* 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>
+            </BreadcrumbItem>
+            <BreadcrumbSeparator />
+            <BreadcrumbItem>
+              <BreadcrumbPage>編輯角色</BreadcrumbPage>
+            </BreadcrumbItem>
+          </BreadcrumbList>
+        </Breadcrumb>
+        <Label>↑ 組織 › ⋯ › 權限 › 編輯角色(⋯ 可展開看中間項)</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 不折疊、讓長路徑橫向撐破版面"
+        note="Breadcrumb 單行不換行(flex-nowrap),窄容器或 mobile 上完整路徑會溢出邊界、被裁切或逼出橫向捲動,體驗比中段折疊還糟。折疊是主動的資訊階層處理"
+      >
+        {/* 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 maxItems={99}>
+              <BreadcrumbItem><BreadcrumbLink href="#">組織</BreadcrumbLink></BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem><BreadcrumbLink href="#">部門</BreadcrumbLink></BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem><BreadcrumbLink href="#">設計團隊</BreadcrumbLink></BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem><BreadcrumbLink href="#">成員管理</BreadcrumbLink></BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem><BreadcrumbLink href="#">權限</BreadcrumbLink></BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem><BreadcrumbPage>編輯角色</BreadcrumbPage></BreadcrumbItem>
+            </BreadcrumbList>
+          </Breadcrumb>
+        </div>
+        <Label warn>↑ 窄容器塞不下六層,單行溢出邊界(需橫向捲動才看得完),不如折疊中段</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+// ── 職責範圍 ──────────────────────────────────────────────────────────────
+
+export const ScopeRule: Story = {
+  name: '只放階層指示，不塞功能',
+  render: () => (
+    <div>
+      <Rule
+        title="Breadcrumb 可容納 icon 強化首項（如 Home）"
+        note="首項用 Home icon 是業界慣例(Material / Atlassian),視覺錨點明確。其他 item 通常純文字。圖示大小由設計系統統一控制(小 / 中尺寸 16px、大尺寸 20px),你只要用 `startIcon` 指定要哪個圖示,不用自己設大小。"
+      >
+        <Breadcrumb>
+          <BreadcrumbList>
+            <BreadcrumbItem>
+              <BreadcrumbLink href="#" startIcon={Home}>首頁</BreadcrumbLink>
+            </BreadcrumbItem>
+            <BreadcrumbSeparator />
+            <BreadcrumbItem>
+              <BreadcrumbLink href="#">設定</BreadcrumbLink>
+            </BreadcrumbItem>
+            <BreadcrumbSeparator />
+            <BreadcrumbItem>
+              <BreadcrumbPage>帳號</BreadcrumbPage>
+            </BreadcrumbItem>
+          </BreadcrumbList>
+        </Breadcrumb>
+      </Rule>
+
+      <Rule
+        title="❌ 把 Breadcrumb 當 nav bar，塞搜尋 / 按鈕 / avatar"
+        note="Breadcrumb 是「位置指示器」,不是 nav。塞功能會變成 nav bar,兩者職責混亂。頁面 header 的其他功能獨立擺放"
+      >
+        <div className="flex items-center gap-3 border border-border rounded-md p-3">
+          <Breadcrumb>
+            <BreadcrumbList>
+              <BreadcrumbItem><BreadcrumbLink href="#">專案</BreadcrumbLink></BreadcrumbItem>
+              <BreadcrumbSeparator />
+              <BreadcrumbItem><BreadcrumbPage>Design System</BreadcrumbPage></BreadcrumbItem>
+            </BreadcrumbList>
+          </Breadcrumb>
+          <Button variant="tertiary" size="sm">邀請成員</Button>
+          <Button variant="primary" size="sm">新增元件</Button>
+        </div>
+        <Label warn>↑ 按鈕應該放 page header / action bar,不塞進 breadcrumb</Label>
+      </Rule>
+    </div>
+  ),
+}

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

@@ -2,9 +2,19 @@
 component: Breadcrumb
 family: composite
 variants: {}
-sizes: {}
+sizes:
+  sm:
+    when: "Dialog / panel / drawer 內;text-body(14)+ icon 16,建議配 text-h4(20)title。對齊 BREADCRUMB_TEXT_CLASS.sm + BREADCRUMB_ICON_SIZE.sm(breadcrumb.tsx:124-136)"
+    world-class: ["Atlassian Breadcrumb", "Ant Design Breadcrumb"]
+  md:
+    when: "預設 — 一般頁面 header;text-body(14)+ icon 16,建議配 text-h3(24)title"
+    world-class: ["Ant Design Breadcrumb default", "MUI Breadcrumbs", "Polaris Breadcrumbs"]
+  lg:
+    when: "Detail page hero / landing;text-body-lg(16)+ icon 20,建議配 text-h2(32)title"
+    world-class: ["Carbon Breadcrumb", "Material 3 breadcrumb"]
 traits:
   - hasInteractiveStates
+  - hasSizes
   - isStructural
 benchmark:
   - Ant Design Breadcrumb: github.com/ant-design/ant-design/tree/master/components/breadcrumb
@@ -13,14 +23,13 @@ benchmark:
   - Carbon Breadcrumb: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Breadcrumb
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
 
 # Breadcrumb 設計原則
 
 ## 定位
 
 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 是「你在哪裡」的指示器，不是「你可以去哪裡」的選單**——反映當前路徑，不是全部可能路徑。
 
@@ -51,7 +60,7 @@ Breadcrumb 顯示「當前頁面在資訊階層中的位置」，同時提供快
 | **Sidebar nav** | Sidebar 是全局導覽 chrome;Breadcrumb 是 content header 內 inline path | 局部位置 anchor,不取代全局 nav |
 | **Link / page header** | Link 是單一導覽動作;Breadcrumb 是 parent-chain 完整路徑 | 路徑 ≥ 3 層需要可逐層回上 |
 
-對齊 Polaris Breadcrumbs / Material Breadcrumb / Atlassian Breadcrumbs 共識:nav inside page header,不取代 sidebar。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+Breadcrumb 是 page header 內的階層定位提示，不取代承載全域與跨區導覽的 sidebar。
 
 ---
 
@@ -63,12 +72,11 @@ Breadcrumb 顯示「當前頁面在資訊階層中的位置」，同時提供快
     <li>  BreadcrumbItem
       <a> BreadcrumbLink   ← clickable, 可回到上層
     </li>
-    <li>
-      <span> BreadcrumbSeparator (ChevronRight, aria-hidden)
+    <li role="presentation" aria-hidden="true"> BreadcrumbSeparator (ChevronRight)
     </li>
     ...
     <li>
-      <span> BreadcrumbPage  ← 當前頁面, 不可點, aria-current="page"
+      <span role="link" aria-disabled="true" aria-current="page"> BreadcrumbPage  ← 當前頁面, 不可點
     </li>
   </ol>
 </nav>
@@ -82,9 +90,9 @@ Breadcrumb 顯示「當前頁面在資訊階層中的位置」，同時提供快
 | `BreadcrumbList` | items 清單 | `<ol>` flex row |
 | `BreadcrumbItem` | 單一項目容器 | `<li>` |
 | `BreadcrumbLink` | 可點擊路徑項（非當前）| `<a>` 或 Slot（支援 `asChild` 給 router Link）|
-| `BreadcrumbPage` | 當前頁面（非 clickable）| `<span aria-current="page">` |
+| `BreadcrumbPage` | 當前頁面（非 clickable）| `<span role="link" aria-disabled="true" aria-current="page">` |
 | `BreadcrumbSeparator` | 項目間分隔 | `<li role="presentation">` + `ChevronRight` icon |
-| `BreadcrumbEllipsis` | 省略中間路徑的 `⋯` | `<span aria-hidden>` + `MoreHorizontal` |
+| `BreadcrumbEllipsis` | 省略中間路徑的 `⋯`（可點擊展開折疊路徑）| `<button type="button" aria-label="顯示折疊路徑">` + `MoreHorizontal`（消費 `ItemInlineActionButton` primitive，作為 DropdownMenuTrigger）|
 
 ---
 
@@ -93,18 +101,18 @@ Breadcrumb 顯示「當前頁面在資訊階層中的位置」，同時提供快
 | Slot | Token | 原因 |
 |---|---|---|
 | 基底字體 | `text-body` (14px) | navigation 尺度的標準 |
-| 間距（items 之間） | `gap-2` (8px) | 對齊 item-layout pattern 的 slot gap |
+| 間距（items 之間，含 separator）| `gap-1` (4px) | 緊湊節奏，符合 breadcrumb 密集流動感（`breadcrumb.tsx` BreadcrumbList `<ol>`）|
 | **`BreadcrumbLink`（可點擊）預設** | `text-fg-secondary` | neutral-8, 提示「可互動但非焦點」 |
 | **`BreadcrumbLink` hover** | **`text-primary-hover`** | 藍字 + `transition-colors duration-150`，明確回饋「點這個會有動作」 |
 | **`BreadcrumbPage`（當前）** | `text-foreground`（不加粗）| neutral-9 深色區分於 fg-secondary 的 links，但**不加粗**——加粗會讓 breadcrumb 最右端視覺過重，破壞「你從哪來 → 你在這」的流動感 |
-| **`BreadcrumbSeparator`** | `text-fg-muted` + `ChevronRight` size=`BREADCRUMB_ICON_SIZE[size]`(`breadcrumb.tsx:130` SSOT,sm/md=16, lg=20) | 視覺降噪,separator 不搶焦點;對齊 `uiSize.spec.md` Icon Size Tier(2026-05-18 retire 過去 14) |
-| **`BreadcrumbEllipsis`** | `text-fg-muted` + `MoreHorizontal` size=`BREADCRUMB_ICON_SIZE[size]` | 同 separator 層級 |
-| **`BreadcrumbLink` / `BreadcrumbPage` `startIcon`**(2026-05-20 ship)| `<Icon size={BREADCRUMB_ICON_SIZE[size]} aria-hidden />`(sm/md=16, lg=20)| 首項 Home icon 業界慣例(Material / Atlassian)。Consumer 只傳 `LucideIcon`,DS 統一管 size 消費 BREADCRUMB_ICON_SIZE SSOT — 對齊 `uiSize.spec.md` Icon Size Tier,**禁 consumer 傳 size prop**(避免再次 14 / 20 等寫死 drift)|
+| **`BreadcrumbSeparator`** | `text-fg-muted` + `ChevronRight`,尺寸消費 `BREADCRUMB_ICON_SIZE`(`breadcrumb.tsx` SSOT,對齊 `uiSize.spec.md` Icon Size Tier)| 視覺降噪,separator 不搶焦點 |
+| **`BreadcrumbEllipsis`** | `text-fg-muted` + `MoreHorizontal`,消費 `ItemInlineActionButton` 固定 `size="md"`(不隨 BreadcrumbList size 變化)| 尺寸 SSOT 在 `inline-action.spec.md` 尺寸表;固定 md 的理由詳 `breadcrumb.tsx` |
+| **`BreadcrumbLink` / `BreadcrumbPage` `startIcon`** | `<Icon size={BREADCRUMB_ICON_SIZE[size]} aria-hidden />` | 首項 Home icon 業界慣例(Material / Atlassian)。Consumer 只傳 `LucideIcon`,DS 統一管 size 消費 BREADCRUMB_ICON_SIZE SSOT — 對齊 `uiSize.spec.md` Icon Size Tier,**禁 consumer 傳 size prop**(避免寫死 drift)|
 
 ## 對齊既有設計語言
 
 - **色彩三階層**（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 選擇
 
 ---
@@ -128,7 +136,7 @@ Breadcrumb 顯示「當前頁面在資訊階層中的位置」，同時提供快
 
 ## Single-line + Overflow / 長路徑處理(2026-05-10 升級)
 
-**Single-line canonical**:BreadcrumbList 預設 `flex-nowrap`,**不 wrap 到下一行**。對齊 Material UI / GitHub / Notion / Linear / Atlassian 共識(WebFetch verified Material UI source `Breadcrumbs.js renderItemsBeforeAndAfter`)。路徑過長走中段折疊,非 multi-line wrap。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**Single-line canonical**:BreadcrumbList 預設 `flex-nowrap`,**不 wrap 到下一行**。路徑過長走中段折疊,非 multi-line wrap；如此保留單一由左至右的 ancestry scan path。
 
 當路徑層級太深(> 4–5 層)且容器寬度有限,world-class 作法是**中段折疊**:
 
@@ -141,7 +149,7 @@ Breadcrumb 顯示「當前頁面在資訊階層中的位置」，同時提供快
 - `<BreadcrumbEllipsis>` 消費 `ItemInlineActionButton` primitive(per inline-action.spec.md predicate + M1 SSOT 消費),`overlayTrigger=true` 內建 DropdownMenu open 視覺鎖
 - 包 `<DropdownMenuTrigger asChild>` 提供點 ⋯ 展開互動
 
-**v2 shipped Phase B**(2026-05-10):declarative `items` prop + `maxItems`(**default 4**,user-tuned;Material UI source 預設 8)+ `itemsBeforeCollapse`(default 1)+ `itemsAfterCollapse`(default 1)auto-collapse mode。對齊 Material UI source `Breadcrumbs.js renderItemsBeforeAndAfter` mechanism(2026-05-10 WebFetch verified)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**v2 shipped Phase B**(2026-05-10):declarative `items` prop + `maxItems`(**default 4**,user-tuned)+ `itemsBeforeCollapse`(default 1)+ `itemsAfterCollapse`(default 1)auto-collapse mode。Collapse 保留 root 與目前位置兩端，中段只透過 ellipsis 展開。
 
 ```tsx
 <BreadcrumbList
@@ -168,31 +176,28 @@ 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 自然寬度,**不浪費剩餘空間**(回應 user 質疑)
+- 容器寬 / items 少 → 各 item 自然寬度,**不浪費剩餘空間**
 - 容器窄 / items 多 → 按 priority 縮(root 先 → middle → current 最後)
 - 都縮到 `min-w-0` 後 CSS `truncate` 開啟 + Tooltip 補完整文字
-- Root **也會** truncate(shrink:3 縮最積極)— 不是 `shrink-0`(回應 user 質疑)
+- Root **也會** truncate(shrink:3 縮最積極)— 不是 `shrink-0`
 
-**Truncate-on-overflow + tooltip canonical**(per `tooltip.principles.stories.tsx:190`):
-- 每 BreadcrumbLink / BreadcrumbPage 內部 wrap `<TruncatedLabel>`(同 `data-table.tsx:339 TruncateCell` + `tag.tsx:138 isTruncated` SSOT pattern)
-- Shared ResizeObserver 偵測 `scrollWidth > clientWidth` → `<Tooltip>` wrap
-- 只在實際 truncate 時才顯 Tooltip(per tooltip canonical)— 沒被截斷不顯
-- **TODO**(Rule-of-3):breadcrumb / data-table / tag 三處同 idiom,future 抽 `patterns/element-anatomy/truncated-text.tsx` 共用 SSOT
-
-世界級對照:
-- **Material UI**:`maxItems=8` declarative auto-collapse(source verified,**no per-item width rule**)
-- Notion / Linear / GitHub / Atlassian per-item width 策略:**unverified**(WebFetch + web search 無法取得 source / docs)。本 DS 設計基於 DS internal SSOT(`TruncateCell` + `Tag truncate` + `Tooltip canonical`)+ first-principles flex-shrink hierarchy 回應 user 兩 challenges(root 也 truncate / 不浪費空間)。
+**Truncate-on-overflow + tooltip canonical**(消費 Tooltip「資訊補救」canonical,見 `tooltip.principles.stories.tsx`):
+- 每 BreadcrumbLink / BreadcrumbPage 內部 wrap `<TruncatedLabel>` — 與 DataTable `TruncateCell` / Tag truncate 同一 idiom(偵測機制詳 `breadcrumb.tsx`)
+- 只在實際 truncate 時才顯 Tooltip — 沒被截斷不顯
 
 世界級對照:
-- **Material UI**:`maxItems=8` + auto-collapse(declarative)
+- **Material UI**:`maxItems=8` declarative auto-collapse(source verified,no per-item width rule)
 - **Polaris**:點 ⋯ DropdownMenu 展開
 - **Atlassian**:中段 ⋯ + dropdown
 - **GitHub / Notion / Linear / Apple Finder**:auto truncate 中段
+- Per-item width(flex-shrink hierarchy)無世界級 source 可考(**unverified**)— 本 DS 自有設計,依據詳上方「為何 flex-shrink hierarchy 不用 fixed max-width」
 
 ## Title-breadcrumb-end 同步 canonical(2026-05-10 新增)
 
-**Breadcrumb 末位 `<BreadcrumbPage>` 文字 = page title `<h2>` / `<h3>` / `<h4>` 內容**。對齊 GitHub / Notion / Linear / Atlassian / Material UI examples 共識。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**Breadcrumb 末位 `<BreadcrumbPage>` 文字 = page title `<h2>` / `<h3>` / `<h4>` 內容**。兩處必共享同一頁面 identity，禁止同頁出現兩個互相矛盾的名稱。
 
 具體 pairing(per BreadcrumbList size):
 - `size="sm"` + 末位 `<BreadcrumbPage>X</BreadcrumbPage>` + `<h4>X</h4>` 同字
@@ -201,7 +206,17 @@ Breadcrumb 顯示「當前頁面在資訊階層中的位置」，同時提供快
 
 **為何同字重複**:breadcrumb 末位是 a11y 階層 navigation 階梯末端(`aria-current="page"`);title h2/h3/h4 是同字**視覺大字 emphasis**。兩者各司其職:小字 breadcrumb 提供路徑 context,大字 title 提供 page identity。同 SSOT 兩 view。
 
-**禁止**:breadcrumb 末位用 `BreadcrumbLink`(parent path)+ title 才顯示 current page = breadcrumb 末位 ≠ title 內容 = 違反 spec.md L142「最後一項必 BreadcrumbPage」+ 違反 world-class consensus。
+**禁止**:breadcrumb 末位用 `BreadcrumbLink`(parent path)+ title 才顯示 current page = breadcrumb 末位 ≠ title 內容 = 違反「禁止事項」段「最後一項不可是 `BreadcrumbLink`,必須用 `BreadcrumbPage`」+ 違反 world-class consensus。
+
+---
+
+## 邊界案例
+
+- **空值**:`items={[]}` 渲染空容器、空 label 渲染空節點(元件皆不 guard)— 單一層級本就禁用 Breadcrumb(見禁止事項),consumer 應條件性不渲染
+- **中段項無 `href`**:declarative mode 僅末位自動轉 `BreadcrumbPage`;中段項無 `href` 仍渲染 `BreadcrumbLink`(輸出無 `href` 的 `<a>`,不可 focus / 不可導覽)
+- **Loading / Error**:本元件無 loading / error state — 純 sync 展示元件;async 路徑載入時 consumer 以 Skeleton 取代整條(對齊 Steps 同類處理),路徑解析失敗的降級由 consumer own
+- **多語言長字串**:truncate 為 CSS 字元級裁切,不分語言(中英同規則),完整文字由 Tooltip 補(見 truncate canonical)
+- **RTL**:不支援；全域 LTR-only compatibility contract 見 `packages/design-system/README.md#compatibility-matrix`。separator / hierarchy 不在本檔另立支援決策。
 
 ---
 
@@ -209,19 +224,19 @@ Breadcrumb 顯示「當前頁面在資訊階層中的位置」，同時提供快
 
 - ❌ **不用 `/` 字元作分隔**——用 `ChevronRight` icon。`/` 是文字字元，跟文字對齊不穩、顏色綁 text、screen reader 會讀出「斜線」
 - ❌ **最後一項不可是 `BreadcrumbLink`**——最後一項代表當前頁，無處可點。必須用 `BreadcrumbPage`
-- ❌ **Breadcrumb 不做頁面切換動作的「back 按鈕」**——back 的語意是「上一步瀏覽歷史」不是「上一層階層」，兩者不同。Back 用 Button 或瀏覽器原生
-- ❌ **不得在 Breadcrumb 裡嵌入複雜互動元素**（dropdown、search、avatar picker）——breadcrumb 是「位置指示器」，塞功能會變 nav bar
+- ❌ **Breadcrumb 不做頁面切換動作的「back 按鈕」**——back 的語意是「上一步瀏覽歷史」不是「上一層階層」，兩者目的地可能不同（從搜尋結果直接進深層頁時，back 回搜尋結果＝歷史，breadcrumb 上一層回 parent＝階層）。Back 用 Button 或瀏覽器原生
+- ❌ **不得在 Breadcrumb 裡嵌入複雜互動元素**（dropdown、search、avatar picker）——使用者對 breadcrumb 的心智模型是「每個節點都是回上層的連結」，混入查詢 / 選擇功能會打斷路徑掃讀，breadcrumb 就變成 nav bar（`BreadcrumbEllipsis` 展開折疊路徑的選單屬路徑導覽本身、是本 spec 既定 canonical，非此禁令範圍——禁令指 consumer 自嵌的業務 dropdown / search）
 - ❌ **不得覆寫 `BreadcrumbLink` 的 hover 色彩**——`primary-hover` 是全系統的「互動高亮」canonical，覆寫破壞語言一致性
 - ❌ **不得把 Breadcrumb 拿來當 sidebar 或 top nav 替代**——breadcrumb 只顯示當前路徑，不展示 sibling 選項
 - ❌ **單一層級頁面不要放 Breadcrumb**——「首頁」一個 item 沒導覽價值，造成視覺噪音
 
 ---
 
-## 為何無 Inspector
+## anatomy story 結構
 
-Breadcrumb 決策維度是 collapse 策略 × size × 當前頁狀態,已在 `CollapseMatrix` / `SizeMatrix` / `ColorMatrix` / `StateBehavior` / 元件特有 `UsageExamples` 五張結構矩陣 + 真實場景完整覆蓋。互動 Inspector(切換 size / truncate)無法呈現「路徑深度 + 斷點」這類真實場景決策——`UsageExamples` 展示實際業務路徑更直接。
+互動 `Inspector`(切 `size` / `showHomeIcon` / `pathLength` / `maxItems` / collapse 設定,即時看路徑深度 × 折疊行為)搭配 `CollapseMatrix` / `SizeMatrix` / `ColorMatrix` / `StateBehavior` / 元件特有 `UsageExamples` 結構矩陣 + 真實場景,完整覆蓋 collapse 策略 × size × 當前頁狀態的決策維度。
 
-ColorMatrix 已建:展示 BreadcrumbLink / Page / Separator / Ellipsis 四種節點的 default / hover / focus 色彩矩陣,採 fg-muted → fg-secondary → foreground 的階層策略(對齊 GitHub / Notion / Linear)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+ColorMatrix 已建:展示 BreadcrumbLink / Page / Separator / Ellipsis 四種節點的 default / hover / focus 色彩矩陣,採 fg-muted → fg-secondary → foreground 的 DS 內部資訊階層。
 
 ---
 
@@ -233,14 +248,16 @@ ColorMatrix 已建:展示 BreadcrumbLink / Page / Separator / Ellipsis 四種節
 
 ## A11y 預設
 
-**ARIA / Pattern**:繼承 Radix `slot` primitive a11y 預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/slot#accessibility)。
+**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` 是合理增強。
 
 **Keyboard 行為**:
 
 - Tab — 逐個 link 導覽
 - Enter — navigate
 
-**Focus**:Radix primitive 自管 focus trap / restoration / visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。
+**Focus**:聚焦時顯示 visible ring;`BreadcrumbLink` 用 `focus-visible:ring-2 ring-ring ring-offset-1`（box-shadow ring，對齊全系統 focus-visible canonical，見上方「互動狀態」段），`BreadcrumbEllipsis` 按鈕（消費 `ItemInlineActionButton`）用 `focus-visible:outline-2 outline-ring`。連結逐個依序成為 tab stop,不攔截焦點(無 focus trap — breadcrumb 是序列式導覽,trap 反而是無障礙 bug)。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
@@ -248,10 +265,5 @@ ColorMatrix 已建:展示 BreadcrumbLink / Page / Separator / Ellipsis 四種節
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
-- `steps.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
 - `app-shell.spec.md`
+- `steps.spec.md`