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

package/src/components/Pagination/pagination.principles.stories.tsx

@@ -0,0 +1,81 @@
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Pagination } from './pagination'
+import { SegmentedControl, SegmentedControlItem } from '@/design-system/components/SegmentedControl/segmented-control'
+import { Button } from '@/design-system/components/Button/button'
+
+const meta: Meta = {
+  title: 'Design System/Components/Pagination/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers(同 Breadcrumb principles idiom) ──────────────────────────────────
+
+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>
+)
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(v3 canonical,Polaris/Material/Ant 共識)──
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => {
+    const [page, setPage] = React.useState(2)
+    const [view, setView] = React.useState('list')
+    return (
+      <div>
+        <Rule
+          title="何時用:大量資料切頁後的位置導覽"
+          note="使用者需要知道總頁數、且可能直接跳到某頁的順序瀏覽 —— 訂單列表、搜尋結果、SKU 目錄。表格情境優先用 <DataTable pagination> 內建(內部就是消費本元件),standalone 留給非 DataTable 的列表頁。"
+        >
+          <Pagination total={128} page={page} onPageChange={setPage} />
+          <Label>✓ 訂單管理列表底部:128 筆訂單 / 每頁 20 筆,置於列表下方、間距 tight</Label>
+        </Rule>
+
+        <Rule
+          title="何時不用:無盡瀏覽 feed → load-more / 虛擬滾動"
+          note="activity stream、通知列表這類「往下讀」的流,頁碼是錯的心智模型 —— 使用者不在乎第幾頁,只在乎更多內容。與虛擬滾動互斥:兩者是互斥的大資料策略(TanStack 官方定位),同一份資料不可同時用。"
+        >
+          <Button variant="secondary">載入更多通知</Button>
+          <Label>✓ feed 尾端用 load-more;超大資料集在 DataTable 內建虛擬滾動</Label>
+          <Label warn>✗ 給 activity feed 加頁碼 —— 讀流被切斷,回頭找內容也記不住頁碼</Label>
+        </Rule>
+
+        <Rule
+          title="vs SegmentedControl:位置導覽 ≠ 互斥選值"
+          note="兩者都是「多顆亮一顆」,語意完全不同:SegmentedControl 選項固定 2-5 個、每顆有語意(清單/看板/時間軸),恆有一值;Pagination 頁數動態、可摺疊、數字本身無語意,當前頁是「你在哪」不是「你選了什麼」。"
+        >
+          <SegmentedControl value={view} onValueChange={(v) => v && setView(v)} aria-label="檢視切換">
+            <SegmentedControlItem value="list">清單</SegmentedControlItem>
+            <SegmentedControlItem value="board">看板</SegmentedControlItem>
+            <SegmentedControlItem value="timeline">時間軸</SegmentedControlItem>
+          </SegmentedControl>
+          <Label>✓ 檢視切換用 SegmentedControl(互斥選值)</Label>
+          <Label warn>✗ 用 Pagination 做檢視切換,或用 SegmentedControl 排頁碼</Label>
+        </Rule>
+
+        <Rule
+          title="流程推進不是翻頁"
+          note="精靈流程「上一步 / 下一步」走 Steps(進度指示)+ Button(推進),不是頁碼 —— 頁碼可任意跳,流程有順序依賴;混用會讓使用者以為可以跳過必填步驟。"
+        >
+          <Label>✓ 註冊精靈 / 建立專案引導 → Steps + Button</Label>
+          <Label warn>✗ 精靈底部放 1 2 3 4 頁碼</Label>
+        </Rule>
+      </div>
+    )
+  },
+}

package/src/components/Pagination/pagination.spec.md

