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

package/src/components/Skeleton/skeleton.tsx

@@ -17,7 +17,7 @@ Skeleton.displayName = "Skeleton"
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const skeletonMeta = {
   component: 'Skeleton',
-  family: null, // non-family composite / overlay / layout
+  family: 'self-contained', // 對齊 skeleton.spec.md frontmatter(SSOT;同 ScrollArea meta 寫法)
   variants: {
 
   },

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

@@ -108,9 +108,9 @@ export const ColorMatrix: Story = {
               <tr><Td>Thumb 底色 disabled</Td><Td><TokenCell token="--canvas" display="bg-canvas(不透明背景色,沉回)" /></Td><Td><TokenCell token="--canvas" /></Td></tr>
               <tr><Td>Thumb 邊框 default</Td><Td><TokenCell token="--primary" display="border-2 border-primary" /></Td><Td><TokenCell token="--primary" display="--primary(與 Range default 同色)" /></Td></tr>
               <tr><Td>Thumb 邊框 disabled</Td><Td><TokenCell token="--border" display="border-border" /></Td><Td><TokenCell token="--border" display="--border(與 Range disabled 同色)" /></Td></tr>
-              <tr><Td>Thumb hover</Td><Td mono>border primary-hover + --elevation-100</Td><Td>—</Td></tr>
-              <tr><Td>Thumb active</Td><Td mono>--elevation-200</Td><Td>—</Td></tr>
-              <tr><Td>Thumb focus</Td><Td mono>border-primary-hover(加深,不加 ring/halo)</Td><Td><TokenCell token="--primary-hover" /></Td></tr>
+              <tr><Td>Thumb hover</Td><Td mono>border primary-hover(升 hover 階)+ --elevation-100</Td><Td>—</Td></tr>
+              <tr><Td>Thumb active(按壓拖曳)</Td><Td mono>border primary-active(深一階)+ --elevation-200</Td><Td><TokenCell token="--primary-active" /></Td></tr>
+              <tr><Td>Thumb focus</Td><Td mono>border-primary-hover(同 hover 視覺,不加 ring/halo)</Td><Td><TokenCell token="--primary-hover" /></Td></tr>
             </tbody>
           </table>
         </div>
@@ -230,7 +230,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"ARIA / 角色:繼承 Radix slider 的無障礙預設(role、aria-* 屬性、鍵盤導覽都由 primitive 提供)。\n\n鍵盤操作:\n\n- Tab — 聚焦到 thumb\n- ←/→ — 微調數值\n- Home/End — 跳到最小/最大值\n- PageUp/PageDown — 大步階調整\n\n聚焦樣式:thumb 鍵盤聚焦時,邊框加深成 primary-hover 色(跟滑鼠 hover 同一個視覺),不另外加外框光暈(ring/halo)。\n\n驗證:Storybook a11y 面板應為 0 個 critical violation;不用滑鼠、純鍵盤也能完整操作。文字對比 ≥ 4.5:1、UI 元件對比 ≥ 3:1(WCAG AA)。"}</p>
+      <p className="whitespace-pre-line">{"ARIA / 角色:繼承 Radix slider 的無障礙預設(role、aria-* 屬性、鍵盤導覽都由 primitive 提供)。\n\n鍵盤操作:\n\n- Tab — 聚焦到 thumb\n- ←/→ — 微調數值\n- Home/End — 跳到最小/最大值\n- PageUp/PageDown — 大步階調整\n\n聚焦樣式:thumb 鍵盤聚焦時,邊框升 hover 階(跟滑鼠 hover 同一個視覺),不另外加外框光暈(ring/halo)。\n\n驗證:Storybook a11y 面板應為 0 個 critical violation;不用滑鼠、純鍵盤也能完整操作。文字對比 ≥ 4.5:1、UI 元件對比 ≥ 3:1(WCAG AA)。"}</p>
     </div>
   ),
 }

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

@@ -66,28 +66,9 @@ benchmark:
 
 ### 一種視覺,多種容器尺寸
 
