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

package/src/components/Slider/slider.spec.md

@@ -1,19 +1,19 @@
 ---
 component: Slider
-family: 4
+family: self-contained
 variants: {}
 sizes:
   sm:
     px: 28
-    when: "Toolbar / inline 編輯;對齊 field-height-sm"
+    when: "Toolbar / inline 編輯;對齊 field-height-sm(md density)"
     world-class: ["VS Code zoom slider", "Figma toolbar inline"]
   md:
-    px: 36
-    when: "預設 — Form + 設定面板 + DataTable cell inline edit"
+    px: 32
+    when: "預設 — Form + 設定面板 + DataTable cell inline edit;對齊 field-height-md(md density)"
     world-class: ["Material Slider default", "Polaris RangeSlider", "Ant Slider"]
   lg:
-    px: 44
-    when: "Marketing hero 互動 / 高 touch 區"
+    px: 36
+    when: "Marketing hero 互動 / 高 touch 區;對齊 field-height-lg(md density)"
     world-class: ["Apple HIG slider touch zone"]
 traits:
   - hasSizes
@@ -25,8 +25,6 @@ benchmark:
   - MUI Slider: github.com/mui/material-ui/tree/master/packages/mui-material/src/Slider
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
-
 # Slider 設計原則
 
 **數值範圍選取器**——基於 Radix Slider primitive,橋接設計系統 token。
@@ -66,28 +64,9 @@ benchmark:
 
 ### 一種視覺,多種容器尺寸
 
-**Slider 的視覺是固定的**——track 厚度、thumb 直徑、focus ring 都是單一值,不會隨 `size` 變動。這是跟 Button / Input 等元件的明顯差異,理由是:
-
-- Slider 的 thumb 必須足夠容易被手指 / 鼠標捕捉,改小會降低可用性
-- 連續拖曳的 track 太細會看不清楚 range
-- 業界(Material / Ant / Radix Themes / shadcn)都只有一組 thumb / track 視覺,不做多尺寸
-
-**但**,Slider 可以被丟進 `Field` 容器跟 `Input` / `Select` / `NumberInput` 等並排,這時它**必須跟該 Field 的 `size` 對齊高度**(否則一排 sm field 裡混一個 md 高度的 slider,breakline rhythm 會崩)。
-
-### 解決方式:`size` prop 只控容器外高
-
-Slider 接收 `size?: 'sm' | 'md' | 'lg'` prop(預設 `md`),**這個 prop 只決定 root 容器的 `h-field-*` class**,不改變 track 厚度、thumb 直徑、ring 尺寸。內部視覺元素透過 flex `items-center` 在容器中**垂直置中**,所以不論容器高度是 28 / 32 / 36 px,track 和 thumb 的位置都在中間,視覺體驗一致。
-
-這樣做的效果:
-- 視覺:一種尺寸,任何 Field context 長得都一樣
-- 對齊:完美對齊 Field family 的 field-height tier
-- API 一致性:跟 Input / NumberInput 同樣有 `size` prop,消費者不需要特別記「Slider 沒有 size」
-
-### 為什麼不完全對齊 `--field-height-*`
+**track / thumb 是單一視覺規格**(track 4px、thumb 16px、邊框 2px,皆不隨 `size` 變):thumb 是位置指示器，必須夠大才容易捕捉；等比縮小會直接降低命中率。因此 `size` 只調整容器與 Field 的對齊高度，thumb / track 保留同一操作量體。
 