@@ -0,0 +1,150 @@
+---
+component: Pagination
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+  - isStructural
+benchmark:
+  - Ant Design Pagination: github.com/ant-design/ant-design/tree/master/components/pagination
+  - MUI Pagination: github.com/mui/material-ui/tree/master/packages/mui-material/src/Pagination
+  - Atlassian Pagination: atlassian.design/components/pagination
+  - shadcn Pagination: ui.shadcn.com/docs/components/pagination
+  - TanStack Table Pagination: tanstack.com/table/latest/docs/guide/pagination
+  - Carbon Pagination: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Pagination
+  - Polaris Pagination: polaris-react.shopify.com/components/navigation/pagination
+---
+
+# Pagination 設計原則
+
+## 定位
+
+Pagination 是「大量資料切成多頁後的位置導覽」——顯示當前頁、允許直接跳到任一頁。
+
+基於 shadcn/ui Pagination 的 DOM 骨架(`nav >(操作群 div)> ul > li` + 當前頁 `aria-current="page"`),但**按鈕消費 DS `Button`、事件驅動、資料模型 = `total`(總筆數)+ `pageSize`(Ant Pagination 同款,總頁數內部推導),非 shadcn 原生的 `<a href>` 連結型**——本 DS 服務 app 產品場景;需要 URL 同步時由 consumer 在 `onPageChange` 接 router,不是把按鈕換成連結。`page` / `pageSize` 皆 dual-mode(傳值 = controlled,不傳 = uncontrolled)。
+
+**本元件是分頁的完整功能 SSOT**(2026-07-06 user 拍板):頁碼、總筆數資訊(`showTotal`)、每頁筆數選單(`pageSizeOptions`)全部 own 在此——Ant(showTotal / showSizeChanger 內建於 Pagination)/ Carbon(page-size select 內建)/ MUI TablePagination(rows-per-page + range 內建)同派。DataTable 等 consumer **轉發 config 消費本元件**,不自拼分頁列。
+
+**Layout Family**:非 4-family — self-contained composite(nav 橫排 control row);個別按鈕消費 Family 3(Button Pill)。
+
+**樣式派系**(2026-07-05 user 拍板):數字頁碼派(上下頁箭頭 + 數字 + ellipsis 摺疊)——shadcn / MUI / Ant / Atlassian 同派;非 Polaris(純上下頁)/ Carbon(page Select 可跳頁 + 上下頁,無數字鈕列)派。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## 何時用
+
+- 資料表翻頁(**優先用 `<DataTable pagination>` 內建**,見下方分界)
+- server 分批載入的列表頁 / 搜尋結果頁(消費端自行 slice 或 server 端分頁)
+- 任何「使用者需要知道總頁數、且可能想直接跳到某頁」的順序瀏覽
+
+## 何時不用
+
+| 情境 | 改用 |
+|------|------|
+| 無盡瀏覽 feed(activity stream / 通知列表) | 虛擬滾動或 load-more,不是頁碼 |
+| 資料表且已用 `<DataTable>` | `<DataTable pagination>` 內建(不要自己在表格下手排 standalone Pagination) |
+| 精靈流程「上一步 / 下一步」 | `Steps`(流程進度)+ Button——頁碼是**位置導覽**,不是流程推進 |
+| 檢視切換(清單 / 看板 / 時間軸) | `SegmentedControl`(互斥選值) |
+| 資料不足 2 頁且未來也不會成長 | 不放 Pagination(元件本身單頁仍照常渲染;`total <= 0` 才不渲染——見邊界案例) |
+
+## 近親分界
+
+- **vs `SegmentedControl`**:兩者都是「多顆中亮一顆」,但語意不同——SegmentedControl 是**互斥選值**(選項固定 2-5 個、每個選項有語意),Pagination 是**位置導覽**(頁數動態、可摺疊、數字本身無語意)。SegmentedControl 恆有一值且不可空;Pagination 的當前頁是「你在哪」不是「你選了什麼」。
+- **vs `<DataTable pagination>`**:DataTable 把 TanStack 分頁模型(`getPaginationRowModel`)封裝在內部並消費本元件 render 分頁列(Ant Table 消費 Pagination / Atlassian DynamicTable `rowsPerPage` 同模式)。表格場景一律走內建;standalone Pagination 留給非 DataTable 的列表 / 搜尋結果頁。
+- **vs 虛擬滾動**:兩者是互斥的大資料策略(TanStack 官方定位為 alternative strategies)——分頁 = 使用者主動換頁、每頁固定筆數;虛擬滾動 = 連續滾動、只渲染可視列。同一份資料不可同時用兩者。
+- **vs `Button secondary`(語意分界)**:當前頁「視覺上」= secondary 一比一(直接消費),但**語意兩條線**——secondary 是「次要動作」(action emphasis),當前頁是「持續選中」(selection state,由 `aria-current="page"` 承載)。在一般 UI 不得反過來拿 secondary 冒充「選中」表達(選中語意元件走 Chip / SegmentedControl / Pagination);此處是 selection 元件消費 action variant 當視覺 host,方向合法。
+
+---
+
+## 內部結構與摺疊規則
+
+```
+◀ 上一頁   1   …   4  [5]  6   …   12   下一頁 ▶
+```
+
+- **格位配置**:boundary 1 + sibling 1(= MUI `boundaryCount` / `siblingCount` 預設 1/1;內部常數,v1 不開 props——未來若開放,命名必沿用 MUI)。最大格位 = 首尾各 1 + 當前頁左右各 1 + 當前頁 + 2 顆 ellipsis = **7 格**,超過即摺疊。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- **Ellipsis 非互動**:純指示符號(`MoreHorizontal` icon + `aria-hidden`),不可點——對齊 Ant / MUI / shadcn;Breadcrumb 的可點 ellipsis 是 collapse dropdown 場景,語意不同。
+- **上下頁按鈕**:iconOnly(`ChevronLeft` / `ChevronRight`),在第一頁 / 最後一頁時 `disabled`。
+- 頁碼格位由內部演算法產生;兩顆省略號各自身分穩定,翻頁時不互相 remount(演算法簽名與 React key 等實作細節由 `pagination.tsx` 檔內註解單一持有,spec 不重述——職責分離)。
+
+## 視覺
+
+- **全部按鈕 = Button variant 純組裝,零視覺客製**(2026-07-06 user 抓出後精煉):上下頁 = `text` iconOnly、未選數字 = `text`、**當前頁 = `secondary`**——secondary 的 rest(primary 描邊+染字+不染底)/ hover(升 hover 階)/ active(深一階)與 `semantic.css`「選中狀態」canonical 完全同拼寫,直接消費不手寫平行副本(M17/M23)。唯一的 className = 等寬幾何(min-width 方形節奏對齊 Ant,屬 bundled family 合法)。
+- **語意與視覺分工**:「選中」語意由 `aria-current="page"` 承載;Button secondary 僅為視覺 host(action 元件本身無選中語意,見近親分界)。與 Chip / SegmentedControl 選中同一套 token 語言(它們非 Button、自建 element 鏡射同拼寫);同時正是 Ant 當前頁做法(`colorPrimary` 描邊+字+不染底、hover `colorPrimaryHover`)。
+- **間距兩層**:頁碼列內部(數字鈕之間)屬 bundled family(`tokens/layoutSpace/layoutSpace.spec.md` 已明文「Pagination 內部」元件自管),元件固定;完整形態的「資訊 ↔ 操作群」與「頁碼 ↔ 每頁選單」群組間距消費 `--layout-space-tight`(density-aware,與 DataTable 表格→分頁列同 token)。
+
+## 完整形態(showTotal / pageSizeOptions)
+
+**Layout =「資訊左、操作右」**(對齊 Ant 源碼結構:total 文字是最左元素、size changer 是最右元素——資訊「你在哪」與操作「換頁/換每頁筆數」分離):
+
+```
+第 1–20 筆,共 85 筆                    ◀ [1] 2 3 4 5 ▶  [20 筆/頁 ▾]
+```
+
+- `showTotal`(opt-in):左側 range 格式「第 x–y 筆,共 N 筆」——Ant「1-20 of 85 items」/ MUI「1–5 of 13」/ Carbon「1–10 of 128 items」三家共識,非單純總數。
+- `pageSizeOptions`(opt-in):頁碼右側「N 筆/頁」選單(文案內嵌 = Ant「20 / page」同款;消費既有 `Select size="sm"`);變更每頁筆數自動回第 1 頁——MUI TablePagination / TanStack `autoResetPageIndex` 派;Ant 為 preserve-position(clamp)派,本 DS 採 reset-to-1 避免換大 pageSize 後停在超界頁的 clamp 歧義。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- 兩者皆未開 = 純頁碼 inline 形態(consumer layout 決定對齊;表格情境靠右由 DataTable 處理)。
+
+---
+
+## 邊界案例
+
+| 情境 | 行為 |
+|------|------|
+| `total <= 0` | 不渲染(回傳 null)——沒有資料可導覽 |
+| 單頁(`total <= pageSize`) | **照常渲染**(單顆當前頁 + disabled 上下頁)——對齊 Ant `hideOnSinglePage` 預設 false + MUI;保留版面穩定,避免資料量在 1 頁邊界抖動時整條列出現消失 |
+| `page` 越界(< 1 或 > 總頁數) | 防禦性 clamp 後渲染(顯示層不炸);糾正責任在 consumer / DataTable(接資料變動時同步 clamp) |
+| `pageSize <= 0`(consumer contract violation) | 防禦 clamp 至 1(不渲染垃圾格位、totalPages 不會變 Infinity/NaN) |
+| 極大總頁數(500+) | 摺疊規則不變(恆 ≤ 7 格);數字鈕寬度容納 3-4 位數自然撐開 |
+| 邊界頁 disabled 時 focus 落點 | 接受 focus 掉落(對齊 Ant / MUI 行為);不做 focus 轉移 |
+
+## Loading / 空值
+
+本元件無 loading 態——換頁中的資料 loading 由列表 / DataTable 層表達(skeleton / CircularProgress),頁碼列維持可互動或由 consumer disable。無資料(`total <= 0`)即不渲染,空狀態由 `Empty` 表達。
+
+---
+
+## 與 DataTable 的關係
+
+分頁列本體(頁碼、showTotal、每頁筆數選單、資訊左操作右 layout)**SSOT 在本元件**;DataTable 只做:轉發 config(`pagination` prop → 本元件 props)、own TanStack state(controlled 消費)、表格→分頁列 tight 間距、純頁碼形態靠右、與虛擬滾動互斥——這些表格側規則 → `../DataTable/data-table.spec.md`「L5:分頁」段。
+
+## 禁止事項
+
+- ❌ **手刻當前頁選中樣式**——必消費選中 canonical(semantic.css SSOT);選中態不得用 primary-hover(那是瞬時 hover 專用階)
+- ❌ **把按鈕換成 `<a href>`**——URL 同步由 consumer 在 `onPageChange` 接 router;連結型會破壞 controlled 契約與 Button 消費
+- ❌ **與虛擬滾動並用**(同一份資料同時分頁 + 虛擬化)
+- ❌ **把 ellipsis 做成可點按鈕**(快速跳頁需求走未來 `showQuickJumper` 類擴充,不是 ellipsis)
+- ❌ **用 Pagination 做檢視切換 / 流程推進**(見何時不用)
+- ❌ **在 DataTable 下方自行手排 standalone Pagination**(走 `<DataTable pagination>` 內建)
+
+## A11y 預設
+
+**ARIA / Pattern**:WAI-ARIA 無專門 pagination pattern,公認做法(shadcn / MUI / Atlassian 一致)= landmark + current 標記:
+
+- root `<nav aria-label="Pagination">`(landmark;label 用英文 pattern 名,follow Breadcrumb `aria-label="Breadcrumb"` 慣例;consumer 可覆寫)
+- 當前頁按鈕 `aria-current="page"`(**不用** `aria-pressed`——pressed 是可取消的 toggle 語意,當前頁不可「取消」)
+- ellipsis `aria-hidden`(純視覺指示)
+- 上下頁 iconOnly 按鈕帶 `aria-label`(預設「上一頁」/「下一頁」,`prevAriaLabel` / `nextAriaLabel` props 可覆寫)
+
+**鍵盤**:Tab 逐鈕聚焦(原生 button 序)、Enter / Space 觸發——全部繼承 Button 原生語意,無自訂 key handler;不做 roving tabindex(頁碼是 nav landmark 內的獨立按鈕群,非 composite widget,對齊 shadcn / Ant / MUI)。
+
+**驗證**:Storybook a11y 面板 0 critical violation;純鍵盤可完成翻頁與跳頁。
+
+**SizeMatrix N/A rationale**:本元件無 size 軸(單一尺寸,按鈕固定 `size="sm"`)——頁碼列是 chrome 級導覽,不隨 Field 密度縮放(Ant / MUI / Carbon 的 size 變體服務其自家 density 系統;本 DS 表格密度由 DataTable size 控制、分頁列不連動)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+## 相關
+
+- `../Button/button.spec.md` — 按鈕消費(text variant / iconOnly / disabled)
+- `../Chip/chip.spec.md` — 「持續選中」視覺 canonical 同族(描邊+染字、不染底)
+- `../SegmentedControl/segmented-control.spec.md` — 近親分界(互斥選值 vs 位置導覽)
+- `../DataTable/data-table.spec.md` — 表格內建分頁(L5 段,SSOT)
+- `../Steps/steps.spec.md` — 流程進度 vs 位置導覽分界
+- `../../tokens/color/semantic.css` — 選中狀態 token SSOT
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `data-table.spec.md`
+- `segmented-control.spec.md`

