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

package/src/components/ProgressBar/progress-bar.spec.md

@@ -0,0 +1,232 @@
+---
+component: ProgressBar
+family: self-contained
+traits: []
+variants: {}
+sizes: {}
+benchmark:
+  - Radix Progress primitive: github.com/radix-ui/primitives/tree/main/packages/react/progress
+  - Ant Design Progress: github.com/ant-design/ant-design/tree/master/components/progress
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# ProgressBar 設計原則
+
+**水平進度條(linear determinate progress)**——表達「已完成 X%、還剩 Y%」的量化進度視覺 primitive。0–100% 的已知進度、單向推進、可預期終點。circular 形式(含 indeterminate)走 `CircularProgress`。
+
+**Layout Family**：非上述 family — self-contained primitive（獨立視覺，無 slot 結構；僅 `affix` 附加區可選顯示進度文字或狀態 icon）。
+
+**實作基礎**：基於 Radix `@radix-ui/react-progress` primitive（原生提供 `role="progressbar"` + `aria-valuenow` / `aria-valuemin` / `aria-valuemax` / `aria-valuetext`），外包本 DS 的 status / affix 語意與 token。高度**固定 4px**,不提供 size 選項(見下「單一高度」節)。
+
+> 最薄的 linear determinate progress primitive。沒有 indeterminate animation(那屬 `CircularProgress` 無 value 模式的職責)、沒有 buffered fill(目前無 streaming 場景)、沒有自訂色(只能走 inProgress / success / error 三狀態)。
+
+---
+
+## 定位
+
+ProgressBar 是**量化 linear 進度** primitive——consumer 必須能回答「目前進度是百分之幾」才能使用。若無法量化（e.g. fetching 中不知道要多久），改用 `CircularProgress`(不傳 value,indeterminate 模式)。
+
+世界級對照:
+- **Material** `LinearProgress`(determinate) — 同樣區分 determinate / indeterminate 兩模式,indeterminate 在我們系統由 `CircularProgress`(無 value)承擔
+- **Ant Design** `Progress` — 支援百分比文字、status（success/exception/normal）,我們以 `affix="value"` / `status` 對應 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- **Polaris** `ProgressBar` — 單一直線進度,不含 status 色區分,我們加上 status 對應上傳完成 / 失敗語意 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- **shadcn** `Progress` — 同為 Radix Progress 薄包裝
+
+---
+
+## 何時用
+
+- **批次任務進度**：CSV 匯入、批量同步、報表生成（Linear batch action / Jira bulk edit / Airtable import）
+- **下載 / 匯出進度**（非檔案上傳列表情境）:單檔下載進度、匯出 zip、報表生成
+- **多步驟流程的整體進度**：表單 wizard「步驟 3/5 = 60%」（但**步驟結構本身**用 `Steps` 元件,ProgressBar 只表達整體完成比例）
+- **Table cell / row 內的 inline 進度**：DataTable 裡「配額使用率 45%」、「完成度 78%」等單列靜態指標
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| **檔案上傳 / 下載列表** | `FileItem` | FileItem 是檔案情境 canonical consumer-facing primitive,內部已消費 ProgressBar(見「與 FileItem 的分界」)——consumer 不自組 raw ProgressBar + 檔名 + icon 做上傳 UI |
+| 進度無法量化(fetch / 等待 server) | `CircularProgress`(無 value,indeterminate) | ProgressBar 需已知 0-100%,無法估算終點時用 CircularProgress 的 indeterminate 語意 |
+| <1 秒的短暫操作 | `CircularProgress` 或不顯示 | ProgressBar 動畫(300ms transition)在極短操作反而造成閃爍 |
+| 骨架載入(預期內容形狀) | `Skeleton` | Skeleton 保留 layout,ProgressBar 只傳達「執行中量化」 |
+| 步驟導覽(顯示 step 1/2/3 結構) | `Steps` | Steps 強調 step 本身是什麼、ProgressBar 只看整體百分比 |
+| 容量 / 配額靜態顯示(非動態進行中) | 可用 ProgressBar(不傳 status,預設 inProgress 即可) | 可接受——ProgressBar 也能表達靜態 ratio,但若只是裝飾比例、非「進行中」語意,考慮 Chart bar 類元件 |
+| 評分顯示(5 顆星 80%) | `Rating` | Rating 有離散刻度語意 |
+| 小空間 / inline icon 位置的量化進度 | `CircularProgress`(有 value,determinate) | ProgressBar 在 16–24px 的小空間視覺比例不如 circular arc |
+
+---
+
+## 與 CircularProgress 的分界(SSOT)
+
+**本節為 ProgressBar ↔ CircularProgress 分界的 single source of truth**,`circular-progress.spec.md` 的定位表以 pointer 指向本節深度規則。
+
+**核心判斷**:兩個維度擇一(兩者都必須通過才選 ProgressBar):
+1. **能量化進度嗎?**(ProgressBar 必須能;CircularProgress 兩態都接受)
+2. **形狀適合 linear 還是 circular?**(頁面級 / 表單 wizard / 上傳列表 = linear;inline 小空間 / Button / Field = circular)
+
+| 維度 | ProgressBar | CircularProgress |
+|------|-------------|------------------|
+| **形狀** | linear(水平直線) | circular(圓弧) |
+| **進度模式** | determinate(0–100% 已知) | 兩態合一:無 value → indeterminate / 有 value → determinate |
+| **視覺** | 水平直線從左往右填充 | 圓弧從 12 點順時針填充 / indeterminate 整體旋轉 |
+| **典型情境** | 批次處理 / 表單 wizard / 頁面級大區塊 / quota(檔案上傳 → 走 FileItem) | Button loading / Field loading / cell 局部 / inline 小 % |
+| **可量化時機** | **必須能量化**(100% 結束可預期) | determinate 能量化 / indeterminate 不需要 |
+| **a11y** | `role="progressbar"` + `aria-valuenow` | `role="progressbar"`(有 value) / `role="status"`(無 value) |
+| **終止條件** | 到 100% 或 status 變 success / error | 任務完成(卸載或 aria-busy 移除) |
+| **typical 時長** | 秒級到分鐘級(值得顯示比例) | 秒級(短暫等待) / 秒到分鐘(determinate) |
+
+**選擇 flowchart**:
+
+```
+1. 有進度數值嗎?
+   ├─ 沒有 / 不知道時長 ────────→ CircularProgress(不傳 value)
+   │    ├─ < 1 秒          ──→ 不顯示(避免閃爍)
+   │    ├─ 1-10 秒         ──→ CircularProgress indeterminate
+   │    └─ > 10 秒 + 無量化 ──→ CircularProgress + 額外文字說明
+   │
+   └─ 有(0-100%)
+      2. 場景形狀適合?
+         ├─ 頁面級 / 表單級 / 上傳列表 / 大區塊 ─→ ProgressBar
+         └─ inline 小空間 / Button / Field / cell ─→ CircularProgress(傳 value)
+```
+
+**禁止混搭**:同一操作內不能先 CircularProgress 再 ProgressBar(會讓使用者以為是兩個獨立步驟)。一個操作若一開始不知進度、中段才取得 → 維持 indeterminate CircularProgress 到底,或改由上層 overlay 控制切換。
+
+---
+
+## API
+
+```tsx
+export interface ProgressBarProps {
+  /** 當前進度 0-100,超出範圍自動 clamp */
+  value: number
+  /** inProgress=進行中 / success=完成 / error=失敗 */
+  status?: 'inProgress' | 'success' | 'error'
+  /** 右側附加:value=顯示 `{value}%` / status-icon=顯示狀態圖示 / ReactNode=客製 */
+  affix?: 'value' | 'status-icon' | React.ReactNode
+  /**
+   * Track 高度 override(**非 consumer API**)。
+   * 僅 FileItem 的 compact mode 內部使用,匹配極密集 row 的視覺比例。
+   * Consumer 不要傳此 prop;若有新需求應先討論是否開新 variant,而非濫用此逃生艙。
+   */
+  height?: number
+}
+```
+
+### Status 語意
+
+| Status | 語意 | fill token | 使用時機 |
+|--------|------|-----------|---------|
+| `inProgress`(預設) | 進行中 / 未完成 ratio | `--primary` | 處理中、靜態比例顯示、CSV 匯入 |
+| `success` | 完成 / 成功 | `--success` | value 到 100% 且操作成功完成 |
+| `error` | 失敗 / 中斷 | `--error` | 處理中斷、配額超出警示 |
+
+**禁止新增 `warning` status**:ProgressBar 的語意是「進行中 / 成功 / 失敗」二元終態,warning 屬於 Notice / Alert 的範疇。若要表達配額警示(如 90% 快滿),consumer 自己根據 value 切換到 `error`,不要在 ProgressBar 加中間色。
+
+### 單一高度 4px(2026-04-20 決策)
+
+本元件**不提供 size 選項**,track 固定 `4px`——對齊 Material 3 / Carbon / Ant Design 慣例(皆固定單一高度)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**為什麼不分 size**:
+- 過往分 size 的刻度差太小,視覺差異使用者幾乎無法區分,形同冗餘 API
+- 分 size 反而讓 consumer 每次要「判斷該選哪個」,增加認知負擔
+- 世界級 canonical:Material LinearProgress / Carbon ProgressBar / Ant Progress 皆固定單一高度,無 size variant <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- 若需要視覺強調(hero level progress),改用 full-width 排版 + 放大百分比文字 / swap 為 CircularProgress 大尺寸,不靠 size 階梯撐
+
+### 與 FileItem 的分界(consumer 選哪個)
+
+**檔案上傳 UI 一律走 `FileItem`,不直接消費 ProgressBar**。FileItem 是檔案情境的 canonical consumer-facing primitive(檔名 / icon / 進度 / status / actions 一條龍);FileItem 內部**可能**消費 ProgressBar(實作細節,consumer 不用關心)。
+
+| 情境 | 用什麼 |
+|------|--------|
+| 單檔 / 多檔上傳列表 / 下載 progress | **FileItem**(`components/FileItem/`)|
+| CSV 匯入 / 批次處理 / 表單 wizard / quota 使用率 | **ProgressBar** 直接用 |
+| 短暫 loading(不知時長) | **CircularProgress**(indeterminate) |
+
+**世界級對照**:Ant Design 的 `Upload` vs `Progress`(Upload.List 內部用 Progress,consumer 不直接拼 Progress 做上傳 UI)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+### Affix 選擇
+
+| Affix | 適用時機 | 範例 |
+|-------|---------|------|
+| `"value"` | 靜態 poll 場景 / 使用者想知道具體百分比 | DataTable cell「配額 78%」、FileItem「45%」 |
+| `"status-icon"` | final state（success ✓ / error ✗）| 上傳完成顯示勾、失敗顯示叉 |
+| `ReactNode` | 客製（e.g. action button「取消」、file size「2.3/5.0 MB」） | 上傳中顯示「取消」按鈕 |
+| 不傳 | in-flight 不需額外資訊 | 短暫過渡狀態、nested 容器已有進度文字 |
+
+**禁止**：同時在 affix 顯示 value 又在旁邊額外寫 `{value}%` 文字——會重複。取一個。
+
+---
+
+## 禁止事項
+
+❌ **不得硬寫色值**——所有 status 色必走 `--primary` / `--success` / `--error` token,consumer 不可 override fill 色(若業務需要其他色,提到系統層討論新 status,不是每個消費者自己改)
+
+❌ **不得將 ProgressBar 當 CircularProgress 用**——進度不可量化的操作一律用 `CircularProgress`(不傳 value),不要傳 `value={indeterminate ? ... : ...}` 假裝進度
+
+❌ **不得堆疊多個 ProgressBar 在同一操作**——每個操作一個 bar。多檔上傳清單 = 每檔一個 ProgressBar,但「整體進度」不再加一條總 bar(Dropbox / Google Drive 皆此做法)
+
+❌ **不得用於 <1 秒的短暫操作**——動畫 transition(300ms)會造成閃爍,改用 CircularProgress 或不顯示
+
+❌ **不得用於未知進度**(詳見「與 CircularProgress 的分界」)
+
+❌ **不得加 `warning` status**(見 Status 語意節)
+
+❌ **不得在 ProgressBar 內塞內容(children)**——它是純視覺,附加資訊走 `affix`
+
+---
+
+## 狀態與邊界
+
+- **Disabled**:本元件無 disabled 狀態。ProgressBar 是純視覺回饋,不接受互動事件。若整個上傳流程被禁用,由 parent container 控制(e.g. 包裝 `<fieldset disabled>` 或不 render)
+- **Loading**:ProgressBar 本身就是 loading 的視覺,不再疊加 CircularProgress
+- **Empty / 0%**:value=0 時仍 render 整條 track(灰底 + 無填充),不做特殊 empty state
+- **Dark mode**:fill 色透過 semantic token(`--primary` / `--success` / `--error`)自動反轉,詳見 `color.spec.md`
+- **Density**:本元件不隨 density 縮放(track 單一高度,見 tsx)
+
+---
+
+## A11y 預設
+
+Radix `Progress.Root` 自動提供：
+- `role="progressbar"`
+- `aria-valuenow={value}` / `aria-valuemin={0}` / `aria-valuemax={100}`
+- 如需客製 announce（e.g.「上傳中 45%」）,在 parent 傳 `aria-valuetext="上傳中 45%"` override
+
+**Consumer 需補**:若此 ProgressBar 代表特定語境任務,在 parent 加 `aria-label`(e.g.「檔案上傳進度」)讓螢幕閱讀器能辨認。
+
+---
+
+## 為何無 StateBehavior
+
+ProgressBar 是**純視覺百分比指示**,本身**無互動狀態**(見「狀態與邊界」段:無 disabled,不接受互動事件)。唯一的「行為」是 value 變化時 fill 寬度動畫——那是 controlled prop 的資料更新,不是 UI state 切換。color variant(inProgress / success / error)依 value 狀態切換的行為已在 `ColorMatrix` + 元件特有 `AffixBehavior`(percent / icon-on-complete 驅動邏輯)覆蓋。
+
+對應 anatomy story:保留 `Overview` + `Inspector`(value 試玩) + `ColorMatrix` + 元件特有 `AffixBehavior`。無 `SizeMatrix`(高度固定 4px)。
+
+---
+
+## 相關
+
+- **CircularProgress 分界** — 本 spec「與 CircularProgress 的分界」節(SSOT)
+- **CircularProgress 元件** — `components/CircularProgress/circular-progress.spec.md`(circular 兩態 primitive)
+- **FileItem 消費** — `components/FileItem/file-item.tsx`(canonical 檔案情境 consumer-facing primitive,內部消費 ProgressBar 的 4px 單一高度)
+- **Steps** — `components/Steps/steps.spec.md`(步驟結構非百分比)
+- **Skeleton** — `components/Skeleton/skeleton.spec.md`(骨架載入非進度)
+- **Color tokens** — `tokens/color/color.spec.md`(`--primary` / `--success` / `--error` 定義)
+
+## 遷移記錄(2026-04-20)
+
+元件由 `Progress`(folder `Progress/` + identifier `Progress`)重命名為 `ProgressBar`(folder `ProgressBar/` + identifier `ProgressBar`)。Breaking change:
+
+- `import { Progress } from '.../Progress/progress'` → `import { ProgressBar } from '.../ProgressBar/progress-bar'`
+- `<Progress value={N}/>` → `<ProgressBar value={N}/>`(props 契約未變)
+- `ProgressProps` type name → `ProgressBarProps`
+
+重命名理由:`CircularProgress` 元件(circular 兩態合一)納入系統後,需和 `Progress`(原 linear)在名稱上明確區分形狀。`ProgressBar` 對齊 Polaris / shadcn 命名慣例,使用者一看即知是 linear。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `file-item.spec.md`