-- **現況**:容器高 = `--field-height-sm/md/lg`(對齊);track 厚度固定 4px / thumb 直徑固定 16px / focus ring 固定 2px,**皆不隨 size 變化**(偏離 size-proportional scaling)
-- **Rationale**:Slider 的 thumb 是「位置指示器」,必須足夠大好捕捉(Fitts's Law);縮小成比例(sm=12 / lg=20 之類)會讓 sm 幾乎無法精確拖曳。業界共識:track/thumb 是**單一視覺規格**,`size` 只控容器外高讓 Slider 並排對齊,內部透過 `flex items-center` 垂直置中
-- **世界級對照**:Material 3 Slider(track 4dp thumb 20dp 固定)/ iOS UISlider(track 3pt thumb 28pt 固定)/ Ant Design Slider(track 4px thumb 14px 固定)/ Radix Slider(default 4px track)——全部 thumb / track 尺寸獨立於 form-size system <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+`size?: 'sm' | 'md' | 'lg'`(預設 `md`)**只控 root 容器外高 `h-field-*`**,內部視覺 `flex items-center` 垂直置中——Slider 丟進 `Field` 與 Input / Select / NumberInput 並排時對齊 field-height tier(否則一排 sm field 混一個 md 高 slider,rhythm 會崩),同時保持「一種尺寸,任何 context 長得都一樣」;API 與其他 field 元件一致(都有 `size`),消費者不需特別記「Slider 沒有 size」。focus 不加 ring / halo,改用 border 階變(詳「視覺規格」表)。
 
 ---
 
@@ -95,34 +74,28 @@ Slider 接收 `size?: 'sm' | 'md' | 'lg'` prop(預設 `md`),**這個 prop 只決
 
 | 元素 | 值 | Token |
 |---|---|---|
-| **Track** 厚度 | 4px(`h-1`) | — |
+| **Track** 厚度 | 4px | — |
 | **Track** 底色 rest | `bg-secondary` | `--secondary`(neutral-3,跟 Tag neutral / Badge low 同級「微淡可辨」)|
 | **Track** 底色 disabled | `bg-muted` | `--muted`(neutral-2,disabled-like 退化)|
 | **Range** 填滿色 rest | `bg-primary` | `--primary` |
 | **Range** 填滿色 disabled | `bg-border`(neutral-5)| `--border` |
-| **Thumb** 直徑 | 16px(`h-4 w-4`) | — |
-| **Thumb** 底色(rest + disabled 不變)| `bg-surface`(白) | `--surface` |
-| **Thumb** 邊框 rest | `border-2 border-primary`(= Range rest 同色)| `--primary` |
+| **Thumb** 直徑 | 16px | — |
+| **Thumb** 底色 rest | `bg-on-emphasis`(白,深淺主題不反轉;對齊 Switch thumb / Radix Themes / iOS) | `--on-emphasis` |
+| **Thumb** 底色 disabled | `bg-canvas`(不透明頁面背景色,沉回背景;= Radix disabled thumb gray-1 同款) | `--canvas` |
+| **Thumb** 邊框 rest | 2px,色 = Range rest 同 token | `--primary` |
 | **Thumb** 邊框 disabled | `border-border`(= Range disabled 同色)| `--border` |
-| **Thumb** hover | border `primary-hover` + 陰影 `--elevation-100` | `--primary-hover` |
-| **Thumb** active | 陰影 `--elevation-200` | — |
-| **Focus ring** | `ring-2 ring-ring ring-offset-2 ring-offset-background` | `--ring` |
+| **Thumb** hover | border 升 hover 階(light mode 淺一階 lift,= Button primary hover 邏輯)+ 陰影 `--elevation-100` | `--primary-hover` |
+| **Thumb** active(按壓拖曳) | border 深一階 `primary-active`(= Button active 邏輯;2026-07-06 修:原誤用 hover 階,全 DS 唯一 active-用-hover 偏移)+ 陰影 `--elevation-200` | `--primary-active` |
+| **Thumb** focus | border 同 hover 視覺(`outline-none focus-visible:border-primary-hover`,不加 ring / halo)| `--primary-hover` |
 | **Disabled cursor** | `cursor-not-allowed` + hover 陰影關閉 | — |
 
 ### 為什麼 thumb 是**白底 + 邊框**,不是**實心 primary**
 
-實心 primary thumb 會讓 thumb fill 與 range fill 使用同一 token → 失去位置辨識語意(特別是 range mode 兩個 thumb 與 primary range 共存時)。白底 + 邊框讓 thumb 與 range 視覺可區分——thumb 作為位置指示器,必須能從 range 中辨別。這是 Material 3 / iOS / Linear 的共同解法。
+實心 primary thumb 會讓 thumb fill 與 range fill 使用同一 token → 失去位置辨識語意(特別是 range mode 兩個 thumb 與 primary range 共存時)。白底 + 邊框讓 thumb 與 range 視覺可區分——thumb 作為位置指示器,必須能從 range 中辨別。
 
-### 為什麼 Track 永遠是 `bg-muted`,不跟 state 變動
+### 為什麼 Track 底色維持「灰色凹槽」身分,不跟 enabled state 變動
 
-Track 是「凹槽底線」,它的視覺角色是「告訴使用者這條線是 slider 可滑動範圍」——這個語意不會因為 enabled / disabled 改變,所以**顏色也不該變**。當整個 slider 被 disable 時,Range 和 Thumb border 會降級(rest 的 primary → border),但 Track 的灰色凹槽身分始終不變。
-
-為什麼用 `bg-muted` 而非其他 token?
-- `--muted` 是 semantic token,屬於「shadcn Badge / skeleton 底色」家族,語意歸屬明確
-- 是最淡的 subtle bg,符合「track 是背景凹槽,不是主角」的視覺層級
-- **優先用 semantic token,不直接引用 primitive**——這是系統的基本原則
-
-> **若覺得 `--muted` 在 white canvas 上太淡**,那是 `--muted` 本身的系統級議題,應該統一調整 `--muted` 的定義(影響 Badge / skeleton / Slider 一起),而不是在 Slider 裡偷偷用 primitive `--color-neutral-3` 繞過。
+Track 的視覺角色是「可滑動範圍的凹槽底線」,語意不因 enabled / disabled 改變——rest `bg-secondary`(neutral-3)、disabled 退一階 `bg-muted`(neutral-2),都在最淡 subtle bg 層級、凹槽身分不變(disable 時 Range / Thumb border 同步降級 primary → border)。semantic token 優先、不直接引 primitive;**若覺得 track 在 white canvas 上太淡**,那是 `--secondary` / `--muted` 的系統級議題(Badge / Skeleton 一起調),不是在 Slider 裡用 primitive 繞過的理由。
 
 ### Range 色 ↔ Thumb border 色的綁定規則
 
@@ -133,13 +106,11 @@ Range 填滿色和 Thumb border 色**永遠是同一個 token**:
 | Rest | `bg-primary` | `border-primary` | `--primary` |
 | Disabled | `bg-border` | `border-border` | `--border` |
 
-**為什麼綁在一起**:thumb 坐落在 range 的端點上,border 是 range 的視覺延續;兩者同色讓 thumb 作為「range 的終點標記」而非獨立元素,對齊物理滑桿 handle 屬於軌道一部分的 mental model(具體視覺呈現見 `.principles.stories.tsx` 的 ThumbBindingRule)。
-
-**強制規則**:未來若要改 Range 的 disabled 色(例如加新 variant),必須同步改 Thumb border。不要讓兩者漂移。
+**為什麼綁在一起**:thumb 是 range 的端點標記、border 是 range 的視覺延續(物理滑桿 handle 屬於軌道的 mental model;呈現見 principles `ThumbBindingRule`)。**強制規則**:改 Range 任一 state 色必同步 Thumb border,不許漂移。
 
 ### 為什麼 hover / active 用陰影不用色變
 
-Slider 不是 button——它是「當前位置指示器」,底色不該動(動了會暗示是另一個狀態)。陰影(elevation)是世界級 slider 的標準 hover 語言:Material 3 的 state layer + elevation、iOS slider 的 scale + shadow、Linear 的 drop shadow。對齊 `elevation.spec.md` 的 `--elevation-100` / `--elevation-200`。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+Slider 不是 button——它是「當前位置指示器」,底色不該動(動了會暗示是另一個狀態);「不用色變」指 thumb 底色與 range 填色;thumb border 仍有同色相變化:hover / focus 升 hover 階(淺一階 lift)、按壓拖曳深至 `primary-active`(2026-07-06 修語:原文「加深至 primary-hover」與 token 實際方向相反,見視覺規格表)。陰影只提供深度與拖曳回饋，對齊 `elevation.spec.md` 的 `--elevation-100` / `--elevation-200`，不改寫數值 state 的色彩。
 
 ---
 
@@ -150,20 +121,22 @@ Slider 不是 button——它是「當前位置指示器」,底色不該動(動
   value={number[]}                 // controlled
   defaultValue={number[]}          // uncontrolled
   onValueChange={(value) => void}
-  onValueCommit={(value) => void}  // 放開滑鼠時才觸發
+  onValueCommit={(value) => void}  // 互動結束觸發:滑鼠放開,或鍵盤 Arrow/Page/Home/End 每次有效變更
   min={number}                     // 預設 0
   max={number}                     // 預設 100
   step={number}                    // 預設 1
   size="sm" | "md" | "lg"          // 預設 md(只影響容器外高)
   disabled={boolean}
-  orientation="horizontal"         // 不支援 vertical(用 TickSlider / 垂直尺若未來需要再擴充)
   minStepsBetweenThumbs={number}   // range mode 時兩個 thumb 的最小距離
 />
 ```
 
+- **不支援 vertical**:`orientation` 已自型別排除(`slider.tsx` `Omit<..., 'orientation'>`);DS 尚無垂直變體,未來真有需求再擴充。
+- **`value` / `defaultValue` 必為非空陣列**:至少一個元素(`[single]` 或 `[min, max]` range)。傳空陣列 `[]` 時 Radix 無對應值會隱藏 thumb,留下沒有可操作 thumb 的空軌道 → `slider.tsx` 正規化為 `[min]`(`min` 未傳時為 `0`),保證至少一個坐落在 `min` 的可操作 thumb。省略值(不傳 `value` / `defaultValue`)時走 Radix 預設單 thumb。
+
 ### Range mode(雙 thumb)
 
-Radix Slider 原生支援多 thumb——只要 `value` / `defaultValue` 傳長度 > 1 的 array,就自動渲染對應數量的 thumb,range(填滿段)落在最小和最大 thumb 之間。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+底層 Slider 支援多 thumb——只要 `value` / `defaultValue` 傳長度 > 1 的 array,就自動渲染對應數量的 thumb,range(填滿段)落在最小和最大 thumb 之間。
 
 ```tsx
 // 單值
@@ -191,37 +164,21 @@ Radix Slider 原生支援多 thumb——只要 `value` / `defaultValue` 傳長
 
 | State | 視覺 | 觸發 |
 |---|---|---|
-| Rest | track `bg-muted`,range `bg-primary`,thumb `bg-surface + border-primary` | 預設 |
-| Hover(thumb) | 加 `--elevation-100` 陰影 | 滑鼠 hover 在 thumb 上 |
-| Active(拖曳中) | 加 `--elevation-200` 陰影 | 按住拖曳 |
-| Focus | `ring-2 ring-ring ring-offset-2` | 鍵盤 Tab 聚焦 |
-| Disabled | 灰階降級:range `bg-border`、thumb `border-border`(= range 同 token)、thumb bg 保留 `bg-surface` 白底、`cursor-not-allowed`、hover 陰影關閉 | `disabled` prop 或 Field context disabled |
+| Rest | track `bg-secondary`,range `bg-primary`,thumb `bg-on-emphasis + border-primary` | 預設 |
+| Hover(thumb) | thumb border 升 hover 階 `primary-hover` + 加 `--elevation-100` 陰影 | 滑鼠 hover 在 thumb 上 |
+| Active(拖曳中) | border 深一階 `primary-active` + 加 `--elevation-200` 陰影 | 按住拖曳 |
+| Focus | thumb border 升 hover 階 `primary-hover`(跟 hover 同視覺,不加 ring / halo)| 鍵盤 Tab 聚焦 |
+| Disabled | 灰階降級:range `bg-border`、thumb `border-border`(= range 同 token)、thumb bg 沉回 `bg-canvas`(不透明背景色)、`cursor-not-allowed`、hover 陰影關閉 | `disabled` prop 或 Field context disabled |
 
 **Mode / readonly / dark mode / density** 詳見 `../Field/field-controls.spec.md`(Slider 作為 Field 家族整合時繼承其 canonical;semantic token 自動處理 dark mode,無需元件內特殊 handling)。
 
-### Disabled 視覺階層
-
-```
-track (muted, n-2) < range = thumb border (border, n-5) < text (n-7+)
-```
-
-**三階**,不是四階。Range 和 Thumb border 刻意用同一個 token(見前面「Range 色 ↔ Thumb border 色的綁定規則」),不拆成兩階。
+### Disabled 視覺階層(三階,不是四階)
 
-- **Track n-2**:最底的凹槽底線
-- **Range + Thumb border n-5**:同層——thumb border 是 range 的連續視覺,兩者融為一體;thumb 的 fill 保持 surface 色,與 range fill 對比,位置由 range 的長度段決定
-- **Text n-7+**:label / description 在所有視覺元件之上
+`track(muted, n-2)< range = thumb border(border, n-5)< text(n-7+)`——Range 與 Thumb border 刻意同 token 不拆階(見綁定規則);thumb fill(rest 白 / disabled canvas)與 range fill 對比、位置由 range 長度段決定;text 永遠最上層。
 
-### 為什麼 range disabled 不用 `--fg-disabled`
+### 為什麼 range disabled 用 `--border` 不用 `--fg-disabled`
 
-`--fg-disabled`(neutral-6)的語意是「**disabled 狀態下的文字前景色**」,它存在的目的是讓 disabled text 有足夠對比度可讀。把它拿來當 range 的 background 是**混用 fg token 當 bg 色**——在設計系統語意上是 smell,偶然 work 只是因為 neutral-6 剛好是我想要的深度。
-
-正確選擇是 `--border`(neutral-5):
-- **語意對**:`--border` 屬於 Border family,「視覺分隔 / 容器邊框」語意,跟 range 的「填充視覺指示器」角色接近
-- **Family 對**:非文字的視覺元素,不借用 fg family
-- **可同時作為 border-color**:`border-border` 在 Thumb 上直接用,Range bg 跟 Thumb border 可共享同一個 token(這是綁定規則的前提)
-- **跟 fg-disabled 解耦**:未來若 `--fg-disabled` 被微調,Slider 不會被拖著一起變
-
-詳細的 fg / bg token family 借用規則見 `tokens/color/color.spec.md` 的「fg token 不可當 bg 用」節。
+`--fg-disabled` 是「disabled 文字前景」語意,拿來當 bg = fg token 混用當 bg 的 smell(偶然 work 只因 neutral-6 深度剛好)。`--border`(neutral-5)語意對(視覺分隔家族、非文字元素不借 fg)、可同時作 Thumb 的 border-color(綁定規則的前提)、與 fg-disabled 解耦。詳 `tokens/color/color.spec.md`「fg token 不可當 bg 用」節。
 
 ---
 
@@ -229,45 +186,26 @@ track (muted, n-2) < range = thumb border (border, n-5) < text (n-7+)
 
 **Slider 用灰階不用 opacity**。這是系統內重要的判準,反覆確認後的結論——系統有兩個 disabled 處理派別,Slider 屬於**灰階派**(跟 Button / Checkbox 同家族)。判準比「多色彩 vs 單色彩」更精準,是:
 
-### 判準:**顏色是否是 semantic state 的唯一載體?**
+### 判準:**顏色是否是 semantic state 的主載體?**
 
 | 元件 | 顏色的角色 | State 載體 | Disabled 策略 |
 |---|---|---|---|
-| **Switch** | `bg-primary` vs `bg-border` 是 on/off 的**唯一視覺差異**(track 和 thumb 形狀在 on/off 之間完全相同,只有顏色變)| **顏色本身就是 state** | **`opacity-disabled`** — 必須保留色彩身分,否則灰階後失去狀態區辨 |
+| **Switch** | `bg-primary` vs `bg-border` 是 on/off 的**最強視覺差異**(thumb 位移與 check icon 只是弱輔助線索,灰階低對比下難辨——見 switch.spec.md「Disabled 用 opacity」)| **顏色是 state 主載體** | **`opacity-disabled`** — 必須保留色彩身分,否則灰階後狀態區辨大幅下降 |
 | **Checkbox** | 勾了有 checkmark,沒勾沒 checkmark——**形狀**決定 state,顏色只是美學 | **形狀(checkmark)** | **灰階 swap**(`bg-disabled`)— 灰色框裡的 checkmark 仍清楚可辨 |
 | **Button** | Primary 色是品牌美學,不是 state | — | **灰階 swap** |
 | **Slider** | Range 藍色是「已選長度」的美學視覺,**位置 + 長度是 state**,顏色只是裝飾 | **位置(thumb)+ 長度(range 佔比)** | **灰階 swap** — 灰色 range 跟灰色 thumb 的位置/長度仍然完全可辨 |
 
-### Slider 的完整論證
-
-使用者看到 disabled slider 需要理解兩件事:
-1. **Thumb 在 track 的哪個位置**(例如「60% 處」)
-2. **Range 的填滿長度**(例如「20% 到 80%」)
-
-這兩個資訊**完全不依賴顏色**:
-- 灰階 thumb 在灰階 track 上,x 座標位置跟 primary 版本一模一樣
-- 灰階填滿段的長度跟 primary 版本一模一樣
-
-**失去藍色沒有任何資訊損失**。Slider 跟 Checkbox 同類——semantic state 由形狀/位置承載,顏色是純裝飾。
+### 論證摘要
 
-### 對照 Switch 的差異
+Disabled slider 要傳達的兩件事——thumb 位置、range 長度——**完全不依賴顏色**(灰階後 x 座標與填滿佔比一模一樣),失去藍色零資訊損失,故走灰階派(同 Checkbox:state 由形狀 / 位置承載、顏色是裝飾)。Switch 是唯一 opacity 特例:on/off 的主載體是顏色(thumb 位移 / check icon 只是弱輔助線索),灰階會讓兩態近乎無法區分——此 rationale 不適用 Slider。
 
-Switch 是**唯一需要 opacity 的特例**,因為它的 on/off 沒有任何形狀差異:
-- On:track + thumb
-- Off:track + thumb(同樣形狀,thumb 在不同位置)
+### 為什麼不直接套 opacity
 
-唯一的 state 視覺載體是 track 顏色(primary vs border)。灰階 swap 會讓 on/off 視覺無法區分——必須靠 opacity 保留顏色。
-
-**這個 rationale 不適用 Slider**,因為 Slider 的 state 載體不是顏色。
-
-### 為什麼 shadcn / Material 3 用 opacity 仍然不是理由
-
-- **shadcn 的 Slider 用 `opacity-50`**:shadcn 追求「最短 code path」,不是「設計嚴謹」,它對所有 disabled 元件都 lazy-apply opacity。這是實作偷懶,不是 design decision。
-- **Material 3 的 38% opacity 全局規則**:M3 是為 Android 生態系設計的,opacity-based disabled 能跟 Android 原生控件的視覺一致。我們的系統是 web,不受此約束,且 Button / Checkbox / Input 已經選了灰階路線,Slider 跟進對齊才是 system consistency 的正確解。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+Opacity 會同時削弱 track、range、thumb 與邊框，讓元件所有層級一起沉沒；而本 DS 已有明確的 disabled semantic tokens。Slider 跟 Button / Checkbox / Input 使用灰階 swap，保留 thumb 位置與 range 長度的結構對比，也避免「灰階後再整體透明」的雙重降級。
 
 ### 常見錯誤(避免)
 
-**不要把 thumb 的 disabled bg 改成 `bg-muted`**——`--muted` 和 `--bg-disabled` 在這個系統都等於 `var(--color-neutral-2)`,同一個顏色。Thumb `bg-muted` 會跟 track `bg-muted` 完全融色,只剩 border 可見,失去 thumb 形狀辨識(真實踩過的 bug)。**保留 `bg-surface` 白底**,只改 border 顏色即可達成降級。
+**不要把 thumb 的 disabled bg 改成 `bg-muted`**——`--muted` 和 `--bg-disabled` 在這個系統都等於 `var(--color-neutral-2)`,同一個顏色。Thumb `bg-muted` 會跟 track `bg-muted` 完全融色,只剩 border 可見,失去 thumb 形狀辨識(真實踩過的 bug)。Disabled 用 **`bg-canvas`**(不透明頁面背景色,與 track 的 muted 不同值且隔 n-5 邊框,不融色)。2026-06-12 補:rest 態原為 `bg-surface`,但 `--surface` 深色 = 8% 白半透明 → thumb 在深色變破洞且 track 穿透,故改 `bg-on-emphasis`(固定白不反轉)。
 
 **不要同時套 opacity + 灰階 swap**——兩個策略互斥,同時用會導致「灰階 swap 後再打 opacity 一層」,視覺雙重降級,整個 slider 褪色過度。選一條路走到底。
 
@@ -275,9 +213,13 @@ Switch 是**唯一需要 opacity 的特例**,因為它的 on/off 沒有任何形
 
 Slider 沒有獨立的 error 視覺——拖曳選值本身不太會「無效」。如果業務邏輯需要限制範圍,用 `min` / `max` 直接限制使用者能拖到的範圍,不要讓他拖到再報錯。
 
-### 無 readonly mode
+### 無 Loading state(N/A)
+
+Slider 是**同步輸入 primitive**,thumb 上不加 spinner。值本身即為當前狀態,沒有「載入中的值」這種中間態。若資料尚未就緒(例如初始範圍要等 API 回),loading 由父層或 `Field` 擁有(在 Field 層顯示 skeleton / spinner),Slider 本身只在值到位後渲染——不在 thumb / track 疊加載入視覺。
 
-Slider 的 `readonly` 等同於 `disabled`——一個不能操作的 slider 本質上就是 disabled。不同於 Input 有「可以 focus 但不能改」的 readonly 差異,slider 的 focus 除了拖曳沒有其他行為。若要顯示「歷史值」,用純文字或另一個 display 元件。
+### Readonly(僅 Field cascade,無獨立 prop)
+
+Slider 無獨立 `readOnly` prop;但在 `<Field mode="readonly">` 內(2026-06-12 拍板)= **鎖互動、保留正常視覺**(pointer-events-none + thumb tabIndex=-1 + aria-readonly on thumb;值仍可讀、不降色——readonly ≠ disabled)。理由:readonly 表單中 Slider 的值(thumb 位置 + range 長度)本身就是 value 呈現。若要在非表單情境顯示「歷史值」,用純文字或另一個 display 元件。
 
 ---
 
@@ -293,6 +235,14 @@ Slider 的 `readonly` 等同於 `disabled`——一個不能操作的 slider 本
 
 ---
 
+## 常見誤解
+
+- 「Slider 可以當計數器」——錯。Slider 傳達 position(在哪裡),計數(多少)用 NumberInput ±step(見「何時不用」)
+- 「兩個選項可以用 Range mode」——錯。Range 是連續值區間(value = [start, end]),二元 / 布林選擇用 Switch / SegmentedControl
+- 「focus 要加 ring」——本元件 documented 例外:focus 用 border 升 hover 階(`primary-hover`,淺一階 lift;同 hover 視覺),不加 ring / halo(見「視覺規格」表,對齊上方「為什麼 hover / active 用陰影不用色變」)
+
+---
+
 ## Do / Don't
 
 ✅ **Do**
@@ -311,13 +261,9 @@ Slider 的 `readonly` 等同於 `disabled`——一個不能操作的 slider 本
 
 ---
 
-## 為何無 Inspector
-
-Slider 決策維度是 `size`(容器外高)× `range mode`(single / range)× track / range / thumb 的色彩綁定規則——已由 `SizeMatrix` / `StateBehavior` / `ColorMatrix` / 元件特有 `ColorBindingRule`(range ↔ thumb border 綁定規則) / `KeyboardMatrix`(Radix 原生鍵盤) 五張 story 完整覆蓋。
+## Inspector 用途
 
-互動 Inspector 拉動 thumb 無法呈現「range 色和 thumb border 永遠同 token」這類設計綁定規則——這是 side-by-side 對照題,不是單值拉動題。鍵盤互動已由 `KeyboardMatrix` 以對照表呈現比 Inspector 試玩更完整。
-
-對應 anatomy story:保留 `Overview` + `ColorMatrix` + `SizeMatrix` + `StateBehavior` + 元件特有 `ColorBindingRule` + `KeyboardMatrix`。
+Inspector 提供 `min` / `max` / `step` / `defaultValue` × `size` 即時調整(track / thumb 視覺固定,只有容器外高隨 size 變);色彩綁定 / 鍵盤等 side-by-side 對照題由各 matrix story 覆蓋。對應 anatomy story:`Overview` + `Inspector` + `ColorMatrix` + `SizeMatrix` + `StateBehavior` + 元件特有 `ColorBindingRule` + `KeyboardMatrix` + `Accessibility`。
 
 ---
 
@@ -335,14 +281,15 @@ Slider 決策維度是 `size`(容器外高)× `range mode`(single / range)× tra
 
 **ARIA / Pattern**:繼承 Radix `slider` primitive a11y 預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/slider#accessibility)。
 
-**Keyboard 行為**:
+**Accessible name(命名,強制)**:`role="slider"` 的 thumb **必須有 accessible name**,否則螢幕閱讀器只讀出數值、不知這是「什麼」的值。Radix 對**單 thumb 不會自動產生名稱**(只有 2+ thumb 才給 Minimum / Maximum 泛稱)。命名三層(`slider.tsx` 已實作,由高到低優先):
+
+1. **consumer `aria-label`**:standalone(不在 Field 內)的 Slider **必傳** `aria-label`(例:`<Slider aria-label="音量" />`);多 thumb 時自動展開為 `{label} (1)` / `{label} (2)` 區分各 thumb。
+2. **Field 自動接線**:包在 `<Field>` 內且未傳 `aria-label` 時,thumb 自動 `aria-labelledby` 接 `FieldLabel`(元件讀 `fieldCtx.labelId`)——此情境不需另傳 `aria-label`。
+3. **Radix fallback**:兩者皆無時,2+ thumb 由 Radix 提供 Minimum / Maximum 泛稱;單 thumb 則**無名稱**(= 需靠上面兩層補)。
 
-- Tab — focus thumb
-- ←/→ — 微調
-- Home/End — min/max
-- PageUp/Down — 大步階
+**Keyboard 行為**:完整鍵盤對照見上方「鍵盤操作(Radix 原生,免手工)」節,不重複列。
 
-**Focus**:Radix primitive 自管 focus trap / restoration / visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。
+**Focus**:Radix primitive 自管 focus / restoration;thumb 鍵盤聚焦時 `outline-none focus-visible:border-primary-hover`(border 升 hover 階,跟 hover 同視覺,不加 ring / halo)。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
@@ -350,4 +297,5 @@ Slider 決策維度是 `size`(容器外高)× `range mode`(single / range)× tra
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `number-input.spec.md`
 - `switch.spec.md`

package/src/components/Slider/slider.stories.tsx

@@ -0,0 +1,115 @@
+// @story-history: hasSizes 由 anatomy.stories.tsx SizeMatrix auto-compile owns size showcase(2026-05-15 F-migration)。
+import * as React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Slider } from './slider'
+import { NumberInput } from '@/design-system/components/NumberInput/number-input'
+
+const meta: Meta<typeof Slider> = {
+  title: 'Design System/Components/Slider/展示',
+  tags: ['autodocs'],
+  component: Slider,
+  parameters: {
+    layout: 'padded',
+    docs: { description: { component: '在連續範圍內以拖曳方式調整單一數值，並提供鍵盤操作。適合音量、強度或大致偏好等即時回饋情境；需要精確輸入時搭配 NumberInput。' } },
+  },
+}
+export default meta
+
+type Story = StoryObj<typeof Slider>
+
+// @story-history: Default / Range retired 2026-05-17 per audit Dim 24 —
+//   anatomy.stories.tsx Overview(含 Anatomy + Range mode 子段)已 cover baseline + range showcase。
+//   展示層保留 typical 情境(SizeAlignment / MinMaxStep / Disabled 等),避免跟 anatomy 重複。
+
+// ── Sizes(容器對齊)───────────────────────────────────────────────────
+
+export const SizeAlignment: Story = {
+  name: '容器尺寸對齊',
+  render: () => (
+    <div className="w-[420px] flex flex-col gap-6">
+      <p className="text-caption text-fg-secondary max-w-[480px]">
+        三個 size 下 track 厚度與 thumb 直徑一致——只有容器外高跟著
+        `--field-height-*` 變。這讓 Slider 能在同一列跟 NumberInput 等 field
+        控件並排、field-height 完美對齊,同時保持自己的視覺身分不變。
+      </p>
+      {(['sm', 'md', 'lg'] as const).map(size => (
+        <div key={size} className="flex flex-col gap-2">
+          <div className="text-caption text-fg-muted">size = {size}</div>
+          <div className="flex items-center gap-3">
+            <span className="text-body w-10 shrink-0">音量</span>
+            <Slider size={size} defaultValue={[40]} aria-label="音量" className="flex-1" />
+            <NumberInput size={size} value={40} onChange={() => {}} aria-label="音量數值" className="w-20 shrink-0" />
+          </div>
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+// ── Min / Max / Step ─────────────────────────────────────────────────────
+
+export const MinMaxStep: Story = {
+  name: '最小 / 最大 / 步階',
+  render: () => {
+    const [quality, setQuality] = React.useState([80])
+    return (
+      <div className="w-[360px] flex flex-col gap-4">
+        <p className="text-caption text-fg-secondary">
+          匯出圖片品質——限制在 10–100% 之間,每次以 5% 為一階(min / max / step)
+        </p>
+        <div className="flex items-center gap-3">
+          <span className="text-body w-16 shrink-0">圖片品質</span>
+          <Slider
+            value={quality}
+            onValueChange={setQuality}
+            min={10}
+            max={100}
+            step={5}
+            aria-label="匯出圖片品質"
+            className="flex-1"
+          />
+          <span className="text-caption text-fg-muted font-mono w-10 shrink-0">{quality[0]}%</span>
+        </div>
+      </div>
+    )
+  },
+}
+
+// @story-history: Disabled retired 2026-05-17 per audit Dim 24 —
+//   anatomy.stories.tsx StateBehavior 已 cover disabled state(單值 + 範圍)。展示層保留 SizeAlignment + MinMaxStep + OnCommit。
+//   2026-06-11:刪除 zombie export `Disabled_REMOVED`,對齊 DS-wide comment-only 退役慣例(deep-audit dim25)。
+
+// ── With live value commit ──────────────────────────────────────────────
+
+export const OnCommit: Story = {
+  name: '提交數值回呼',
+  render: () => {
+    const [preview, setPreview] = React.useState([3000])
+    const [applied, setApplied] = React.useState([3000])
+    return (
+      <div className="w-[360px] flex flex-col gap-4">
+        <p className="text-caption text-fg-secondary">
+          價格上限篩選——拖曳時即時預覽,放開才送出查詢(適合昂貴操作如 API
+          query、重新載入結果)
+        </p>
+        <div className="flex items-center gap-3">
+          <span className="text-body w-12 shrink-0">價格</span>
+          <Slider
+            value={preview}
+            onValueChange={setPreview}
+            onValueCommit={setApplied}
+            min={0}
+            max={10000}
+            step={100}
+            aria-label="價格上限"
+            className="flex-1"
+          />
+        </div>
+        <div className="flex flex-col gap-1 text-caption">
+          <span className="text-fg-secondary">即時預覽:${preview[0]}</span>
+          <span className="text-foreground font-medium">已套用查詢:${applied[0]}</span>
+        </div>
+      </div>
+    )
+  },
+}