package/src/components/Pagination/pagination.stories.tsx

@@ -0,0 +1,98 @@
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Pagination } from './pagination'
+
+const meta: Meta<typeof Pagination> = {
+  title: 'Design System/Components/Pagination/展示',
+  component: Pagination,
+  tags: ['autodocs'],
+}
+export default meta
+type Story = StoryObj<typeof Pagination>
+
+/* ── 預設 ── */
+export const Default: Story = {
+  name: '預設',
+  render: () => {
+    const [page, setPage] = React.useState(3)
+    return (
+      <div className="flex flex-col gap-3">
+        <p className="text-caption text-fg-muted">
+          客服工單佇列:total=128 / 每頁預設 20 → 7 頁(總頁數由 total/pageSize 內部推導,
+          Ant 同款資料模型)。當前頁 `aria-current="page"`,選中 = 主色描邊+染字不染底;
+          選中之上 hover 升 hover 階、按壓 active 階。
+        </p>
+        <Pagination total={128} page={page} onPageChange={setPage} />
+      </div>
+    )
+  },
+}
+
+/* ── 完整形態(資訊左、操作右) ── */
+export const FullBar: Story = {
+  name: '完整形態',
+  render: () => {
+    const [page, setPage] = React.useState(1)
+    return (
+      <div className="flex flex-col gap-3">
+        <p className="text-caption text-fg-muted">
+          搜尋結果頁:showTotal(「第 x–y 筆,共 N 筆」range 格式,Ant/MUI/Carbon 共識)+
+          pageSizeOptions(「N 筆/頁」選單)—— 分頁完整功能 own 在本元件(SSOT),layout =
+          資訊左、操作群(頁碼+每頁筆數)右,對齊 Ant 源碼結構;換每頁筆數自動回第 1 頁。
+        </p>
+        <Pagination
+          total={85}
+          page={page}
+          onPageChange={setPage}
+          showTotal
+          pageSizeOptions={[10, 20, 50]}
+        />
+      </div>
+    )
+  },
+}
+
+/* ── 大量頁數摺疊 ── */
+export const ManyPages: Story = {
+  name: '大量頁數摺疊',
+  render: () => {
+    const [page, setPage] = React.useState(42)
+    return (
+      <div className="flex flex-col gap-3">
+        <p className="text-caption text-fg-muted">
+          商品 SKU 目錄 10,000 筆 / 每頁 20 = 500 頁:恆 ≤ 7 格位、雙側 … 摺疊(boundary/sibling
+          = 1/1,MUI 預設同款);… 為純指示不可點。翻到頭尾附近時摺疊自動變單側。
+        </p>
+        <Pagination total={10000} page={page} onPageChange={setPage} />
+      </div>
+    )
+  },
+}
+
+/* ── 邊界狀態(R3 hasInteractiveStates) ── */
+export const States: Story = {
+  name: '邊界狀態',
+  render: () => {
+    const [first, setFirst] = React.useState(1)
+    const [last, setLast] = React.useState(7)
+    return (
+      <div className="flex flex-col gap-6">
+        <div>
+          <p className="text-caption text-fg-muted mb-2">第一頁 — 上一頁按鈕 disabled</p>
+          <Pagination total={128} page={first} onPageChange={setFirst} />
+        </div>
+        <div>
+          <p className="text-caption text-fg-muted mb-2">最後一頁 — 下一頁按鈕 disabled</p>
+          <Pagination total={128} page={last} onPageChange={setLast} />
+        </div>
+        <div>
+          <p className="text-caption text-fg-muted mb-2">
+            單頁(total ≤ pageSize)— 照常渲染保持版面穩定(Ant hideOnSinglePage=false + MUI 同);
+            total=0 則整個不渲染
+          </p>
+          <Pagination total={15} page={1} onPageChange={() => {}} />
+        </div>
+      </div>
+    )
+  },
+}