package/src/components/RadioGroup/radio-group.spec.md

@@ -0,0 +1,141 @@
+---
+component: RadioGroup
+family: 4
+variants: {}
+sizes:
+  sm:
+    when: "form field-height 28 / compact chrome / dialog / panel context"
+  md:
+    when: "default general UI"
+  lg:
+    when: "touch / prominent CTA / stakeholder-facing surface"
+traits:
+  - hasSizes
+  - hasInteractiveStates
+  - isSelectionMulti
+benchmark:
+  - Radix RadioGroup primitive: github.com/radix-ui/primitives/tree/main/packages/react/radio-group
+  - Ant Design Radio: github.com/ant-design/ant-design/tree/master/components/radio
+  - MUI Radio: github.com/mui/material-ui/tree/master/packages/mui-material/src/Radio
+  - Polaris RadioButton: github.com/Shopify/polaris/tree/main/polaris-react/src/components/RadioButton
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# RadioGroup 設計原則
+
+## 定位
+
+RadioGroup 是**互斥單選且全選項可見**的表單控件——從 2-5 個選項中挑恰好一個，每個選項一行獨立呈現（支援 label + description + 完整閱讀）。
+
+**Layout Family**：非上述 family — self-contained primitive（獨立視覺，無 slot 結構）。
+
+**實作基礎**：基於 Radix RadioGroup（shadcn 包裝）+ 橋接 DS token。
+
+共用規則見 `../Checkbox/checkbox.spec.md`（Checkbox & RadioGroup 設計原則，含 SelectionItem 佈局與 clamp 政策）。
+
+---
+
+## 何時用
+
+- **決策節點的互斥單選**：付款方式、訂閱方案、票種、權限角色——使用者需要**對比評估**
+- **選項需要描述文字**：法律條款、方案價格、feature 比較（Radio 的 description 支援完整閱讀，不截斷）
+- **2-5 個選項且全部可見**：讓使用者一眼看完所有選項，不需要點兩次（Select）
+- **空間允許 O(n) 垂直展開**：form 內、dialog 內、setting section 內
+
+## 何時不用
+
+**與 Select 的分界詳見 `../Select/select.spec.md` 的「與 RadioGroup 的分界」**（SSOT）——Select 是 Select vs RadioGroup 判斷的 owner。簡言：RadioGroup 用於「使用者需對比評估的決策節點」，Select 用於「label 自帶語意、空間受限、使用者熟悉選項」。
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 空間受限 / 選項超過 5 個 | `Select` | RadioGroup 全可見，O(n) 垂直空間成本過高 |
+| 2-5 個緊湊切換（toolbar / filter） | `SegmentedControl` | compact control，pill 尺寸融入 toolbar |
+| 多選（可選多個）| `Checkbox` | Radio 是互斥單選，Checkbox 是獨立 toggle |
+| 布林 on/off | `Switch`（即時）/ 單個 `Checkbox`（on-submit） | 布林不需要「選一個」的心智模型 |
+| 大量選項需要搜尋 | `Select` + `searchable` | RadioGroup 不支援搜尋 |
+
+---
+
+## 與 Checkbox 的差異
+
+視覺語言共用（見 Checkbox spec），差異僅在：
+
+- **形狀**：`rounded-full`（Checkbox 是 `rounded-md`）
+- **指示器**：filled dot（Checkbox 是 check / minus icon）
+- **語意**：互斥單選（Checkbox 可多選）
+- **`fieldLayout`**：`'block'`（放進 `<Field>` 時 Field 自動切 block 模式；Checkbox 沒有此 static 屬性，因為單個 Checkbox 是 inline primitive）
+
+---
+
+## 尺寸
+
+共用 Checkbox 的 sm/md/lg 控件尺寸(sm/md=16px, lg=20px),詳見 `../Checkbox/checkbox.spec.md`「尺寸」。
+
+### 為什麼不完全對齊 `--field-height-*`
+
+- **現況**:控件 sm=16 / md=16 / lg=20px(不等於 `--field-height-sm/md/lg` = 28/32/36px)
+- **Rationale**:Radio 與 Checkbox 視覺語言共用(只是形狀 round vs square),rationale 完全繼承 Checkbox——控件是選擇指示器(indicator)不是容器,走 icon tier(16/16/20),行高對齊透過 SelectionItem 的 `py = (field-height - 1lh) / 2` 保證
+- **世界級對照**:Material 3 Radio = 20px / Ant Design Radio = 16px / Polaris RadioButton = 16px——全部獨立於 field-height,與 Checkbox 控件尺寸對齊 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## StateBehavior(RadioGroup 層級特有)
+
+Item-level default / hover / active / checked / disabled **色彩**與 Checkbox 共用同一套 SelectionItem 規則,由 `ColorMatrix` story 承載;RadioGroup 的 `StateBehavior` story 展示**群組層級的互斥行為**(單選模型 / 個別 disabled / 整組 disabled),這是 Checkbox 沒有的維度。
+
+---
+
+## Mode / disabled / readonly / 驗證 / a11y
+
+繼承 Field family,詳見 `../Field/field-controls.spec.md` + `../Field/form-validation.spec.md`。
+
+---
+
+## 禁止事項
+
+- ❌ 單選卻用 Checkbox 群組模擬——selection model 不對,keyboard navigation 與 a11y 角色錯誤
+- ❌ RadioGroup 沒有 group label(`<Field>` 的 label 或 `aria-labelledby`)——螢幕閱讀器無法念出這是哪組選項
+- ❌ 巢狀 RadioGroup(radio 內包 radio)——互斥模型只適用單層,需要階層選擇改用樹狀 Select
+- ❌ 選項數量超過 5 或空間受限時硬用 RadioGroup,不改 Select(見「何時不用」)
+
+---
+
+## 邊界案例
+
+- **Disabled**:Group-level `disabled` 套用至所有 radio items;item-level `disabled` 單獨 disable 該選項。視覺繼承 SelectionItem SSOT(`text-fg-disabled` + 灰 radio circle + 不可點 + 鍵盤導覽自動 skip)。
+- **Loading(async option fetch)**:async option list 載入時 consumer 應渲 `<Skeleton>` 對應 radio item count(常見 3-5 行 skeleton),而非空 RadioGroup;RadioGroup 自身不獨立 own loading prop。
+- **Empty(no options)**:罕見場景。應由 consumer 條件性渲 `<Empty>` placeholder(「無可選項目」)取代空 RadioGroup,不渲 0-radio 空 group(SR 會讀「empty group」造成混淆)。
+- **No value selected**:`value=null` 為合法 initial state(所有 radio 都 unchecked);Field validation 在 required + null 時觸發 error。
+- **Dark mode / density**:走 SelectionItem semantic token 自動 adapt;垂直 gap 隨 layoutSpace token density-aware。
+
+---
+
+## 相關
+
+- `../Checkbox/checkbox.spec.md` — 共用規則（SelectionItem 佈局 / clamp 政策 / 視覺語言）
+- `../Select/select.spec.md` — 「與 RadioGroup 的分界」SSOT（Select vs RadioGroup 決策的 owner）
+- `../SegmentedControl/segmented-control.spec.md` — compact 互斥切換的替代
+- `../Switch/switch.spec.md` — 布林開關
+- `../Field/field.spec.md` — RadioGroup 作為 Field control 時的 block layout 整合
+
+## A11y 預設
+
+**ARIA / Pattern**:繼承 Radix `radio-group` primitive a11y 預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/radio-group#accessibility)。
+
+**Keyboard 行為**:
+
+- Tab — 進入 group
+- ↑/↓ — 切 option
+- Space — 選擇
+
+**Focus**:Radix primitive 自管 focus trap / restoration / visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。
+
+**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `selection-item.spec.md`
+- `steps.spec.md`