-**Slider 的視覺是固定的**——track 厚度、thumb 直徑、thumb 邊框都是單一值,不會隨 `size` 變動(focus 不加 ring / halo,改用 border 加深)。這是跟 Button / Input 等元件的明顯差異,理由是:
+**track / thumb 是單一視覺規格**(track 4px、thumb 16px、邊框 2px,皆不隨 `size` 變):thumb 是位置指示器,必須夠大好捕捉(Fitts's Law),等比縮小會直接傷可用性;世界級同款——Material 3(track 4dp / thumb 20dp)/ iOS(3pt / 28pt)/ Ant(4px / 14px)/ Radix,全部 thumb / track 尺寸獨立於 form-size system。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
-- 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 直徑、thumb 邊框尺寸。內部視覺元素透過 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-*`
-
-- **現況**:容器高 = `--field-height-sm/md/lg`(對齊);track 厚度固定 4px / thumb 直徑固定 16px / thumb 邊框固定 2px,**皆不隨 size 變化**(偏離 size-proportional scaling)。focus 不加 ring / halo,改用 border 加深(詳「視覺規格」表)
-- **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 階變(詳「視覺規格」表)。
 
 ---
 
@@ -105,9 +86,9 @@ Slider 接收 `size?: 'sm' | 'md' | 'lg'` prop(預設 `md`),**這個 prop 只決
 | **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` | — |
-| **Thumb** focus | border `primary-hover`(`outline-none focus-visible:border-primary-hover`,不加 ring / halo,跟 hover 同視覺)| `--primary-hover` |
+| **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**
@@ -116,14 +97,7 @@ Slider 接收 `size?: 'sm' | 'md' | 'lg'` prop(預設 `md`),**這個 prop 只決
 
 ### 為什麼 Track 底色維持「灰色凹槽」身分,不跟 enabled state 變動
 
-Track 是「凹槽底線」,它的視覺角色是「告訴使用者這條線是 slider 可滑動範圍」——這個語意不會因為 enabled / disabled 改變,所以**色相 / 角色也不該變**。rest 用 `bg-secondary`(neutral-3,「微淡可辨」),disabled 才退化成 `bg-muted`(neutral-2);兩者都在最淡的 subtle bg 層級,只是深淺差一階,凹槽身分始終不變。當整個 slider 被 disable 時,Range 和 Thumb border 會降級(rest 的 primary → border),Track 也同步退一階灰。
-
-為什麼用 `--secondary` / `--muted` 而非其他 token?
-- 兩者都是 semantic token,屬於 subtle bg 家族,語意歸屬明確
-- 是最淡的 subtle bg,符合「track 是背景凹槽,不是主角」的視覺層級
-- **優先用 semantic token,不直接引用 primitive**——這是系統的基本原則
-
-> **若覺得 track 底色在 white canvas 上太淡**,那是 `--secondary` / `--muted` 本身的系統級議題,應該統一調整其定義(影響 Badge / skeleton / Slider 一起),而不是在 Slider 裡偷偷用 primitive 繞過。
+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 色的綁定規則
 
@@ -134,13 +108,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)是世界級 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 -->
 
 ---
 
@@ -193,36 +165,20 @@ Radix Slider 原生支援多 thumb——只要 `value` / `defaultValue` 傳長
 | State | 視覺 | 觸發 |
 |---|---|---|
 | Rest | track `bg-secondary`,range `bg-primary`,thumb `bg-on-emphasis + border-primary` | 預設 |
-| Hover(thumb) | 加 `--elevation-100` 陰影 | 滑鼠 hover 在 thumb 上 |
-| Active(拖曳中) | 加 `--elevation-200` 陰影 | 按住拖曳 |
-| Focus | thumb border 加深成 `primary-hover`(跟 hover 同視覺,不加 ring / halo)| 鍵盤 Tab 聚焦 |
+| 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+)
-```
+### Disabled 視覺階層(三階,不是四階)
 
-**三階**,不是四階。Range 和 Thumb border 刻意用同一個 token(見前面「Range 色 ↔ Thumb border 色的綁定規則」),不拆成兩階。
+`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 永遠最上層。
 
-- **Track n-2**:最底的凹槽底線
-- **Range + Thumb border n-5**:同層——thumb border 是 range 的連續視覺,兩者融為一體;thumb 的 fill(rest 白 / disabled canvas)與 range fill 對比,位置由 range 的長度段決定
-- **Text n-7+**:label / description 在所有視覺元件之上
+### 為什麼 range disabled 用 `--border` 不用 `--fg-disabled`
 
-### 為什麼 range disabled 不用 `--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 用」節。
 
 ---
 
@@ -239,27 +195,9 @@ track (muted, n-2) < range = thumb border (border, n-5) < text (n-7+)
 | **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 的差異
-
-Switch 是**唯一需要 opacity 的特例**,因為它的 on/off 沒有任何形狀差異:
-- On:track + thumb
-- Off:track + thumb(同樣形狀,thumb 在不同位置)
-
-唯一的 state 視覺載體是 track 顏色(primary vs border)。灰階 swap 會讓 on/off 視覺無法區分——必須靠 opacity 保留顏色。
-
-**這個 rationale 不適用 Slider**,因為 Slider 的 state 載體不是顏色。
+Disabled slider 要傳達的兩件事——thumb 位置、range 長度——**完全不依賴顏色**(灰階後 x 座標與填滿佔比一模一樣),失去藍色零資訊損失,故走灰階派(同 Checkbox:state 由形狀 / 位置承載、顏色是裝飾)。Switch 是唯一 opacity 特例:on/off 無任何形狀差異、顏色本身就是 state,灰階會讓兩態無法區分——此 rationale 不適用 Slider。
 
 ### 為什麼 shadcn / Material 3 用 opacity 仍然不是理由
 