package/src/components/Pagination/pagination.tsx

@@ -0,0 +1,263 @@
+// ────────────────────────────── 消費的 SSOT ──────────────────────────────
+// - Button:../Button/button.tsx —— 全部按鈕純 variant 組裝零視覺客製(2026-07-06 user 抓出):
+//   上下頁 = text iconOnly / 未選數字 = text / 當前頁 = secondary(rest primary 描邊染字不染底、
+//   hover 升 hover 階、active 深一階 —— 與 semantic.css「選中」canonical + 拍板 #8 完全同拼寫);
+//   選中「語意」由 aria-current="page" 承載(非 pressed —— pressed 是可取消 toggle,當前頁不可取消)
+// - Select(size="sm"):../Select/select.tsx —— 完整形態的「N 筆/頁」選單
+// - Ellipsis icon:MoreHorizontal(.claude/rules/ui-development.md「Icon canonical」)
+// - DOM 骨架:shadcn Pagination(nav > ul > li + aria-current="page");
+//   controlled 事件驅動 + total/pageSize 資料模型對齊 Ant Pagination(2026-07-06 user 拍板:
+//   Pagination 本體 = 完整功能 SSOT —— showTotal / 每頁筆數皆本元件 own,Table 轉發 config 消費)
+// 設計規則:./pagination.spec.md
+import * as React from 'react'
+import { ChevronLeft, ChevronRight, MoreHorizontal } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { Button } from '@/design-system/components/Button/button'
+import { Select } from '@/design-system/components/Select/select'
+import { useControllable } from '@/design-system/hooks/use-controllable'
+
+// MUI usePagination 預設同款(boundaryCount/siblingCount = 1/1)。內部常數不開 props(M21
+// 最小 API);未來若開放,命名必沿用 MUI siblingCount / boundaryCount。
+// 最大格位 = 首尾各 1 + 當前頁左右各 1 + 當前頁 + 2 顆 ellipsis = 7,超過即摺疊。
+const BOUNDARY_COUNT = 1
+const SIBLING_COUNT = 1
+
+type PaginationSlot = number | 'ellipsis-start' | 'ellipsis-end'
+
+// 摺疊演算法照 MUI usePagination(1/1 配置);兩顆 ellipsis 用 distinct 穩定 key
+// (Breadcrumb Math.random key remount 前車之鑑,breadcrumb.tsx:208-210)。
+function getPaginationRange(page: number, totalPages: number): PaginationSlot[] {
+  const range = (start: number, end: number) =>
+    Array.from({ length: end - start + 1 }, (_, i) => start + i)
+
+  // 全部放得下(≤ 7 頁)→ 不摺疊
+  if (totalPages <= BOUNDARY_COUNT * 2 + SIBLING_COUNT * 2 + 3) return range(1, totalPages)
+
+  const startPages = range(1, BOUNDARY_COUNT)
+  const endPages = range(totalPages - BOUNDARY_COUNT + 1, totalPages)
+  const siblingsStart = Math.max(
+    Math.min(page - SIBLING_COUNT, totalPages - BOUNDARY_COUNT - SIBLING_COUNT * 2 - 1),
+    BOUNDARY_COUNT + 2,
+  )
+  const siblingsEnd = Math.min(
+    Math.max(page + SIBLING_COUNT, BOUNDARY_COUNT + SIBLING_COUNT * 2 + 2),
+    totalPages - BOUNDARY_COUNT - 1,
+  )
+
+  return [
+    ...startPages,
+    ...(siblingsStart > BOUNDARY_COUNT + 2
+      ? (['ellipsis-start'] as const)
+      : [BOUNDARY_COUNT + 1]),
+    ...range(siblingsStart, siblingsEnd),
+    ...(siblingsEnd < totalPages - BOUNDARY_COUNT - 1
+      ? (['ellipsis-end'] as const)
+      : [totalPages - BOUNDARY_COUNT]),
+    ...endPages,
+  ]
+}
+
+export interface PaginationProps extends React.ComponentPropsWithoutRef<'nav'> {
+  /** 資料總筆數(Ant `total` 同款資料模型;<= 0 不渲染)。總頁數 = ceil(total / pageSize) 內部推導。 */
+  total: number
+  /** 每頁筆數(controlled;搭配 onPageSizeChange)。不傳 = uncontrolled(defaultPageSize 起始)。 */
+  pageSize?: number
+  /** uncontrolled 每頁筆數初始值(預設 20)。 */
+  defaultPageSize?: number
+  /** 當前頁(1-based,controlled)。不傳 = uncontrolled(defaultPage 起始)。越界防禦性 clamp。 */
+  page?: number
+  /** uncontrolled 初始頁(1-based,預設 1)。 */
+  defaultPage?: number
+  /** 換頁 callback(1-based)。URL 同步在此接 router,不把按鈕換 <a>。每頁筆數變更時自動回第 1 頁並 fire。 */
+  onPageChange?: (page: number) => void
+  /** 每頁筆數變更 callback。 */
+  onPageSizeChange?: (pageSize: number) => void
+  /** 完整形態:左側顯示「第 x–y 筆,共 N 筆」range 資訊(Ant showTotal / MUI / Carbon 同款,opt-in)。 */
+  showTotal?: boolean
+  /** 完整形態:頁碼右側渲染「N 筆/頁」選單(消費 Select sm;Ant showSizeChanger 同款,opt-in)。 */
+  pageSizeOptions?: number[]
+  /** 上一頁按鈕 aria-label(iconOnly 必有名)。 */
+  prevAriaLabel?: string
+  /** 下一頁按鈕 aria-label。 */
+  nextAriaLabel?: string
+}
+
+/**
+ * Pagination —— 大量資料切頁後的位置導覽(數字頁碼派,2026-07-05 user 拍板)。
+ *
+ * 本元件是分頁的**完整功能 SSOT**(2026-07-06 user 拍板):頁碼 + 總筆數資訊(showTotal)
+ * + 每頁筆數選單(pageSizeOptions)全部 own 在此;完整形態 layout =「資訊左、操作右」
+ * (Ant 源碼結構同款:total 文字最左、size changer 最右)。DataTable 等 consumer 轉發
+ * config 消費本元件,不自拼分頁列。與虛擬滾動互斥。詳 ./pagination.spec.md。
+ */
+const Pagination = React.forwardRef<HTMLElement, PaginationProps>(
+  (
+    {
+      total,
+      pageSize: pageSizeProp,
+      defaultPageSize = 20,
+      page: pageProp,
+      defaultPage = 1,
+      onPageChange,
+      onPageSizeChange,
+      showTotal = false,
+      pageSizeOptions,
+      prevAriaLabel = '上一頁', // i18n-allow: DS default; consumer override via prop(precedent calendar.tsx)
+      nextAriaLabel = '下一頁', // i18n-allow: DS default; consumer override via prop
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    // Hooks 必在 early return 之前(React #310 canonical,select.tsx:503 同慣例)
+    const [pageSize, setPageSize] = useControllable<number>({
+      value: pageSizeProp,
+      defaultValue: defaultPageSize,
+      onChange: onPageSizeChange,
+    })
+    const [page, setPage] = useControllable<number>({
+      value: pageProp,
+      defaultValue: defaultPage,
+      onChange: onPageChange,
+    })
+
+    // 無資料 → 不渲染(空狀態由 Empty / 列表層表達,詳 spec 邊界案例)
+    if (total <= 0) return null
+
+    // pageSize <= 0 防禦 clamp(consumer contract violation)——防 totalPages 變 Infinity/NaN
+    // 渲染垃圾格位(spec 邊界案例表有對應 row)
+    const safePageSize = Math.max(1, Math.floor(pageSize))
+    const totalPages = Math.max(1, Math.ceil(total / safePageSize))
+    const current = Math.min(Math.max(page, 1), totalPages)
+    const slots = getPaginationRange(current, totalPages)
+    const hasSizeChanger = !!pageSizeOptions && pageSizeOptions.length > 0
+    const hasExtras = showTotal || hasSizeChanger
+    const rangeStart = (current - 1) * safePageSize + 1
+    const rangeEnd = Math.min(current * safePageSize, total)
+    // 當前 pageSize 不在 options 內時補進清單頭(否則 Select trigger 顯示裸值失去「N 筆/頁」文案)
+    const sizeOptions = hasSizeChanger
+      ? (pageSizeOptions!.includes(safePageSize) ? pageSizeOptions! : [safePageSize, ...pageSizeOptions!])
+      : []
+
+    const pageList = (
+      <ul className="flex items-center gap-1">
+        <li>
+          <Button
+            variant="text"
+            size="sm"
+            iconOnly
+            startIcon={ChevronLeft}
+            aria-label={prevAriaLabel}
+            disabled={current <= 1}
+            onClick={() => setPage(current - 1)}
+          />
+        </li>
+        {slots.map((slot) =>
+          typeof slot === 'number' ? (
+            <li key={slot}>
+              {/* 當前頁 = <Button variant="secondary"> 一比一零客製(2026-07-06 user 抓出可純組裝):
+                  secondary 的 rest(primary 描邊+染字+不染底)/ hover(升 hover 階)/ active(深一階)
+                  與 semantic.css「選中」canonical + 拍板 #8 完全同拼寫,且無 neutral 灰底 hover —
+                  消費既有 variant 取代手寫平行拼寫(M17/M23 SSOT)。選中「語意」由 aria-current="page"
+                  承載,Button 僅為視覺 host;未選 = text variant。className 只剩等寬幾何
+                  (蓋掉 size sm 的 min-w-14/px-3,方形 item 對齊 Ant;兩 variant 同 border 寬零位移)。 */}
+              <Button
+                variant={slot === current ? 'secondary' : 'text'}
+                size="sm"
+                aria-current={slot === current ? 'page' : undefined}
+                className="min-w-[var(--field-height-sm)] px-1 justify-center tabular-nums"
+                onClick={() => setPage(slot)}
+              >
+                {slot}
+              </Button>
+            </li>
+          ) : (
+            // Ellipsis 純指示不可點(Ant / MUI / shadcn 同);寬度對齊數字鈕保持節奏
+            <li
+              key={slot}
+              aria-hidden
+              className="flex min-w-[var(--field-height-sm)] items-center justify-center"
+            >
+              <MoreHorizontal size={16} className="text-fg-muted" />
+            </li>
+          ),
+        )}
+        <li>
+          <Button
+            variant="text"
+            size="sm"
+            iconOnly
+            startIcon={ChevronRight}
+            aria-label={nextAriaLabel}
+            disabled={current >= totalPages}
+            onClick={() => setPage(current + 1)}
+          />
+        </li>
+      </ul>
+    )
+
+    return (
+      <nav
+        ref={ref}
+        aria-label="Pagination"
+        className={cn(
+          'flex items-center',
+          // 完整形態 =「資訊左、操作右」(Ant 源碼結構:total 文字最左 li、size changer 最右 li)
+          hasExtras && 'w-full justify-between gap-[var(--layout-space-tight)]',
+          className,
+        )}
+        {...props}
+      >
+        {hasExtras && (
+          // i18n-allow: DS default(range 格式 = Ant/MUI/Carbon 共識);showTotal=false 時渲染
+          // 空 span 佔 justify-between 左位,不含 stray 文字節點
+          <span className="text-body text-fg-secondary">
+            {showTotal ? `第 ${rangeStart}–${rangeEnd} 筆,共 ${total} 筆` : null}
+          </span>
+        )}
+        <div className="flex items-center gap-[var(--layout-space-tight)]">
+          {pageList}
+          {hasSizeChanger && (
+            <Select
+              size="sm"
+              aria-label="每頁筆數" // i18n-allow: DS default
+              className="w-28"
+              value={String(safePageSize)}
+              onChange={(v) => {
+                const next = Number(v)
+                // 同值重選 / 非法值不動作——防「重選 20 筆/頁」誤把頁碼重置回第 1 頁
+                if (!Number.isFinite(next) || next <= 0 || next === safePageSize) return
+                setPageSize(next)
+                // 換每頁筆數回第 1 頁——MUI TablePagination / TanStack autoResetPageIndex 派;
+                // Ant 為 preserve-position(clamp)派,本 DS 採 reset-to-1(spec「完整形態」段有註記)
+                setPage(1)
+              }}
+              options={sizeOptions.map((n) => ({ value: String(n), label: `${n} 筆/頁` }))} // i18n-allow: DS default(Ant「20 / page」內嵌同款)
+            />
+          )}
+        </div>
+      </nav>
+    )
+  },
+)
+Pagination.displayName = 'Pagination'
+
+export const paginationMeta = {
+  component: 'Pagination',
+  family: null, // non-family composite(nav 橫排 control row;按鈕消費 Family 3 Button Pill)
+  variants: {},
+  // 單一尺寸(按鈕固定 Button sm;無 size 軸)—— 頁碼列是 chrome 級導覽不隨 Field 密度縮放,
+  // spec「SizeMatrix N/A rationale」段有完整理由
+  sizes: {},
+  // 'selected' = 當前頁(語意由 aria-current="page" 承載;2026-07-07 meta 詞彙統一:持續選中一律 'selected')
+  states: ['default', 'hover', 'active', 'selected', 'focus-visible', 'disabled'],
+  tokens: {
+    // bg:未選/上下頁(Button text)hover 灰底 + active 深一階;當前頁(secondary)bg-surface
+    bg: ['bg-surface', 'bg-neutral-hover', 'bg-neutral-active'],
+    fg: ['text-foreground', 'text-primary', 'text-primary-hover', 'text-primary-active', 'text-fg-muted', 'text-fg-secondary', 'text-fg-disabled'],
+    border: ['border-primary', 'border-primary-hover', 'border-primary-active'],
+    ring: ['ring-ring'],
+  },
+} as const
+
+export { Pagination }

package/src/components/PeoplePicker/people-picker.anatomy.stories.tsx

@@ -252,7 +252,7 @@ export const ColorMatrix: Story = {
               <tr>
                 <Td mono>disabled</Td>
                 <Td><TokenCell token="--bg-disabled" display="bg-disabled" /></Td>
-                <Td><TokenCell token="--border" /></Td>
+                <Td>—(border transparent)</Td>
                 <Td><TokenCell token="--fg-disabled" display="fg-disabled" /></Td>
               </tr>
               <tr>

package/src/components/PeoplePicker/people-picker.spec.md

@@ -88,7 +88,7 @@ PeoplePicker 永遠支援搜尋（內部使用 `Command` / cmdk）——因為
 | 資料類型 | **人員**（含 Avatar） | 任意（純文字）| 任意（純文字）|
 | 單選 / 多選 | 兩者皆支援（value 類型決定）| 單選 | 多選 |
 | 視覺 prefix | Avatar（必備） | 可選 startIcon | 無 |
-| 底層實作 | Popover + Command + SelectMenu | 桌機自建 listbox（`role="combobox"` div + cmdk SelectMenu，`select.tsx:570`）/ 觸控 native `<select>`(`select.tsx` NativeSelect) | 桌機自建 listbox（`role="combobox"` div + cmdk SelectMenu + Tag overlay，`combobox.tsx:699`）/ 觸控 native `<select>`(`combobox.tsx` NativeCombobox) |
+| 底層實作 | Popover + Command + SelectMenu | 桌機自建 listbox（`role="combobox"` div + cmdk SelectMenu，`select.tsx:582`）/ 觸控 native `<select>`(`select.tsx` NativeSelect) | 桌機自建 listbox（`role="combobox"` div + cmdk SelectMenu + Tag overlay，`combobox.tsx:728`）/ 觸控 native `<select>`(`combobox.tsx` NativeCombobox) |
 | 搜尋 | 永遠啟用（人名本質）；single = inline-trigger（wrap `<Select searchable>`），multi 預設 panel-top（`searchIn='menu'`，`searchIn='trigger'` opt-in）— 對齊本 spec L91-92 SSOT 表 | 可選 `searchable`（單選短列表 → inline-trigger only）| 可選 `searchable` + `searchIn='menu' \| 'trigger'`（多選 → 兩種模式）|
 
 **搜尋型態 SSOT canonical**（A1-A5 spec,2026-05-11;2026-05-12 補 PeoplePicker multi `searchIn` opt-in）：
@@ -147,7 +147,7 @@ PeoplePicker 永遠支援搜尋（內部使用 `Command` / cmdk）——因為
 
 | 共享項 | SSOT owner |
 |---|---|
-| Avatar 左 inset 距 trigger.left = 12px 固定(不隨 size/density 漂移)| 本 spec L94 + `people-picker.tsx:362` `!px-[var(--field-px)]` inject(form context)/ `!px-[var(--table-cell-px)]`(naked variant table cell)|
+| Avatar 左 inset 距 trigger.left = 12px 固定(不隨 size/density 漂移)| 本 spec L175「Avatar 左 inset SSOT」段 + `people-picker.tsx:371` `!px-[var(--field-px)]` inject(form context)/ `!px-[var(--table-cell-px)]`(naked variant table cell)|
 | Avatar+人名視覺 | `person-display.tsx:137-152` `PersonDisplay`(共享 renderer)|
 | 人名按空間 ellipsis | `person-display.tsx:150` `truncate flex-1 min-w-0` |
 | Placeholder ellipsis(inline-search active 時)| `field-wrapper.tsx:244` `bareInputStyles` 含 `truncate` |
@@ -237,7 +237,7 @@ PeoplePicker 是 **composite Field Control**(Field shell + Avatar + SelectMenu),
 
 ## shadcn passthrough 例外說明
 
-PeoplePicker 是 **composite 元件**(內部 wrap `<Select>`(single)/ `<Combobox>`(multi)),其主 API 為 declarative(value / onChange / size / mode / options...)。**有套 `forwardRef` + HTML root props spread**(codex P2 fix 2026-05-07 v15.10,`people-picker.tsx:110` / L52 / L130 `...rest`):
+PeoplePicker 是 **composite 元件**(內部 wrap `<Select>`(single)/ `<Combobox>`(multi)),其主 API 為 declarative(value / onChange / size / mode / options...)。**有套 `forwardRef` + HTML root props spread**(codex P2 fix 2026-05-07 v15.10,`people-picker.tsx:111` / L53 / L131 `...rest`):
 
 - **forwardRef + 單一 root**:`PeoplePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'>`,ref 與 `...rest`(`id` / `data-testid` / `onBlur` / `onFocus` / `aria-*` 等 HTML root props)forward 到內部 trigger 容器(readonly/disabled root div、或 wrapped Select / Combobox 的 root),對齊 DS 既有 Combobox / Select 慣例
 - **`onChange` 走 Omit**:本元件 onChange 用 `(value: PersonValue[]) => void` custom signature,跟 HTMLAttributes onChange 衝突,故 Omit
@@ -251,7 +251,7 @@ PeoplePicker 是 **composite 元件**(內部 wrap `<Select>`(single)/ `<Combobox
 
 - **Disabled**:`disabled` → `resolvedMode='disabled'`(`useResolvedFieldMode`),走獨立 static-display 分支(`people-picker.tsx`「readonly / disabled」段)——渲染靜態 `<div>` 包 `MultiPersonDisplay` / `PersonDisplay` + `ItemSuffix` ChevronDown 類型身份 indicator(2026-06-26:disabled 保留 chevron、readonly 不顯示;naked variant 依 `showDisplayEndIcon`),**不** wrap Select / Combobox、無 dismiss X、無 inline-search input。token 走 M24 state precedence(`text-fg-disabled`,含 chevron)。
 - **Loading(async people fetch)**:目前 PeoplePicker **未暴露 `loading` prop**(`PeoplePickerProps` 無此欄位,內部也未 forward 給 wrapped Select / Combobox)。consumer 若需 loading 態,在 fetch 完成前自行控制 `people=[]`(走 emptyText 空態)。底層 Select / Combobox / SelectMenu 各有自己的 loading 機制,但尚未經 PeoplePicker API 層轉發。
-- **Empty(no search results)**:`emptyText` 預設「沒有符合的人員」(本 spec L72 已 codify);無 creatable mode(人員不可建立)。
+- **Empty(no search results)**:`emptyText` 預設「沒有符合的人員」(本 spec L80 已 codify);無 creatable mode(人員不可建立)。
 - **Empty(no value selected)**:single mode → trigger 顯 placeholder「請選擇人員」;multi mode `value=[]` → trigger 同 placeholder(無 avatar stack 渲);詳「Trigger display SSOT canonical table」B-D 段。
 - **`people` 清單變動(async fetch 後更新)**:已選 value 顯示不依賴 `people` 查找 — display 路徑直接渲染 value 自帶資料;edit 路徑以人名回查 `people`,查不到降級為純名字 string(initials fallback),不報錯(`people-picker-helpers.ts:74-75`)。選單選項即時跟隨 props 重渲。
 - **RTL**:未實作方向鏡像(avatar stack overlap `-ml-0.5` / 12px inset 皆以 LTR physical 方向設計);RTL 屬 DS-wide 決策,未定(與 Chip / Breadcrumb 同口徑)。