package/src/components/Rating/rating.spec.md

@@ -0,0 +1,208 @@
+---
+component: Rating
+family: 4
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+  - isMatrixHeavy
+benchmark:
+  - Ant Design Rate: github.com/ant-design/ant-design/tree/master/components/rate
+  - MUI Rating: github.com/mui/material-ui/tree/master/packages/mui-material/src/Rating
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Rating 設計原則
+
+## 定位
+
+Rating 是**離散 1–5 分評分元件**——使用者對商品、服務、體驗給出 1 到 max（預設 5）分的星等，或將已提交的平均分數唯讀展示。
+
+**實作基礎**：自建，無 shadcn 核心或 Radix primitive 對應（shadcn 不提供 Rating，Ant Design `<Rate>` / Material `<Rating>` 為世界級對照）。內部以 lucide-react `Star` 為預設 icon，外層 `role="slider"` / `role="img"` 依 `readOnly` 切換。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**Layout Family**:非 4-Family Model —— **self-contained primitive**(獨立視覺,無 slot 結構,類似 Switch / Checkbox / Badge / CircularProgress)。
+
+---
+
+## 何時用
+
+- **送出評分**（interactive）：Yelp / Google Reviews / Amazon 購物完後「幫這次服務評分」的送出前狀態
+- **展示評分**（readOnly）：商品列表的星等 `4.7 ★★★★★`、評論列表每則評論的作者星等、Airbnb 房源總分
+- **後台商品管理**：店家自己給商品的推薦星等（interactive）
+- **精度展示**：平均分 `4.7`（`precision="half"` 顯示半星），單筆 `5`（`precision="full"` 整星）
+
+## 何時不用
+
+| 情境 | 改用 | 原因 |
+|------|------|------|
+| 純資訊標記（「熱門」「Beta」「新品」）| `Badge` | Rating 是量化 1–5 分，不是分類標籤 |
+| 非 1–5 的連續數值（音量、亮度、價格範圍）| `Slider` | Rating 是離散 tier，Slider 是連續值 |
+| 二元喜歡 / 不喜歡（thumbs up/down、like）| `Switch` 或自組 icon button | Like 是 binary，Rating 是 graded 1–5 |
+| 多維度評比（服務 / 品質 / 速度 各 5 分）| 自組多個 Rating 縱向排列 | 單一 Rating 只表達單一維度 |
+| 進度顯示(任務完成度、上傳進度) | `ProgressBar`(linear)/ `CircularProgress`(circular,有 value) | Rating 不是進度指標,別誤用星星做「完成 4/5 步」|
+| 已提交固定分數但可跳轉「看詳情」| readOnly Rating + 旁邊 Button/Link | Rating 本身不點擊跳頁 |
+
+---
+
+## Props
+
+| Prop | 型別 | 預設 | 說明 |
+|------|------|------|------|
+| `value` | `number` | — | 當前評分（controlled，0 ~ `max`） |
+| `defaultValue` | `number` | `0` | uncontrolled 預設值 |
+| `onChange` | `(value: number) => void` | — | 評分改變 callback |
+| `max` | `number` | `5` | 滿分星數（世界級慣例 = 5，超過 7 會讓使用者無法快速掃視） |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | 尺寸。standalone 展示建議 `xs`(24px,對齊 Avatar/Tag sm);Field 內跟 Field size 傳 sm/md/lg |
+| `precision` | `'full' \| 'half'` | `'full'` | 整星 or 半星 |
+| `readOnly` | `boolean` | `false` | 唯讀展示（不響應 hover / click / 鍵盤） |
+| `disabled` | `boolean` | `false` | 完全停用 |
+| `icon` | `LucideIcon` | `Star` | 自訂 icon（極少用；禁止換成 Heart / ThumbsUp，見禁止事項） |
+| `aria-label` | `string` | — | `readOnly` 時必填（例：「平均評分 4.7 星，共 5 星」） |
+
+---
+
+## Size
+
+| Size | Container 高度 | Star icon | 使用情境 | 配對 field |
+|------|---------------|-----------|---------|-----------|
+| `xs` | **24px**(`h-field-xs`) | 20px | **Standalone 建議值**:商品卡、評論列表旁、搜尋結果 row 的星等展示(非 Field 內時) | — |
+| `sm` | 28px(`h-field-sm`) | 20px | Field sm 並排 | field sm |
+| `md` | 32px(`h-field-md`) | 24px | **Field 預設**。一般表單評分欄位 | field md |
+| `lg` | 36px(`h-field-lg`) | 24px | 送出評分的 review form、強調的主 CTA 區塊 | field lg |
+
+### Standalone vs Field 尺寸選擇(canonical)
+
+- **Standalone 展示**(非 Field 內):用 **`xs`**(container 24 / icon 20)——對齊 Avatar sm 20px / Tag sm;Airbnb / Yelp 商品卡星星亦此大小 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- **Field 內**(`<Field>` 表單內當 control):跟 Field size 對應傳 sm/md/lg(Field 預設 md)
+- 世界級對照:Material Rating standalone ≈ 24dp;Ant Rate 在 Form 內跟 Form itemSize。兩種 context 分開設計,不強求單一預設 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+### Icon 尺寸對齊 **Avatar inline**,不對齊 icon tier(2026-04-21 AR48 canonical)
+
+Rating 的 **container 高度消費 `--field-height-*` token**(sm=28 / md=32 / lg=36),讓它可以與 Input / Select / NumberInput / Button 等 field-height family 元件並排時 row-align 一致。
+
+**Star icon 大小對齊 `item-anatomy` 的 inline Avatar 尺寸**(sm=20 / md=24 / lg=24),**不走 icon tier**(16/16/20)。
+
+| Size | Rating star | Avatar inline | Icon tier | 使用者選到 |
+|------|-------------|---------------|-----------|-----------|
+| sm | **20px** ← Avatar | 20px | 16px | Avatar(更重視覺) |
+| md | **24px** ← Avatar | 24px | 16px | Avatar |
+| lg | **24px** ← Avatar | 24px | 20px | Avatar |
+
+**為什麼對齊 Avatar 不對齊 icon tier**:
+
+1. **視覺份量**:Rating 的「一顆星」是 **filled shape**(整個 icon 面積都是重量),不像純 outline icon 靠 stroke。跟 filled identity 元件(Avatar)同尺寸才能在 row 裡 visual weight 對齊。
+2. **語意**:Rating 是「主要資料視覺」(一顆星 = 一個資料點),不是次要 affordance。次要 affordance(如 Input 的 startIcon、Button iconOnly)才走 icon tier(16/16/20)。
+3. **世界級對照**:Ant Rate in Form = 20px(對齊 Form avatar-like components);Material MUI Rating default 24px;Airbnb 商品卡星星 24px。皆走 identity 重量,不走 icon tier。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+4. **歷史錯誤**:早期設 16/16/20 跟 icon tier 齊,但視覺上跟 inline avatar / tag 並排時星星顯得比 avatar「小一號」,失去「這一顆星是資料點」的語感——AR48 修正。
+
+### 放入 Field 的可組合性
+
+Rating 可直接塞進 `<Field>`(讓使用者能套 Field label / error / hint 共用機制):
+
+```tsx
+<Field>
+  <FieldLabel required>整體滿意度</FieldLabel>
+  <Rating value={rating} onChange={setRating} size="md" />
+  {rating === 0 && <FieldError>請至少給 1 星</FieldError>}
+</Field>
+```
+
+Field 高度由 Rating container(`h-field-md`)自然對齊其他 field control,不需 consumer 額外調整 min-h。`aria-invalid` 透過 FieldContext 自動傳入,視覺錯誤提示由 FieldError 承擔。
+
+---
+
+## Precision — full vs half
+
+| Precision | 顯示值 | 使用情境 |
+|-----------|--------|---------|
+| `full` | 1, 2, 3, 4, 5 | **送出評分**——使用者給分當下只選整數（Yelp / Google Reviews 送出流程就是整星）|
+| `half` | 0.5, 1, 1.5, ..., 5 | **展示平均分**——`4.7` 這類小數只有半星能視覺呈現（Amazon / Shopify 的 `4.7 ★★★★★` 商品列表）|
+
+**原則**：**interactive = full**（使用者按整星清晰、無猶豫），**display average = half**（小數需要更細的視覺刻度）。要給使用者「打半星」的能力只在極特殊情境（如影評社群），一般 SaaS 不建議。
+
+---
+
+## Interactive vs ReadOnly
+
+| Mode | 觸發 | 行為 | ARIA |
+|------|------|------|------|
+| **interactive**（預設）| `readOnly={false} && disabled={false} && loading={false}` | hover 預覽、click 設值、鍵盤 Arrow Left/Right/Up/Down 改值、Focus ring | `role="slider"` + `aria-valuenow/valuemin/valuemax` + `tabIndex={0}` |
+| **readOnly** | `readOnly={true}` | 純顯示，不響應 hover / click / 鍵盤 | `role="img"` + `aria-label`（**必填**，給螢幕閱讀器描述分數）|
+| **disabled** | `disabled={true}` | 不響應，視覺淡化（`opacity-disabled`）| `aria-disabled="true"` |
+| **loading** | `loading={true}` | 不響應,視覺同 disabled(uniform dim)——但語義是「正在取得既有評分 / 正在儲存」,非永久不可互動 | `aria-busy="true"`(screen reader 宣告「忙碌中」) |
+
+**判斷法**:
+- **送出前 = interactive**,**送出後 / 顯示他人評分 = readOnly**。
+- **loading 跟 disabled 視覺相同但語義不同**:loading = 暫時性(fetch / save in flight);disabled = 永久性業務規則(例:評分期限已過)。screen reader 會區分(`aria-busy` vs `aria-disabled`)。
+
+一顆星 Rating 同時給自己評和看別人評的常見錯誤是都用 interactive——使用者會誤以為可以改別人的分數。
+
+### Loading canonical(composite 元件 opacity pattern)
+
+Rating 是**複合 element**(多顆星共同組成評分值),loading 走 **composite 整塊 dim** 策略(對齊 FileUpload / Sidebar menu row),**不**套 skeleton 替換星星:
+- **為什麼不 skeleton**:星星數是 schema(`max=5`)不是 data,loading 中消失變成「動態結構」,使用者誤以為星星數本身在變
+- **為什麼不 spinner**:會與 readOnly 圖示混淆;loading 是**暫時性等待**不是「純展示」
+
+API:`loading?: boolean` prop(對齊 `../Field/field-controls.spec.md` Field 家族 loading canonical,但這裡採 composite dim 非 endAction spinner)。
+
+---
+
+## 視覺 Token
+
+| Role | Token | 色值（light） | 說明 |
+|------|-------|--------------|------|
+| Filled star | `var(--warning)` | yellow-6 | 世界級黃星 convention（Amazon / Yelp / Google / Shopify / Airbnb 都是黃）| <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| Empty star | `var(--color-neutral-4)` | 中灰 | 未填的輪廓色，與 disabled / empty state 同級 |
+| Hover 放大 | `scale-110` + `transition-transform` | — | interactive 時 hover 單顆星放大 10%，給予 preview 回饋 |
+| Focus ring | `ring-2 ring-ring ring-offset-2` + `rounded-md` | — | 鍵盤 focus 時整個 Rating 容器顯示 focus ring（**per-star 無 ring / border / outline**——focus 視覺由 parent container 統一承擔）|
+| Gap between stars | `gap-1` | 4px | 五顆星之間的間距，不隨 size 變化 |
+| Disabled | `opacity-disabled` + `pointer-events-none` | — | 整體降透明度，阻擋所有事件 |
+
+### Star icon 無 stroke outline
+
+Star icon 渲染時明確設 `stroke="none"`(Lucide Star 預設有 1.5px outline stroke,保留會讓 filled 星星多一層深色 outline,破壞純 fill-only shape canonical)。**Rating 是純 fill-only shape**,不保留 outline——對齊 Ant Rate / Material MUI Rating 的世界級慣例。Empty star 靠 `--color-neutral-4` 的 fill 本身與 canvas 對比區隔,不需 outline 補視覺。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+### 為什麼用 `--warning`（黃色）而不用 `--primary`
+
+黃星是**世界級 convention**——Amazon / Yelp / Google Reviews / Shopify / Airbnb / TripAdvisor 全部用黃。使用者的視覺記憶已經把「黃星 = 評分」綁定，換成品牌 primary 色（藍、綠、紫）會破壞這個直覺。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+`--warning` 在本系統指向 yellow-6，與 Rating **共用色相但語境不同**——evaluation convention color，非 status color。這是 documented 例外（見 `color.spec.md`），不是每個元件都能這樣共用。
+
+---
+
+## A11y 預設
+
+- **interactive**：`role="slider"` + `aria-valuenow={value}` + `aria-valuemin={0}` + `aria-valuemax={max}` + `tabIndex={0}`，鍵盤 Arrow Left/Right/Up/Down 改值（precision=half 時 step=0.5，否則 step=1）
+- **readOnly**：`role="img"` + `aria-label`（**必填**），例：`aria-label="平均評分 4.7 星，共 5 星"`。無 tabIndex
+- **disabled**：`aria-disabled="true"` + `pointer-events-none`
+- **單顆星** `aria-hidden`：所有內部 `<button>`（包含 half-precision 的兩個 hover zone）都是 `aria-hidden` 不干擾螢幕閱讀器，父層 role 獨自表達語意
+
+---
+
+## 禁止事項
+
+- ❌ **不用其他色相填充**（藍 / 綠 / 紫 / 紅）——黃星是世界級 convention，破壞使用者的視覺記憶
+- ❌ **不換成 Heart / ThumbsUp / ThumbsDown icon**——那是 like / dislike 的 binary 表達，不是 graded rating。愛心用 `Button iconOnly startIcon={Heart} pressed={liked}`
+- ❌ **`readOnly` 必填 `aria-label`**——純視覺的星星螢幕閱讀器讀不出「4.7 分」
+- ❌ **不用 Rating 做 progress bar**——Rating 語意是「給分」，用「填了 4 顆星」表達「完成 4/5 步」會誤導
+- ❌ **不用於 binary 情境**（「喜歡 / 不喜歡」）——改用 Switch 或 thumbs icon button
+- ❌ **interactive 狀態下不與 `Field` 的 `Label` 分離超過一個 section**——使用者要清楚「這個評分屬於誰 / 哪個面向」
+- ❌ **`max` 不設超過 7**——超過使用者無法快速掃視，若需更細分度改用 Slider（連續 0–100）
+- ❌ **send-form 用 `precision="half"`**——送出評分選半星會讓使用者猶豫（`4` 跟 `4.5` 差在哪？）；半星只用於展示平均值
+
+---
+
+## 相關
+
+- **`Slider`** — 連續數值選擇（0–100、音量、亮度、價格區間）。Rating vs Slider 分界：離散 tier = Rating，連續值 = Slider
+- **`Badge`** — 靜態分類標記（「熱門」「Beta」「NEW」）。Rating 是量化，Badge 是分類
+- **`Switch`** — 二元 on/off。Rating 是 graded，Switch 是 binary
+- **`Button iconOnly + pressed={liked}`** — 愛心 / like 的正確實作
+- **Color token 例外** — `color.spec.md`「共用 `--warning` 色相但語境不同」段落
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `uiSize.spec.md`