@@ -322,11 +260,7 @@ Slider 無獨立 `readOnly` prop;但在 `<Field mode="readonly">` 內(2026-06-12
 
 ## Inspector 用途
 
-Slider 的可調維度是 `min` / `max` / `step` / `defaultValue`(值域與步進)× `size`(容器外高 tier)。`Inspector` story 提供右側 Controls 即時切這些 prop,讓設計師看值域行為與容器高度 tier(track / thumb 視覺固定,只有容器外高隨 `size` 變)。
-
-`size` / `range mode` / track / range / thumb 的色彩綁定規則這類「對照題」(side-by-side 比較,非單值拉動),另由 `SizeMatrix` / `StateBehavior` / `ColorMatrix` / 元件特有 `ColorBindingRule`(range ↔ thumb border 綁定規則) / `KeyboardMatrix`(Radix 原生鍵盤) 各自的 matrix story 完整覆蓋——綁定規則與鍵盤對照用 matrix 呈現比 Inspector 試玩更清楚。
-
-對應 anatomy story:`Overview` + `Inspector` + `ColorMatrix` + `SizeMatrix` + `StateBehavior` + 元件特有 `ColorBindingRule` + `KeyboardMatrix` + `Accessibility`。
+Inspector 提供 `min` / `max` / `step` / `defaultValue` × `size` 即時調整(track / thumb 視覺固定,只有容器外高隨 size 變);色彩綁定 / 鍵盤等 side-by-side 對照題由各 matrix story 覆蓋。對應 anatomy story:`Overview` + `Inspector` + `ColorMatrix` + `SizeMatrix` + `StateBehavior` + 元件特有 `ColorBindingRule` + `KeyboardMatrix` + `Accessibility`。
 
 ---
 
@@ -346,7 +280,7 @@ Slider 的可調維度是 `min` / `max` / `step` / `defaultValue`(值域與步
 
 **Keyboard 行為**:完整鍵盤對照見上方「鍵盤操作(Radix 原生,免手工)」節,不重複列。
 
-**Focus**:Radix primitive 自管 focus / restoration;thumb 鍵盤聚焦時 `outline-none focus-visible:border-primary-hover`(border 加深成 primary-hover,跟 hover 同視覺,不加 ring / halo)。
+**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)。
 

package/src/components/Slider/slider.tsx

@@ -50,7 +50,9 @@ const sliderRootVariants = cva(
 )
 
 export interface SliderProps
-  extends Omit<React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root>, 'children'>,
+  // 'orientation' 一併 Omit(2026-07-07 deep-audit A.1b 殘項):spec「不支援 vertical」宣稱的
+  // 型別面機械封鎖 — DS 樣式(track h-1 / w-full / items-center)假設 horizontal,透傳 vertical 壞版。
+  extends Omit<React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root>, 'children' | 'orientation'>,
     VariantProps<typeof sliderRootVariants> {}
 
 // code-quality-allow: long-function — foundational composite(thumb-count 推導 + Field disabled 整合 + multi-mode render)
@@ -121,7 +123,9 @@ const Slider = React.forwardRef<
           - Rest: `border-primary` ↔ Range `bg-primary`
           - Disabled: `border-border` ↔ Range `bg-border`
         這個一致性讓 thumb border 跟 range 融為一體,看起來像「range 包住 thumb」
-        的連續視覺。不論 state,thumb border 跟 range 永遠同色。
+        的連續視覺。**同色綁定 scope = rest 與 disabled 兩態**;互動態(hover/active/focus)
+        只動 thumb border 色階(+ elevation),range 填色恆定 —— 2026-07-06 修正原
+        「不論 state 永遠同色」過度宣稱(hover/active 一直都只動 thumb,claim 與 code 不符)。
 
         **Thumb bg 兩態(2026-06-12 user 拍板,深色模式破洞修正)**:
           - Rest/hover/active:`bg-on-emphasis`(固定白、深淺主題不反轉)— 對齊自家
@@ -142,10 +146,14 @@ const Slider = React.forwardRef<
             'block h-4 w-4 shrink-0 rounded-full cursor-grab',
             'bg-on-emphasis border-2 border-primary',
             'transition-all duration-150',
-            // Hover:border 加深到 primary-hover + elevation 陰影
+            // Hover:border 升 hover 階(light mode 淺一階 lift,= Button primary hover 變色邏輯)
+            // + elevation 陰影。2026-07-06 修語:原註解寫「加深」但 primary-hover 比 base 淺,
+            // 措辭與 token 相反 — token 不遷就錯註解,註解修正。
             'hover:border-primary-hover hover:[box-shadow:var(--elevation-100)]',
-            'active:cursor-grabbing active:border-primary-hover active:[box-shadow:var(--elevation-200)]',
-            // Focus:border 加深(跟 hover 同視覺),不加 ring 或 halo
+            // Active(按壓拖曳):深一階 primary-active(= Button active 邏輯 button.tsx active:*-active
+            // 對照組;原誤用 hover 階 = 全 DS 唯一 active-用-hover 偏移,2026-07-06 雙向全掃修正)
+            'active:cursor-grabbing active:border-primary-active active:[box-shadow:var(--elevation-200)]',
+            // Focus:跟 hover 同視覺(hover 階),不加 ring 或 halo
             'outline-none focus-visible:border-primary-hover',
             // Disabled:border 跟 Range 一起退成 border(n-5),bg 沉回 canvas(不透明背景色)
             'data-[disabled]:cursor-not-allowed data-[disabled]:border-border data-[disabled]:bg-canvas',

package/src/components/Steps/steps.anatomy.stories.tsx

@@ -382,7 +382,7 @@ export const StateBehavior: Story = {
         <span className="text-caption font-medium text-fg-secondary">行為 2:linear 控制 upcoming step 可否點擊</span>
         <Desc>
           `linear=true`(預設)= 只能依序前進,回查僅限 completed(對應 checkout 這種「不可跳過」流程)。
-          `linear=false` + `reachableValues` = 自由跳轉,任何 reachable step 可點(對應「多 tab 表單編輯器」)。
+          `linear=false` = 自由跳轉,任何非 disabled step 都可點(對應「多 tab 表單編輯器」;reachable 是 linear 模式的內部推導態,非 prop)。
         </Desc>
         <LinearVsNonlinear />
       </div>

package/src/components/Steps/steps.spec.md

@@ -420,9 +420,9 @@ Description 在 error state 下維持 `text-fg-secondary`(跟其他 state 一樣
 
 ---
 
-## 為何無 Inspector
+## Inspector 與矩陣分工
 
-Steps 的決策是「展示所有步驟進度」,需要一整條鏈才能呈現設計——單互動切換 value 不如 side-by-side 矩陣清楚。關鍵維度由 `OrientationMatrix` / `ColorMatrix`(含 4 狀態色)/ `SizeMatrix` / `StateBehavior`(進度流轉 / linear / error interrupt)/ 元件特有 `IndentAlignment` 五張 story 完整覆蓋。
+Steps 的決策是「展示所有步驟進度」,需要一整條鏈才能呈現設計——關鍵維度由 `OrientationMatrix` / `ColorMatrix`(含 4 狀態色)/ `SizeMatrix` / `StateBehavior`(進度流轉 / linear / error interrupt)/ 元件特有 `IndentAlignment` 五張 side-by-side 矩陣 story 完整覆蓋;`Inspector`(元件檢閱器)另補單一互動 playground(Controls 切 value / completedValues / errorValues / size / orientation / linear / expansion,對齊 anatomy 6-canonical)。矩陣是設計比對主路徑,Inspector 供即時 prop 試切。
 
 ## StateBehavior 說明(Steps 層級特有)
 
@@ -432,7 +432,7 @@ Item-level **內容狀態色彩**(completed / current / upcoming / error indicat
 
 ## 邊界案例
 
-- **Disabled step**:`disabled` step 視覺繼承 SelectionItem disabled token(`text-fg-disabled`,M24),click 不觸發 navigate;`linear` mode 下 upcoming steps 預設 disabled 直到前面 completed。
+- **Disabled step**:`disabled` step 視覺繼承 SelectionItem disabled token(`text-fg-disabled`,M24),click 不觸發 navigate;`linear` mode 下 upcoming steps 預設不可點(non-clickable:無 `role="button"` / 不進 Tab 順序 / cursor-not-allowed,SR 念 sr-only「未開始」;與 `disabled` prop 不同,**不**設 `aria-disabled` / `data-disabled`)直到前面 completed 解鎖。
 - **Loading(async step state fetch)**:Steps primitive 為 sync render,async data fetch 應由 consumer 在外層 Skeleton 取代整個 Steps;Steps 內部不獨立 own loading prop,**也無 per-step loading state**(content state 集合不含 loading)— 單一步驟 async 進行中即 current,進度細節由 consumer 在 `StepContent` 內呈現。
 - **Empty(0 steps)**:無任何 `<StepItem>` children 時無進度可呈現;consumer 應條件性不渲 Steps 或渲 `<Empty>` 替代,不渲空 Steps container。
 - **Single step / `value` 指向第一步**:合法初始狀態,第一個 step 渲染 current,後續依推導為 reachable / upcoming。
@@ -448,7 +448,7 @@ Item-level **內容狀態色彩**(completed / current / upcoming / error indicat
 - `../Tabs/tabs.spec.md` — 平行視圖切換（非進度場景）
 - `../Breadcrumb/breadcrumb.spec.md` — 位置路徑（非進度場景）
 - `../RadioGroup/radio-group.spec.md` — 選值（非進度場景）
-- `../Avatar/avatar.tsx` — Indicator 32px 尺寸依據（`AVATAR_SIZE.block.sm/md = 32`）
+- `../../patterns/element-anatomy/item-anatomy.tsx` — Indicator 32px 尺寸依據（`AVATAR_SIZE.block.sm/md = 32`;`AVATAR_SIZE` 常數住 item-anatomy,非 avatar.tsx — Avatar 本身 size 為任意 number）
 - `../../tokens/uiSize/uiSize.spec.md` — `field-height-xs` 地板規則 + Icon 尺寸 Tier
 - `../../tokens/color/color.spec.md` — Primary token
 - CLAUDE.md「選擇 / 狀態視覺必須對齊既有 canonical」— Steps 不用 `bg-neutral-selected` 的理由
@@ -459,6 +459,7 @@ Item-level **內容狀態色彩**(completed / current / upcoming / error indicat
 
 - **root `aria-label`**:consumer 透過 `<Steps aria-label="註冊流程進度">` 提供(透傳到 `<ol>`),命名此流程。對齊 Angular Material「stepper 必須有 label」。
 - **sr-only 狀態文字**:每個 step header 含 visually-hidden `<span>`「第 N 步,共 M 步,{已完成 / 進行中 / 錯誤 / 未開始}」——indicator 是 `aria-hidden` 純視覺,故 sr-only 是螢幕報讀器**唯一**狀態來源(對齊 Carbon `--assistive-text` 慣例)。
+- **展開狀態 ARIA**(2026-07-05 D4 加):垂直模式 step 含 `<StepContent>` 時,clickable header(`role="button"`)輸出 `aria-expanded`(反映 content 展開狀態;`multiple` toggle 與 `follow-active` 皆同步),並在 content 實際渲染(展開)時以 `aria-controls` 指向 content 區(收合時 content 不在 DOM,不輸出避免 dangling reference)——對齊 WAI-ARIA disclosure pattern trigger 最低要求。chevron 維持 `aria-hidden` 純視覺。
 
 **Keyboard 行為**(Carbon 模型 — sequential Tab,非 tablist roving):
 
@@ -476,4 +477,5 @@ Item-level **內容狀態色彩**(completed / current / upcoming / error indicat
 
 - `horizontal-overflow.spec.md`
 - `item-anatomy.spec.md`
+- `pagination.spec.md`
 - `progress-bar.spec.md`

package/src/components/Steps/steps.tsx

@@ -436,7 +436,7 @@ const STEP_STATUS_TEXT: Record<StepContentState, string> = {
   upcoming: '未開始',
 }
 
-function StepItemHeader({ children, className, style }: { children: React.ReactNode; className?: string; style?: React.CSSProperties }) {
+function StepItemHeader({ children, className, style, contentId }: { children: React.ReactNode; className?: string; style?: React.CSSProperties; contentId?: string }) {
   const item = useStepItemContext()
   const steps = useStepsContext()
   const index = React.useContext(StepIndexContext)
@@ -454,6 +454,12 @@ function StepItemHeader({ children, className, style }: { children: React.ReactN
       onClick={item.clickable ? item.activate : undefined}
       onKeyDown={item.clickable ? onKeyDown : undefined}
       aria-disabled={item.disabled || undefined}
+      // 2026-07-05 D4 修:step 有 content 的可點 header(role=button)必帶 aria-expanded —
+      // WAI-ARIA disclosure pattern trigger 最低要求(multiple 模式 toggle;follow-active 亦
+      // 同步反映展開狀態)。aria-controls 只在 content 實際 render(展開)時輸出,避免
+      // dangling id reference(content 收合時不在 DOM)。
+      aria-expanded={item.clickable && contentId ? item.expanded : undefined}
+      aria-controls={item.clickable && contentId && item.expanded ? contentId : undefined}
       className={cn(
         // leading-compact:scanning-family header 行高 = 1.3(item-anatomy.spec.md:776 掃描模式 label 行高)。
         // 設在 header 而非 li 根 → prefix h-[1lh] + 水平 connector h-[1lh] + label(StepLabel 亦 leading-compact)
@@ -490,10 +496,12 @@ function VerticalLayout({
   const item = useStepItemContext()
   const showContent = !!content && item.expanded
   const indicatorBox = INDICATOR_BOX_WIDTH[steps.size]
+  // 2026-07-05 D4 修:content 區 id 供 header aria-controls 指向(disclosure 配線)
+  const contentId = React.useId()
 
   return (
     <>
-      <StepItemHeader className="flex items-start gap-3">
+      <StepItemHeader className="flex items-start gap-3" contentId={content ? contentId : undefined}>
         {/* Row prefix slot — 消費 item-anatomy <ItemPrefix>(h-[1lh] 對齊 label 第一行 SSOT);
             width = INDICATOR_BOX_WIDTH 固定欄寬,base justify-center 讓 sm dot 在欄內置中 */}
         <ItemPrefix style={{ width: indicatorBox }}>
@@ -520,7 +528,7 @@ function VerticalLayout({
         </div>
       </StepItemHeader>
       {showContent && (
-        <div className="flex items-start gap-3 mt-3">
+        <div id={contentId} className="flex items-start gap-3 mt-3">
           <div className="shrink-0" style={{ width: indicatorBox }} />
           <div className="flex-1 min-w-0">{content}</div>
         </div>

package/src/components/Switch/switch.spec.md

@@ -75,6 +75,7 @@ Track（pill 形，rounded-full）
 - Track 寬 = 2 × 高（pill 比例）
 - Thumb 直徑 = track 高度
 - ON 狀態 thumb 右滑 `translateX(trackHeight)`
+- **Hover**(2026-07-06 補,「選中之上 hover 升階」家族):ON track `bg-primary → bg-primary-hover`(Checkbox checked hover 同款;Ant Switch checked hover = `colorPrimaryHover` 源碼實錘);OFF track `bg-border → bg-border-hover` 深一階(Checkbox 未選 hover 同慣例)
 
 ---
 
@@ -102,7 +103,7 @@ sm 和 md 視覺相同（純粹命名 mapping，讓消費者可直接傳同一
 | OFF | `bg-border`（neutral-5） | 白色 + 2px `border-border`（neutral-5，與 OFF track 同色） | 無 |
 | ON | `bg-primary` | 白色 + 2px primary border | primary check |
 | Disabled | 套 `opacity-disabled`（整體透明度降級） | 同 ON/OFF | 同 ON/OFF |
-| Readonly(standalone)| 視覺同一般態 | 但 `pointer-events-none` + `aria-readonly` | — |
+| Readonly(standalone)| 視覺同一般態 | 但 `pointer-events-none` + click guard + `aria-readonly` | — |
 | Readonly(Field 內,2026-06-12 user 拍板)| 不渲染 toggle — 改渲染 `fieldWrapperStyles` readonly 灰框(= Input readonly 同源)+ ✓/—(display 同款值語言) | role="switch" + aria-checked + aria-readonly + 可 focus | — |
 
 ### Disabled 用 `opacity`
@@ -123,7 +124,7 @@ sm 和 md 視覺相同（純粹命名 mapping，讓消費者可直接傳同一
 | | Readonly(standalone) | Disabled |
 |---|---|---|
 | 視覺 | 正常顏色（可讀） | 降透明度（弱化） |
-| 互動 | 不可切換（pointer-events-none） | 不可切換（cursor-not-allowed） |
+| 互動 | 不可切換（pointer-events-none + click guard） | 不可切換（cursor-not-allowed） |
 | aria | `aria-readonly` | `disabled` |
 | Tab 焦點 | 不在 tab order | 不在 tab order |
 | 用途 | settings list 鎖定呈現 | 外部條件造成不可操作 |
@@ -181,7 +182,7 @@ Switch 可透過 `label` / `description` props 內部直接渲染緊鄰文字：
 
 ## 邊界案例
 
-- **Readonly 的滑鼠 / 鍵盤**(standalone)：`pointer-events-none` 使點擊無反應；`tabIndex=-1` 不入 tab order，故無鍵盤互動（視覺正常、僅鎖互動）。Field 內 readonly 灰框則 tabIndex=0 可聚焦(對齊 readonly input 可聚焦慣例)
+- **Readonly 的滑鼠 / 鍵盤**(standalone)：`pointer-events-none` 使直接點擊無反應;`<label htmlFor>` 的 synthetic click 非 pointer event,由 label + Root 兩道 onClick preventDefault guard 攔(2026-07-05 D4 補,點 label 文字不再 toggle);`tabIndex=-1` 不入 tab order，故無鍵盤互動（視覺正常、僅鎖互動）。Field 內 readonly 灰框則 tabIndex=0 可聚焦(對齊 readonly input 可聚焦慣例)
 - **Disabled 的鍵盤**：native `disabled`——不可聚焦、無鍵盤行為
 - **Label 過長**：自動換行（label 容器 `flex-1 min-w-0`），Switch 錨定第一行行高置中（`h-[1lh]`）且不被擠壓（`shrink-0`）
 - **無 loading state**：Switch 無 loading prop——async 進度不屬 Switch（見「何時不用」，用 Button loading）

package/src/components/Switch/switch.tsx

@@ -60,6 +60,13 @@ const switchVariants = cva(
     // OFF → ON 背景色
     'data-[state=unchecked]:bg-border',
     'data-[state=checked]:bg-primary',
+    // 選中之上的 hover = 同色相升 hover 階(2026-07-06 user 掃出 Switch 是「藍色選中家族」
+    // 唯一漏網:Checkbox checked hover 早有同款、Ant Switch checked hover = colorPrimaryHover
+    // 源碼實錘;順修 meta states 宣稱 'hover' 但 code 原本零 hover 樣式的 claim-vs-code 落差)。
+    // unchecked hover:border(n-5)→ border-hover(n-6)深一階,對齊 Checkbox 未選 hover
+    // 加深一階慣例 + Ant unchecked hover(colorTextTertiary 加深)同方向。
+    'data-[state=unchecked]:hover:bg-border-hover',
+    'data-[state=checked]:hover:bg-primary-hover',
   ],
   {
     variants: {
@@ -73,16 +80,18 @@ const switchVariants = cva(
   }
 )
 
-const SPECS: Record<string, { thumb: number; check: number; checkStroke: number; translate: string }> = {
+const SPECS: Record<string, { thumb: number; check: number; checkStroke: number }> = {
   // checkStroke:16px 以下 icon 視覺不夠顯眼 → 加粗 stroke 補償(跟 Checkbox 共用原則,
   // 見 checkbox.tsx 的 checkStrokeWidth 註解)。12px 用 3.5(render ≈ 1.75px 線寬,比 Lucide
   // 預設的 1px render 明顯更粗,視覺跟 16px 預設 stroke 的 1.33px 有足夠區別),16px 用 2.5
   // (render ≈ 1.67px,比預設 1.33px 稍粗讓 toggle check 夠顯眼)。跨 size 配對值由 checkbox.tsx 共用。
   // 2026-05-18 簡化 per user 視覺證 + Checkbox 同步(3.5 → 3 sm/md):effective render 差
   // 0.08px 視覺看不出,保留 compensation 主旨但不過度差異化。
-  sm: { thumb: 20, check: 12, checkStroke: 3, translate: 'translateX(20px)' },
-  md: { thumb: 20, check: 12, checkStroke: 3, translate: 'translateX(20px)' },
-  lg: { thumb: 24, check: 16, checkStroke: 2.5, translate: 'translateX(24px)' },
+  // 2026-07-04 刪 dead field translate:整檔零消費,實際位移 SSOT = Thumb className
+  // translate-x-5(20px)/ translate-x-6(24px)(見下方 Thumb),消除雙住所漂移風險。
+  sm: { thumb: 20, check: 12, checkStroke: 3 },
+  md: { thumb: 20, check: 12, checkStroke: 3 },
+  lg: { thumb: 24, check: 16, checkStroke: 2.5 },
 }
 
 export interface SwitchProps
@@ -174,23 +183,41 @@ const Switch = React.forwardRef<
     const generatedId = React.useId()
     const inputId = idProp ?? fieldCtx?.id ?? generatedId
 
+    // 2026-07-04 修:display / readonly-in-Field 分支的裸 span/div 原丟棄剩餘 props
+    // (id/data-*/aria-*)且不轉發 forwardRef ref → consumer 的 aria-label 等靜默失效。
+    // 抽出 Radix 專屬 non-DOM props,其餘 DOM props 於兩分支 spread 轉發(與 Checkbox/
+    // RadioGroup 同修);edit 主路徑不受影響(rootEl 仍 spread 完整 props)。
+    const {
+      checked: checkedProp,
+      defaultChecked: defaultCheckedProp,
+      onCheckedChange: _onCheckedChange,
+      required: _required,
+      name: _name,
+      value: _value,
+      asChild: _asChild,
+      children: _children,
+      ...restDomProps
+    } = props
+
     // ── mode='display'(下移至所有 hooks 之後,per #35 Rules of Hooks)──────────
     // 純展示模式:無互動 toggle、渲染 ✓ / —。與 Checkbox display 對齊(同 boolean primitive)。
     if (resolvedMode === 'display') {
-      const isChecked = props.checked === true
+      const isChecked = checkedProp === true
       return isChecked
-        ? <span className="text-foreground">✓</span>
-        : <span className="text-fg-muted">—</span>
+        ? <span {...restDomProps} ref={ref as React.Ref<HTMLSpanElement>} className="text-foreground">✓</span>
+        : <span {...restDomProps} ref={ref as React.Ref<HTMLSpanElement>} className="text-fg-muted">—</span>
     }
 
     // ── mode='readonly' in Field(2026-06-12 user 拍板「灰框 + ✓/—」,與 Checkbox 同款)──
     // Field 內 readonly boolean = fieldWrapperStyles readonly 灰框(= Input readonly 同源)
     // + ✓/— 值語言;standalone readOnly(settings list)維持原樣鎖互動。詳 checkbox.tsx 同段註解。
     if (effectiveReadOnly && insideField) {
-      const isChecked = (props.checked ?? props.defaultChecked) === true
+      const isChecked = (checkedProp ?? defaultCheckedProp) === true
       const boxSize = resolvedBoxSize
       return (
         <div
+          {...(restDomProps as React.HTMLAttributes<HTMLDivElement>)}
+          ref={ref as React.Ref<HTMLDivElement>}
           role="switch"
           aria-checked={isChecked}
           aria-readonly="true"
@@ -220,6 +247,17 @@ const Switch = React.forwardRef<
         tabIndex={effectiveReadOnly ? -1 : undefined}
         aria-describedby={fieldCtx?.descriptionId}
         {...props}
+        // 2026-07-05 D4 修:readOnly 鎖互動補 label 繞道 — <label htmlFor> 的 synthetic click
+        // 不是 pointer event,cva pointer-events-none 攔不到,點 label 文字仍 toggle。
+        // preventDefault 讓 Radix composeEventHandlers(checkForDefaultPrevented)跳過內部 toggle;
+        // 必列在 {...props} 之後才不被 consumer onClick 覆蓋(與 Checkbox/RadioGroupItem 同修)。
+        onClick={(event) => {
+          if (effectiveReadOnly) {
+            event.preventDefault()
+            return
+          }
+          props.onClick?.(event)
+        }}
       >
         <SwitchPrimitives.Thumb
           className={cn(
@@ -251,6 +289,11 @@ const Switch = React.forwardRef<
     return (
       <label
         htmlFor={inputId}
+        // 2026-07-05 D4 修:readOnly 時在 label 端取消 synthetic activation(第一道防線;
+        // Root onClick guard 為第二道 — 兩道對齊 finding suggestion 防 consumer 自寫 label 繞過)。
+        onClick={(event) => {
+          if (effectiveReadOnly) event.preventDefault()
+        }}
         className={cn(
           'inline-flex items-start gap-3 select-none',
           effectiveDisabled ? 'cursor-not-allowed' : readOnly ? 'cursor-default' : 'cursor-pointer'
@@ -288,6 +331,7 @@ const Switch = React.forwardRef<
             </span>
           )}
         </span>
+        {/* @row-slot-handcraft-allow: Field 控件的 1lh 首行對齊 wrapper(selection-control 家族 Checkbox/RadioGroup 同構),非 row item slot,不消費 MenuItem */}
         <span className="h-[1lh] flex items-center shrink-0">
           {rootEl}
         </span>
@@ -310,9 +354,14 @@ export const switchMeta = {
     md: { fieldHeight: 32, iconSize: 12, typography: 'body' },
     lg: { fieldHeight: 36, iconSize: 16, typography: 'body-lg' },
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 2026-07-04 修 stale meta:移除 'active' — switchVariants / Thumb 無 active-state 樣式
+  // (cva 只有 unchecked/checked/disabled/readonly/focus-visible;對照 checkboxMeta 正確不含 active)
+  // 'checked' = ON 持續態(bg-primary;2026-07-07 meta 詞彙統一補列,toggle 家族用 'checked')
+  states: ['default', 'hover', 'checked', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-primary'],
+    // 2026-07-04 補齊漏列:bg-border = OFF track(cva data-[state=unchecked]:bg-border)、
+    // bg-on-emphasis = Thumb 白圓(Thumb className)— 兩者 code 實際消費,meta 原漏列
+    bg: ['bg-border', 'bg-on-emphasis', 'bg-primary'],
     fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground', 'text-primary'],
     ring: ['ring-ring'],
   },

package/src/components/Tabs/tabs.anatomy.stories.tsx

@@ -36,7 +36,7 @@ export const Overview: Story = {
             </TabsContent>
           </Tabs>
         </div>
-        <p className="text-footnote text-fg-muted mt-3">Selected underline 用 ::after 絕對定位在 bottom: -1px(2px primary-hover),蓋住 TabsList 的 1px gray border(單一視覺線條)</p>
+        <p className="text-footnote text-fg-muted mt-3">Selected underline 用 ::after 絕對定位在 bottom: -1px(2px primary),蓋住 TabsList 的 1px gray border(單一視覺線條)</p>
       </div>
 
       <div>
@@ -66,9 +66,10 @@ export const Overview: Story = {
             <tbody>
               {[
                 ['Tabs', '', '', ''],
+                ['  defaultValue / value', 'string', '—', '當前 tab 值(受控 / 非受控)'],
+                ['TabsList', '', '', ''],
                 ['  size', "'sm' | 'md' | 'lg'", "'sm'", 'tab 高度 tier(對齊 --tab-height-*);size 選擇指引詳「設計原則 → 尺寸選擇」'],
                 ['  overflow', "'none' | 'scroll' | 'menu'", "'none'", '水平溢出處理(捲動 / 下拉選單)'],
-                ['  defaultValue / value', 'string', '—', '當前 tab 值(受控 / 非受控)'],
                 ['TabsTrigger', '', '', ''],
                 ['  value', 'string', '必填', '唯一識別碼,對應 TabsContent value'],
                 ['  startIcon', 'LucideIcon', '—', '前綴 icon(描述 tab 類型)'],
@@ -227,7 +228,7 @@ export const ColorMatrix: Story = {
         <H3>TabsTrigger 四態色彩</H3>
         <Desc>
           Tabs 未選狀態用 fg-secondary(不搶視覺),hover 時文字色轉 foreground(text-foreground，
-          neutral 最深)。Selected 用 foreground + bottom 2px primary-hover 下線
+          neutral 最深)。Selected 用 foreground + bottom 2px primary 下線
           ——下線是「當前位置」的明確指示器,不靠底色區分。
         </Desc>
         <div className="overflow-x-auto mb-4">
@@ -306,7 +307,7 @@ export const StateBehavior: Story = {
     <div className="flex flex-col gap-10">
       <div>
         <H3>互動狀態對照</H3>
-        <Desc>「總覽」為 selected（當前 value，有 primary-hover 底部下線）;「成員」「通知」為 unselected(移 hover 上去文字色轉 foreground);「設定」為 disabled(停用)。</Desc>
+        <Desc>「總覽」為 selected（當前 value，有 primary 底部下線）;「成員」「通知」為 unselected(移 hover 上去文字色轉 foreground);「設定」為 disabled(停用)。</Desc>
         <div className="border border-border rounded-lg p-4">
           <Tabs defaultValue="overview">
             <TabsList>
@@ -318,7 +319,7 @@ export const StateBehavior: Story = {
           </Tabs>
         </div>
         <p className="text-footnote text-fg-muted mt-3">
-          Selected underline:`::after bottom: -1px height: 2px bg: primary-hover`——蓋住 TabsList 的 1px gray border
+          Selected underline:`::after bottom: -1px height: 2px bg: primary`——蓋住 TabsList 的 1px gray border
         </p>
       </div>
     </div>
@@ -395,7 +396,7 @@ export const SpacingTokens: Story = {
 
       <div>
         <H3>Trigger 無水平 padding</H3>
-        <Desc>Trigger **不加任何水平 padding**——寬度 = 內容寬度(hug content)。selected underline(`::after left-0 right-0`)因此剛好 fit label;若加橫向 padding,underline 會多出鬆散空白。trigger 之間的分隔靠 TabsList 的 `gap-[--layout-space-loose]`,不是 padding。</Desc>
+        <Desc>Trigger **不加任何水平 padding**——寬度 = 內容寬度(hug content)。selected underline(`::after left-0 right-0`)因此剛好 fit label;若加橫向 padding,underline 會多出鬆散空白。trigger 之間的分隔靠 TabsList 的 `gap-[var(--layout-space-loose)]`,不是 padding。</Desc>
       </div>
     </div>
   ),

package/src/components/Tabs/tabs.principles.stories.tsx

@@ -115,10 +115,11 @@ export const UsageGuidance: Story = {
             <Label>✅ Tabs:電商後台,每個 view 是獨立子頁(各自有 filters / table / actions)</Label>
             <Tabs defaultValue="orders">
               <TabsList>
+                {/* 2026-07-04:同組 startIcon 全有或全無(spec 禁止事項)— 原 顧客/設定 混用 icon 已移除 */}
                 <TabsTrigger value="orders">訂單</TabsTrigger>
-                <TabsTrigger value="customers" startIcon={Users}>顧客</TabsTrigger>
+                <TabsTrigger value="customers">顧客</TabsTrigger>
                 <TabsTrigger value="products">產品</TabsTrigger>
-                <TabsTrigger value="settings" startIcon={Settings}>設定</TabsTrigger>
+                <TabsTrigger value="settings">設定</TabsTrigger>
               </TabsList>
               <TabsContent value="orders" className="text-body text-fg-muted">(訂單頁的 toolbar、filters、table…)</TabsContent>
             </Tabs>
@@ -199,8 +200,9 @@ export const SizeSelection: Story = {
       >
         <Tabs defaultValue="a">
           <TabsList size="md">
+            {/* 2026-07-04:同組 icon 全有或全無(spec 禁止事項)— 原 成員 單獨帶 icon 已移除 */}
             <TabsTrigger value="a">總覽</TabsTrigger>
-            <TabsTrigger value="b" startIcon={Users}>成員</TabsTrigger>
+            <TabsTrigger value="b">成員</TabsTrigger>
             <TabsTrigger value="c" badge={<Badge count={3} />}>通知</TabsTrigger>
           </TabsList>
         </Tabs>