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

package/src/components/Sidebar/sidebar.tsx

@@ -172,14 +172,14 @@ const SidebarProvider = React.forwardRef<
     const setOpen = React.useCallback(
       (value: boolean | ((value: boolean) => boolean)) => {
         const openState = typeof value === "function" ? value(open) : value
-        if (setOpenProp) {
-          setOpenProp(openState)
-        } else {
-          _setOpen(openState)
-        }
+        // 受控/非受控分岔依「有沒有傳 open prop」判定(同上方 activeId pattern),
+        // 不依「有沒有傳 onOpenChange」——否則 uncontrolled + onOpenChange 場景
+        // internal state 永不更新,sidebar 凍結(同 SelectMenu R2 已修 bug class)。
+        if (openProp === undefined) _setOpen(openState)
+        setOpenProp?.(openState)
         document.cookie = `${SIDEBAR_COOKIE_NAME}=${openState}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}`
       },
-      [setOpenProp, open]
+      [openProp, setOpenProp, open]
     )
 
     const toggleSidebar = React.useCallback(() => {
@@ -306,6 +306,10 @@ const Sidebar = React.forwardRef<
      * 從該值起算(`top: viewportInsetTop / height: calc(100svh - viewportInsetTop)`),
      * 讓 global header 不被覆蓋(AppShell primary-header mode 必傳)。
      * 對齊 Mantine `layout="default"` navbar 高度扣 header 慣例。
+     *
+     * ⚠️ 作用範圍:**僅桌機 `offcanvas` / `icon` 分支**套用 insetStyle。
+     * `collapsible="none"`(於 isMobile 前提前 return 固定 div)與 mobile Sheet
+     * 兩分支不套此 inset —— 該兩模式下 global header 仍會被覆蓋(未接線)。
      */
     viewportInsetTop?: string
   }
@@ -471,13 +475,15 @@ SidebarInput.displayName = "SidebarInput"
 
 // ── Shell regions ──────────────────────────────────────────────────────────
 
-// SidebarHeader / SidebarFooter:
-//   - 固定高度 `var(--chrome-header-height)`(md=48 / lg=56,density-responsive)
-//   - 跨元件 chrome header 共享同一個 token,自動跟主內容 page header 對齊
+// SidebarHeader(固定高度 chrome slot)vs SidebarFooter(content-based):
+//   - SidebarHeader:固定高度 `var(--chrome-header-height)`(md=48 / lg=56,density-responsive),
+//     跨元件 chrome header 共享同一個 token,自動跟主內容 page header 對齊
+//   - SidebarFooter:高度由內容決定(`shrink-0 py-2 border-t`,不消費 chrome-header-height、
+//     無自身固定高度),見下方 SidebarFooter 定義的 docblock + spec「Chrome 內容的約束」段
 //   - 水平 padding 用 loose token(跟 items 的 px 對齊)
 //   - 邊框是結構邊界(分隔 fixed/scroll 區),full-width 不內縮
 //
-// 為什麼 density-responsive:chrome 裡放的 button 綁定 field-height token,
+// 為什麼 Header density-responsive:chrome 裡放的 button 綁定 field-height token,
 // 會隨 density 變大。Chrome 如果不跟著放大,lg density 下 padding 會被擠壓。
 const SidebarHeader = React.forwardRef<
   HTMLDivElement,
@@ -516,10 +522,11 @@ const SidebarHeader = React.forwardRef<
         //                                JS 端透過 WorkspaceBrand RowSizeProvider value="md"
         //                                + AVATAR_SIZE.inline.md spec-coupled 共識 sync。
         //
-        // Numerical equivalence to v13 `loose-4` 公式(verified):
-        //   md density: (48-24)/2 = 12 = loose-4 = 12 ✓ identical
-        //   lg density: (64-24)/2 = 20 = loose-4 = 20 ✓ identical
-        // → v14 upgrade 純 SSOT chain robustness,0 視覺改變。
+        // Collapsed pl 幾何值(rail-centered,--sidebar-width-icon = 2*loose + menu-icon):
+        //   md density: (48-24)/2 = 12  ·  lg density: (68-24)/2 = 22
+        //   (lg width = 2×24+20 = 68,非 stale 64;avatar-size = 24 both densities)
+        // 註:已撤回的 v13 `loose-4` 近似在 lg 給 20,與新 rail-幾何精確值 22 不同 —
+        //     v14 以 SSOT chain 公式取代該近似,md 兩者恰好都是 12。
         "group-data-[collapsible=icon]:!pl-[calc((var(--sidebar-width-icon)-var(--chrome-header-avatar-size))/2)]",
         "group-data-[collapsible=icon]:!pr-0",
         "transition-[padding] duration-200 ease-linear motion-reduce:duration-0",
@@ -602,8 +609,9 @@ SidebarContent.displayName = "SidebarContent"
 // ── Group ──────────────────────────────────────────────────────────────────
 
 // SidebarGroupContext——讓 `SidebarGroupLabel` 和 `SidebarGroupContent` 知道當前
-// 所在的 group 是否 collapsible,以自動切換渲染模式(label 變 trigger,content 變
-// `Collapsible.Content`)。沒有 context 就是舊行為(非 collapsible 的 plain div)。
+// 所在的 group 是否 collapsible,以自動切換渲染模式(label 尾端 chevron button 變
+// `Collapsible.Trigger`、content 變 `Collapsible.Content`;label 本身維持
+// `role="presentation"` div,不升格為 button)。沒有 context 就是舊行為(plain div)。
 type SidebarGroupContextValue = {
   collapsible: boolean
 }
@@ -617,13 +625,14 @@ function useSidebarGroup() {
  * SidebarGroup
  *
  * 預設是非互動的 plain group(div)。當 `collapsible` = true 時自動切換成 Radix
- * Collapsible:SidebarGroupLabel 變 trigger、SidebarGroupContent 變 Content、
- * 自動渲染 chevron 於 label 尾端、chevron 依 open state 旋轉。
+ * Collapsible:SidebarGroupLabel 尾端自動渲染 chevron button 作為 `Collapsible.Trigger`
+ * (承載 aria-expanded / data-state,依 open state 旋轉),SidebarGroupContent 變 Content;
+ * label 本身維持 `role="presentation"` div,不升格為 button。
  *
  * ── API 設計決策 ──
  * 為什麼是 group 層級的 prop 而不是 label 層級?因為「group 是否可收合」是結構層
- * 的決定,影響 group 所有子 primitive 的渲染模式(label 變 button、content 變
- * animated container)。把 prop 放在 label 上會讓 content 不知道自己該不該被包,
+ * 的決定,影響 group 子 primitive 的渲染模式(label 尾端 chevron 變 trigger button、
+ * content 變 animated container)。把 prop 放在 label 上會讓 content 不知道自己該不該被包,
  * 形成跨元件的 prop drilling。放在 group 上用 context 傳遞是 React 的標準做法。
  */
 const SidebarGroup = React.forwardRef<
@@ -667,8 +676,10 @@ const SidebarGroup = React.forwardRef<
         open={open}
         onOpenChange={onOpenChange}
         className={baseClass}
-        // Collapsible 在 icon 模式下整個隱藏(跟 TreeView 一樣——icon rail 沒空間放展開的 tree)
-        // Consumer 若要在 icon 模式顯示整個 group,自行傳 className 覆寫
+        // 註:此 Collapsible.Root 本身**不**自帶 icon 模式隱藏 class(baseClass 無
+        // `group-data-[collapsible=icon]:hidden`),icon 模式下預設仍渲染。若要在 icon rail
+        // 隱藏整個可收合 group(icon rail 沒空間放展開的 tree),consumer 自行傳
+        // `className="group-data-[collapsible=icon]:hidden"` 覆寫。
         {...(props as React.ComponentProps<typeof CollapsiblePrimitive.Root>)}
       >
         {children}
@@ -872,9 +883,10 @@ SidebarMenuItem.displayName = "SidebarMenuItem"
  *   - hover:      bg-neutral-hover
  *   - selected:   bg-neutral-selected(data-active=true)
  *
- * Icon 模式:button 保持 w-full 填滿 sidebar icon rail,鎖高為 field-height-{size},
- * content 用 justify-center 居中,label span 以 sr-only 視覺隱藏(a11y tree 保留,
- * 2026-07-05 D4——SR 仍讀得到 accessible name)。
+ * Icon 模式:button 保持 w-full 填滿 sidebar icon rail,**無 height lock / 無 justify-center**
+ * (2026-05-21 v4 C* 撤回 `!h-[...]`——row height 永遠 stable,collapsed 只 outer clip);
+ * prefix(icon / avatar)靠 `!pl-[calc((rail - prefix-width)/2)]` 公式置中對齊 rail,
+ * label span 以 sr-only 視覺隱藏(a11y tree 保留,2026-07-05 D4——SR 仍讀得到 accessible name)。
  */
 const sidebarMenuButtonVariants = cva(
   [

package/src/components/Skeleton/skeleton.stories.tsx

@@ -1,5 +1,5 @@
 // @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
-// @story-baseline: packages/design-system/src/components/DataTable/data-table.stories.tsx#NumberAlignment
+// @story-baseline: packages/design-system/src/components/DataTable/data-table.anatomy.stories.tsx#AlignmentRule
 import type { Meta, StoryObj } from '@storybook/react'
 import type { ColumnDef } from '@tanstack/react-table'
 import { Skeleton } from './skeleton'
@@ -21,16 +21,9 @@ const meta: Meta = {
 export default meta
 type Story = StoryObj
 
-export const Default: Story = {
-  name: '預設',
-  render: () => (
-    <div className="flex flex-col gap-2 max-w-md">
-      <Skeleton className="h-4 w-full" />
-      <Skeleton className="h-4 w-full" />
-      <Skeleton className="h-4 w-3/4" />
-    </div>
-  ),
-}
+// Default retired 2026-07-14 per audit Dim 24(story 重複性):「預設」的三行文字骨架
+// pattern 與 DocumentLoading 段落骨架完全同構,且抽象「預設」違「範例必真實業務場景」;
+// 由 UserProfileCard / TaskListLoading / DocumentLoading 等真實情境 story 覆蓋。
 
 export const UserProfileCard: Story = {
   name: '個人資料卡載入',

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

@@ -39,7 +39,7 @@ export const Overview: Story = {
               {[
                 ['value / defaultValue', 'number[]', '—', '[single] 或 [min, max] range mode'],
                 ['onValueChange', '(value: number[]) => void', '—', '拖曳中每次值變動'],
-                ['onValueCommit', '(value: number[]) => void', '—', '放開滑鼠才觸發(防抖用)'],
+                ['onValueCommit', '(value: number[]) => void', '—', '互動結束觸發:滑鼠放開,或鍵盤 Arrow/Page/Home/End 每次有效變更(防抖用)'],
                 ['min / max', 'number', '0 / 100', '值範圍'],
                 ['step', 'number', '1', '步進'],
                 ['size', "'sm' | 'md' | 'lg'", "'md'", '**只影響容器外高**,不影響 track/thumb 尺寸'],
@@ -175,8 +175,8 @@ export const ColorBindingRule: Story = {
   render: () => (
     <div className="flex flex-col gap-8">
       <div>
-        <H3>Range 色和 Thumb border 色永遠同 token</H3>
-        <Desc>Thumb 坐落在 range 的端點上,border 是 range 的視覺延續。兩者同色時看起來像「range 包住 thumb」——thumb 白底是「被 range 圍住的空心洞」,而不是「thumb 浮在 range 上面的異物」。</Desc>
+        <H3>Range 色和 Thumb border 色在 rest / disabled 兩態同 token</H3>
+        <Desc>Thumb 坐落在 range 的端點上,border 是 range 的視覺延續。兩者同色時看起來像「range 包住 thumb」——thumb 白底是「被 range 圍住的空心洞」,而不是「thumb 浮在 range 上面的異物」。<strong>互動態(hover / active / focus)只動 thumb border 色階</strong>(hover / focus 升 primary-hover、active 深至 primary-active),Range 填色恆 primary — 下表只列 rest / disabled 兩態的綁定。</Desc>
         <div className="overflow-x-auto">
           <table className="text-caption border-collapse">
             <thead><tr><Th>State</Th><Th>Range bg</Th><Th>Thumb border</Th><Th>共享 token</Th></tr></thead>

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

@@ -148,8 +148,8 @@ export const PositionAsStateRule: Story = {
       </Rule>
 
       <Rule
-        title="對照 Switch:必須用 opacity(顏色是唯一 state 載體)"
-        note="Switch 的 on/off 視覺差異唯一靠顏色(track bg-primary vs bg-border)——形狀完全一樣。若灰階 swap,disabled 的 ON 和 OFF 會看起來一模一樣,使用者無法分辨。必須 opacity 保留顏色"
+        title="對照 Switch:必須用 opacity(顏色是主要 state 載體)"
+        note="Switch 的 on/off 主要靠顏色(track bg-primary vs bg-border)承載——thumb 位移與 checked 勾號只是輔助訊號,單獨一顆、無左右對照時不易讀。若灰階 swap,disabled 的 ON 和 OFF track 同灰、主通道消失,使用者難以分辨。必須 opacity 保留顏色"
       >
         <div className="flex items-center gap-4">
           <div className="flex items-center gap-2">

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

@@ -123,7 +123,7 @@ 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
@@ -186,18 +186,18 @@ Radix Slider 原生支援多 thumb——只要 `value` / `defaultValue` 傳長
 
 **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 的位置/長度仍然完全可辨 |
 
 ### 論證摘要
 
-Disabled slider 要傳達的兩件事——thumb 位置、range 長度——**完全不依賴顏色**(灰階後 x 座標與填滿佔比一模一樣),失去藍色零資訊損失,故走灰階派(同 Checkbox:state 由形狀 / 位置承載、顏色是裝飾)。Switch 是唯一 opacity 特例:on/off 無任何形狀差異、顏色本身就是 state,灰階會讓兩態無法區分——此 rationale 不適用 Slider。
+Disabled slider 要傳達的兩件事——thumb 位置、range 長度——**完全不依賴顏色**(灰階後 x 座標與填滿佔比一模一樣),失去藍色零資訊損失,故走灰階派(同 Checkbox:state 由形狀 / 位置承載、顏色是裝飾)。Switch 是唯一 opacity 特例:on/off 的主載體是顏色(thumb 位移 / check icon 只是弱輔助線索),灰階會讓兩態近乎無法區分——此 rationale 不適用 Slider。
 
 ### 為什麼 shadcn / Material 3 用 opacity 仍然不是理由
 
@@ -236,7 +236,7 @@ Slider 無獨立 `readOnly` prop;但在 `<Field mode="readonly">` 內(2026-06-12
 
 - 「Slider 可以當計數器」——錯。Slider 傳達 position(在哪裡),計數(多少)用 NumberInput ±step(見「何時不用」)
 - 「兩個選項可以用 Range mode」——錯。Range 是連續值區間(value = [start, end]),二元 / 布林選擇用 Switch / SegmentedControl
-- 「focus 要加 ring」——本元件 documented 例外:focus 用 border 加深(同 hover 視覺),不加 ring / halo(見「視覺規格」表)
+- 「focus 要加 ring」——本元件 documented 例外:focus 用 border 升 hover 階(`primary-hover`,淺一階 lift;同 hover 視覺),不加 ring / halo(見「視覺規格」表,對齊上方「為什麼 hover / active 用陰影不用色變」)
 
 ---
 

package/src/components/Slider/slider.tsx

@@ -107,7 +107,9 @@ const Slider = React.forwardRef<
           Range 是「填充視覺」,Thumb border 是「thumb 的輪廓線」——視覺上 thumb
           的 border 剛好是 range 的延續(thumb 坐落在 range 的端點上,border 跟
           range 在色彩上融為一體,看起來像「range 包住 thumb」而不是「thumb 浮在
-          range 上」)。兩個 token 綁在一起,不論什麼 state 都一致。
+          range 上」)。兩個 token 綁在一起 —— **同色綁定 scope = rest 與 disabled 兩態**;
+          互動態(hover/active/focus)只動 thumb border 色階,range 填色恆 primary
+          (詳下方 Thumb 註解 2026-07-06 retract)。
         */}
         <SliderPrimitive.Range
           className={cn(

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

@@ -39,7 +39,7 @@ export const Overview: Story = {
               <tr><Td>completed</Td><Td><span className="inline-flex items-center gap-1.5"><Swatch value="--info" size="sm" /><span>filled info + white check icon</span></span></Td><Td><TokenCell token="--fg-secondary" display="fg-secondary" /></Td><Td><TokenCell token="--info" display="bg-info" /></Td></tr>
               <tr><Td>current(= value)</Td><Td><span className="inline-flex items-center gap-1.5"><Swatch value="--info" size="sm" /><span>filled info + white number + ring</span></span></Td><Td><TokenCell token="--foreground" display="foreground" /></Td><Td><TokenCell token="--border" display="bg-border" /></Td></tr>
               <tr><Td>upcoming</Td><Td><span className="inline-flex items-center gap-1.5"><Swatch value="--muted" size="sm" /><span>filled muted + fg-disabled number</span></span></Td><Td><TokenCell token="--fg-secondary" display="fg-secondary" /></Td><Td><TokenCell token="--border" display="bg-border" /></Td></tr>
-              <tr><Td>error</Td><Td><span className="inline-flex items-center gap-1.5"><Swatch value="--error" size="sm" /><span>bg-error + white icon</span></span></Td><Td><TokenCell token="--error-text" display="error-text" /></Td><Td>—</Td></tr>
+              <tr><Td>error</Td><Td><span className="inline-flex items-center gap-1.5"><Swatch value="--error" size="sm" /><span>bg-error + white icon</span></span></Td><Td><TokenCell token="--error-text" display="error-text" /></Td><Td><TokenCell token="--border" display="bg-border" /></Td></tr>
             </tbody>
           </table>
         </div>
@@ -185,7 +185,7 @@ export const ColorMatrix: Story = {
                 <Td mono>completed</Td>
                 <Td><TokenCell token="--info" /></Td>
                 <Td>—(同 bg)</Td>
-                <Td><TokenCell token="white" display="白色 Check icon" /></Td>
+                <Td><TokenCell token="--on-emphasis" display="白色 Check icon" /></Td>
                 <Td><TokenCell token="--fg-secondary" /></Td>
                 <Td><TokenCell token="--info" display="bg-info" /></Td>
               </tr>
@@ -209,9 +209,9 @@ export const ColorMatrix: Story = {
                 <Td mono>error</Td>
                 <Td><TokenCell token="--error" /></Td>
                 <Td>—(同 bg)</Td>
-                <Td><TokenCell token="white" display="白色 X icon" /></Td>
+                <Td><TokenCell token="--on-emphasis" display="白色 X icon" /></Td>
                 <Td><TokenCell token="--error-text" /></Td>
-                <Td>—</Td>
+                <Td><TokenCell token="--border" display="bg-border" /></Td>
               </tr>
             </tbody>
           </table>

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

@@ -263,7 +263,7 @@ export const LinearBackClickDoesNotMutate: Story = {
     return (
       <Section
         title="點 completed step 只改 focus(value),不會自動取消完成狀態"
-        subtitle="Steps 是純 controlled 元件,從不偷偷 mutate parent state。若應用層需要「使用者改錯了就 block 後續」,應由應用層自己從 completedValues 移除,Steps 內部絕不 auto-remove。"
+        subtitle="Steps 的進度狀態由 parent own(value 為 controlled / uncontrolled defaultValue 雙模),從不偷偷 mutate parent 的 completedValues。若應用層需要「使用者改錯了就 block 後續」,應由應用層自己從 completedValues 移除,Steps 內部絕不 auto-remove。"
       >
         <div className="flex flex-col gap-3 w-[360px]">
           <p className="text-caption text-fg-secondary">

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

@@ -284,7 +284,7 @@ disabled > error > focused > default
 
 ### 為什麼 error label 要跟 indicator 同色
 
-Steps 的 step 本身是「狀態載體」,跟 Field 的「label 只是欄位名,error 靠 help text 表達」不同。Steps 的 label 在視覺上屬於 indicator 的延伸資訊,兩者應該一起講故事:紅 ✕ indicator + 紅 label + 紅 description(如有)形成一致的 error visual language,讓使用者一眼看出這步出了什麼錯。
+Steps 的 step 本身是「狀態載體」,跟 Field 的「label 只是欄位名,error 靠 help text 表達」不同。Steps 的 label 在視覺上屬於 indicator 的延伸資訊,兩者應該一起講故事:紅 ✕ indicator + 紅 label 形成一致的 error visual language,讓使用者一眼看出這步出了什麼錯(description 不變色,見下段)。
 
 這跟 `CLAUDE.md` 的「Label 永遠 foreground」原則不衝突——那是 Field 家族的規則(edit / readonly / disabled 三態的欄位容器)。Steps 是**進度指示器**不是**輸入容器**,label 色彩跟著 step state 走是正確做法。
 

package/src/components/Switch/switch.anatomy.stories.tsx

@@ -38,14 +38,14 @@ export const Overview: Story = {
             <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
             <tbody>
               {[
-                ['mode', "'edit' | 'display' | 'readonly' | 'disabled'", "'edit'", 'Field mode(默認 inherit Field context 或 edit);display 渲純展示 ✓/—,語意由 context 提供'],
+                ['mode', "'edit' | 'display' | 'readonly' | 'disabled'", "'edit'", 'Field mode(默認 inherit Field context 或 edit);display 渲純展示 勾/叉 icon,語意由 context 提供'],
                 ['size', "'sm' | 'md' | 'lg'", "'md'", '對齊 field size tier(sm 跟 md 視覺相同)'],
                 ['checked / defaultChecked', 'boolean', '—', 'ON/OFF 狀態(受控 / 非受控)'],
                 ['onCheckedChange', '(checked: boolean) => void', '—', '切換 callback'],
                 ['label', 'ReactNode', '—', 'inline label(Field context 內會被忽略)'],
                 ['description', 'ReactNode', '—', 'inline description(與 label 搭配)'],
                 ['disabled', 'boolean', 'false', '停用(opacity-disabled 保留顏色,見 spec)'],
-                ['readOnly', 'boolean', 'false', 'standalone:鎖定互動視覺正常;Field 內:灰框 + ✓/—(2026-06-12 拍板)'],
+                ['readOnly', 'boolean', 'false', 'standalone:鎖定互動視覺正常;Field 內:灰框 + 勾/叉 icon(2026-06-12 拍板)'],
               ].map(([p, t, d, desc]) => (
                 <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>
               ))}
@@ -78,7 +78,7 @@ export const Inspector: InspectorStory = {
     mode: {
       control: 'radio',
       options: ['edit', 'display', 'readonly', 'disabled'],
-      description: 'Field mode;display 渲純展示 ✓/—(語意由 context 提供)',
+      description: 'Field mode;display 渲純展示 勾/叉 icon(語意由 context 提供)',
     },
     size: {
       control: 'radio',
@@ -87,7 +87,7 @@ export const Inspector: InspectorStory = {
     },
     defaultChecked: { control: 'boolean', description: '預設 ON / OFF' },
     disabled: { control: 'boolean', description: '停用(opacity-disabled 保留顏色)' },
-    readOnly: { control: 'boolean', description: '唯讀(standalone 視覺正常鎖互動;Field 內灰框 + ✓/—)' },
+    readOnly: { control: 'boolean', description: '唯讀(standalone 視覺正常鎖互動;Field 內灰框 + 勾/叉 icon)' },
     label: { control: 'text', description: 'inline label(留空 → 只渲染 switch 本體)' },
     description: { control: 'text', description: 'inline description(需搭配 label)' },
   },
@@ -135,7 +135,7 @@ export const StateBehavior: Story = {
     <div className="flex flex-col gap-8">
       <div>
         <H3>視覺狀態對照</H3>
-        <Desc>disabled 用 opacity-disabled 保留顏色(Switch 特例,見下「Disabled 策略」)。readonly:standalone 視覺正常鎖互動;Field 內灰框 + ✓/—。</Desc>
+        <Desc>disabled 用 opacity-disabled 保留顏色(Switch 特例,見下「Disabled 策略」)。readonly:standalone 視覺正常鎖互動;Field 內灰框 + 勾/叉 icon。</Desc>
         <div className="overflow-x-auto mb-4">
           <table className="text-caption border-collapse">
             <thead><tr><Th>State</Th><Th>Track</Th><Th>Thumb</Th><Th>Check icon</Th></tr></thead>
@@ -178,8 +178,8 @@ export const StateBehavior: Story = {
 
       <div>
         <H3>Disabled 策略:opacity 而非灰階 swap</H3>
-        <Desc>Switch 的 on/off 視覺差異**唯一載體是顏色**(track bg-primary vs bg-border)——track 和 thumb 在 on/off 之間形狀完全相同。若用灰階 swap(把 primary 換成 border),disabled 的 ON 和 OFF 會看起來一模一樣,使用者無法分辨當前狀態。必須保留顏色。</Desc>
-        <p className="text-footnote text-fg-muted">對照 Checkbox / Slider 用灰階弱化(它們的形狀或位置本身就承載開 / 關狀態,不靠顏色),所以灰掉也看得出狀態;Switch 只靠顏色,只能降透明度保留顏色。</p>
+        <Desc>Switch 的 on/off 視覺差異**最強載體是顏色**(track bg-primary vs bg-border)——thumb 位移與 check icon 只是弱輔助線索。若用灰階 swap(把 primary 換成 border),disabled 的 ON 和 OFF 只剩灰階低對比下的位置與小 icon 差異,難以一眼分辨當前狀態。必須保留顏色。</Desc>
+        <p className="text-footnote text-fg-muted">對照 Checkbox / Slider 用灰階弱化(它們的形狀或位置本身就承載開 / 關狀態,不靠顏色),所以灰掉也看得出狀態;Switch 的主載體是顏色,只能降透明度保留顏色。</p>
       </div>
     </div>
   ),

package/src/components/Switch/switch.principles.stories.tsx

@@ -116,7 +116,7 @@ export const UsageGuidance: Story = {
 
       <Rule
         title="使用場景對照"
-        note="Readonly(standalone settings list):值重要、視覺不能弱化。表單 readonly = Field 內灰框 + ✓/—(2026-06-12 拍板);DataTable cell 非編輯態 = mode display。Disabled:外部條件造成暫時不可用(方案限制、權限不足)——傳達「現在用不到」"
+        note="Readonly(standalone settings list):值重要、視覺不能弱化。表單 readonly = Field 內灰框 + 勾/叉 icon(2026-06-12 拍板);DataTable cell 非編輯態 = mode display。Disabled:外部條件造成暫時不可用(方案限制、權限不足)——傳達「現在用不到」"
       >
         <Label>兩者都不可切換、不在 tab order 內(standalone),機制不同:readonly 用 `pointer-events-none`(視覺正常);disabled 走 native `disabled` + `cursor-not-allowed`(降透明度)。Field 內 readonly 灰框則可聚焦(tabIndex=0)</Label>
       </Rule>
@@ -132,7 +132,7 @@ export const DisabledOpacityRule: Story = {
     <div>
       <Rule
         title="Switch disabled 用 opacity,不用灰階 swap"
-        note="Switch 的 on/off 視覺差異**唯一載體是顏色**(track bg-primary vs bg-border)——track 和 thumb 在 on/off 之間形狀完全相同,只有顏色變。若灰階 swap(primary → border),disabled 的 ON 和 OFF 會看起來一模一樣,使用者無法分辨當前狀態"
+        note="Switch 的 on/off 最強視覺載體是顏色(track bg-primary vs bg-border);thumb 位移與 checked 小 check icon 是輔助線索。若灰階 swap(primary → border),disabled 的 ON/OFF 只剩灰階低對比下的位置與小 icon 差異,難以一眼分辨當前狀態"
       >
         <div className="grid grid-cols-2 gap-4">
           <div className="border border-dashed border-divider rounded-md p-3">
@@ -164,9 +164,9 @@ export const DisabledOpacityRule: Story = {
 
       <Rule
         title="❌ 若 Switch 改用灰階 swap"
-        note="disabled ON 和 disabled OFF 都會變成「灰 track + 灰 thumb」,視覺一模一樣——使用者不知道這個被停用的開關當前是開還是關"
+        note="disabled ON 和 disabled OFF 都會退成「灰 track + 灰 thumb」——殘餘線索只剩 thumb 位置與 thumb 內小 check icon,在灰階低對比下辨識度大幅下降,使用者難以一眼判斷被停用的開關當前是開還是關"
       >
-        <Label warn>設計上禁止——Switch 是系統內唯一靠顏色承載 state 的元件,必須保留顏色</Label>
+        <Label warn>設計上禁止——Switch 的 on/off 最強視覺載體是顏色(thumb 位置 / check icon 只是輔助線索),disabled 必須保留顏色</Label>
       </Rule>
     </div>
   ),

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

@@ -104,22 +104,22 @@ sm 和 md 視覺相同（純粹命名 mapping，讓消費者可直接傳同一
 | ON | `bg-primary` | 白色 + 2px primary border | primary check |
 | Disabled | 套 `opacity-disabled`（整體透明度降級） | 同 ON/OFF | 同 ON/OFF |
 | 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 | — |
+| Readonly(Field 內,2026-06-12 user 拍板)| 不渲染 toggle — 改渲染 `fieldWrapperStyles` readonly 灰框(= Input readonly 同源)+ 勾/叉 icon(display 同款值語言) | role="switch" + aria-checked + aria-readonly + 可 focus | — |
 
 ### Disabled 用 `opacity`
 
 **不用灰階 swap**——這是 Switch 的**特例**,跟 Checkbox / Button / Slider 的灰階策略不同。
 
-**理由**：Switch 的 on/off 視覺差異**唯一載體是顏色**（track `bg-primary` vs `bg-border`）——track 和 thumb 在 on/off 之間形狀完全相同，只有顏色變。若用灰階 swap（把 primary 換成 border），disabled 的 ON 跟 OFF 會合併成同一視覺態,使用者無法分辨當前狀態(螢幕閱讀器只能靠 `aria-checked` 區分)。
+**理由**：Switch 的 on/off 視覺差異**最強載體是顏色**（track `bg-primary` vs `bg-border`）——thumb 位置（translate-x）與 thumb 內 check icon 雖有差異,但屬弱輔助線索。若用灰階 swap（把 primary 換成 border），disabled 的 ON 跟 OFF 只剩灰階下低對比的位置/小 icon 差異,辨識度大幅下降,使用者難以一眼分辨當前狀態。
 
 **對照**：
 - Checkbox disabled 可以灰階 swap——checkmark 形狀承載 state，顏色只是裝飾
 - Slider disabled 可以灰階 swap——thumb 位置和 range 長度承載 state
-- Switch disabled **必須保留顏色**——沒有形狀差異，灰階後 state 失傳
+- Switch disabled **必須保留顏色**——主載體是顏色,灰階後殘餘線索太弱,state 近乎失傳
 
 詳細對照見 `../Slider/slider.spec.md`「Disabled 策略」節。
 
-### Readonly vs Disabled(standalone;Field 內 readonly = 灰框 + ✓/—,見上方狀態表)
+### Readonly vs Disabled(standalone;Field 內 readonly = 灰框 + 勾/叉 icon,見上方狀態表)
 
 | | Readonly(standalone) | Disabled |
 |---|---|---|
@@ -129,14 +129,14 @@ sm 和 md 視覺相同（純粹命名 mapping，讓消費者可直接傳同一
 | Tab 焦點 | 不在 tab order | 不在 tab order |
 | 用途 | settings list 鎖定呈現 | 外部條件造成不可操作 |
 
-表單 readonly 呈現 = Field 內灰框 + ✓/—(2026-06-12 拍板);DataTable cell 非編輯態 = `mode="display"`(✓/—),皆非本表 standalone readonly。
+表單 readonly 呈現 = Field 內灰框 + 勾/叉 icon(2026-06-12 拍板);DataTable cell 非編輯態 = `mode="display"`(勾/叉 icon),皆非本表 standalone readonly。
 
 ### `mode` prop(Field mode,正交於 size)
 
 `mode?: 'edit' | 'display' | 'readonly' | 'disabled'`(默認 inherit Field context 或 `'edit'`),對齊 `field-types.ts` FieldMode：
 - `edit`(預設)— 可切換的 Switch。
-- `display` — **純展示**:渲染 ✓ / —(非互動 Switch),語意由 context(如 DataTable boolean cell 的行/列 header)提供,對齊 Carbon read-only / Input·Select·Textarea display mode 一致。
-- `readonly` — **Field 內** = 灰框 + ✓/—(消費 `fieldWrapperStyles` readonly,與 Input readonly 同一視覺語言;世界級:Salesforce output ✓ glyph / SAP 靜態文字 — readonly 下 boolean 是資料 value 非控件);**standalone** = 正常色鎖互動(settings list 場景)。
+- `display` — **純展示**:渲染 勾/叉 icon(非互動 Switch;true=Check / false=X,中性 foreground 色,SSOT = `../SelectionControl/boolean-value.tsx`),語意由 context(如 DataTable boolean cell 的行/列 header)提供,對齊 Carbon read-only / Input·Select·Textarea display mode 一致。<!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- `readonly` — **Field 內** = 灰框 + 勾/叉 icon(消費 `fieldWrapperStyles` readonly,與 Input readonly 同一視覺語言;世界級:Salesforce output ✓ glyph / SAP 靜態文字 — readonly 下 boolean 是資料 value 非控件);**standalone** = 正常色鎖互動(settings list 場景)。
 - `disabled` — 同上表「Readonly vs Disabled」(opacity 弱化);`mode='disabled'` 直傳與 `disabled` prop 等效(effectiveDisabled,2026-06-12)。
 
 ---
@@ -194,7 +194,7 @@ Switch 可透過 `label` / `description` props 內部直接渲染緊鄰文字：
 
 - ❌ 用 Switch 做 form 內的同意 / 勾選——「我同意條款」是書面成立行為，用 Checkbox
 - ❌ 把 Switch 當三態使用（例：「on / off / auto」）——用 RadioGroup / SegmentedControl
-- ❌ 對 disabled 狀態用灰階 swap 而非 opacity——會讓 on/off 視覺無法區分（見「Disabled 用 opacity」段）
+- ❌ 對 disabled 狀態用灰階 swap 而非 opacity——會讓 on/off 視覺近乎無法區分（見「Disabled 用 opacity」段）
 - ❌ Switch 的 on/off 顯示「正在處理中」進度——用 Button + loading state
 - ❌ 直接改動 track 顏色承載額外語意（例如 error 時改紅）——Switch 是單純布林，錯誤訊息放外部 help text
 

package/src/components/Switch/switch.stories.tsx

@@ -1,7 +1,6 @@
 // @story-trait-rationale: hasSizes 由 anatomy.stories.tsx SizeMatrix / 狀態(States)story 的 md/lg 對照 owns size showcase;Default scenario 由 四模式(Modes) / 狀態(States) / 搭配標籤(WithLabel)等真實業務情境 story 覆蓋,不另開抽象 Default/AllSizes。
 import type { Meta, StoryObj } from '@storybook/react'
 import { Switch } from './switch'
-import { SelectionItem } from '@/design-system/components/SelectionControl/selection-item'
 
 const meta: Meta<typeof Switch> = {
   title: 'Design System/Components/Switch/展示',
@@ -23,7 +22,7 @@ export const Modes: Story = {
       <div>
         <h3 className="text-body font-bold text-foreground mb-2">display</h3>
         <Switch mode="display" checked />
-        <p className="text-caption text-fg-muted mt-1">純視覺 ✓ / —；語意由 context（如 DataTable 表頭 + 行標籤）提供，display 不暴露獨立 aria-label。需螢幕報讀器可讀請用 edit / readonly。</p>
+        <p className="text-caption text-fg-muted mt-1">純視覺 勾/叉 icon；語意由 context（如 DataTable 表頭 + 行標籤）提供，display 不暴露獨立 aria-label。需螢幕報讀器可讀請用 edit / readonly。</p>
       </div>
       <div>
         <h3 className="text-body font-bold text-foreground mb-2">readonly</h3>
@@ -70,7 +69,10 @@ export const States: Story = {
   ),
 }
 
-/* ── 搭配 SelectionItem ── */
+/* ── 搭配標籤 ── */
+// 2026-07-14 dim-68 修:原直用 internal <SelectionItem control={...}>(selection-item.spec.md
+// 明定僅 Checkbox / RadioGroup 消費路徑;Switch 不在其中)→ 改公開 `<Switch label description>`
+// (switch.spec.md「label / description 整合」canonical:label 左 / switch 右,自動 wire htmlFor)。
 export const WithLabel: Story = {
   name: '搭配標籤',
   render: () => (
@@ -78,27 +80,10 @@ export const WithLabel: Story = {
       {(['sm', 'md', 'lg'] as const).map(size => (
         <div key={size}>
           <p className="text-caption text-fg-muted mb-1">size="{size}"</p>
-          <div className="grid">
-            <SelectionItem
-              size={size}
-              control={<Switch id={`sw-${size}-a`} size={size} defaultChecked />}
-              label="啟用通知"
-              description="接收電子郵件和推播通知"
-              htmlFor={`sw-${size}-a`}
-            />
-            <SelectionItem
-              size={size}
-              control={<Switch id={`sw-${size}-b`} size={size} />}
-              label="自動更新"
-              htmlFor={`sw-${size}-b`}
-            />
-            <SelectionItem
-              size={size}
-              control={<Switch id={`sw-${size}-c`} size={size} disabled />}
-              label="維護模式（管理員限定）"
-              htmlFor={`sw-${size}-c`}
-              disabled
-            />
+          <div className="grid gap-2">
+            <Switch size={size} defaultChecked label="啟用通知" description="接收電子郵件和推播通知" />
+            <Switch size={size} label="自動更新" />
+            <Switch size={size} disabled label="維護模式（管理員限定）" />
           </div>
         </div>
       ))}

package/src/components/Switch/switch.tsx

@@ -7,6 +7,7 @@ import { cn } from '@/lib/utils'
 import type { FieldMode, FieldVariant } from '@/design-system/components/Field/field-types'
 import { useFieldContext, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldSize } from '@/design-system/components/Field/field-context'
 import { fieldWrapperStyles } from '@/design-system/components/Field/field-wrapper'
+import { BooleanValueIcon } from '@/design-system/components/SelectionControl/boolean-value'
 
 /**
  * Switch — 開關控件
@@ -24,7 +25,7 @@ import { fieldWrapperStyles } from '@/design-system/components/Field/field-wrapp
  *   ON:  track primary, thumb 白色 + 2px primary border + primary check icon
  *   disabled: opacity-disabled（整體透明度）
  *   readOnly(standalone): 視覺同一般態，但 pointer-events-none + aria-readonly
- *   readOnly(Field 內): 渲染 readonly 灰框 + ✓/—(2026-06-12 拍板,= Input readonly 同視覺語言)
+ *   readOnly(Field 內): 渲染 readonly 灰框 + 勾/叉 icon(2026-06-12 拍板,= Input readonly 同視覺語言)
  *
  * ── label / description / readOnly ──
  * Switch 可以透過 `label` 和 `description` props 在元件內直接渲染緊鄰的文字，
@@ -45,7 +46,7 @@ import { fieldWrapperStyles } from '@/design-system/components/Field/field-wrapp
  * readOnly 模式：
  *   <Switch readOnly checked={true} label="..." />
  *   standalone:視覺維持 ON/OFF 正確狀態,但無法互動、不在 tab order 內、寫入 aria-readonly。
- *   Field 內:渲染 readonly 灰框 + ✓/—(不渲染 toggle;見 forwardRef 內 readonly 分支)。
+ *   Field 內:渲染 readonly 灰框 + 勾/叉 icon(不渲染 toggle;見 forwardRef 內 readonly 分支)。
  *   與 disabled 的差異：readonly 不降色（可讀），disabled 降色（弱化）。
  */
 
@@ -110,18 +111,18 @@ export interface SwitchProps
    */
   description?: React.ReactNode
   /**
-   * readonly 模式:standalone = 鎖定互動但維持 ON/OFF 視覺;Field 內 = 灰框 + ✓/—。
+   * readonly 模式:standalone = 鎖定互動但維持 ON/OFF 視覺;Field 內 = 灰框 + 勾/叉 icon。
    * 與 disabled 的差異:readonly 不降色(可讀),disabled 降色(弱化)。
-   * DataTable cell 非編輯態用 mode="display"(✓/—),非 readOnly。
+   * DataTable cell 非編輯態用 mode="display"(勾/叉 icon),非 readOnly。
    */
   readOnly?: boolean
   /**
    * Field mode(2026-05-05 Phase B3 align):
    *   edit     — 一般可互動 Switch(預設)
-   *   display  — **純展示**:渲染 ✓ / —(無互動 primitive、無 input chrome);
+   *   display  — **純展示**:渲染 勾/叉 icon(無互動 primitive、無 input chrome);
    *              對齊 Carbon read-only / DataTable boolean cell。
    *              `display` 完全無 toggle 形體;`readonly` 視場景(field-types.ts)。
-   *   readonly — standalone 同 readOnly prop(保留視覺鎖互動);Field 內 = 灰框 + ✓/—
+   *   readonly — standalone 同 readOnly prop(保留視覺鎖互動);Field 內 = 灰框 + 勾/叉 icon
    *   disabled — 同 disabled prop
    */
   mode?: FieldMode
@@ -200,17 +201,20 @@ const Switch = React.forwardRef<
     } = props
 
     // ── mode='display'(下移至所有 hooks 之後,per #35 Rules of Hooks)──────────
-    // 純展示模式:無互動 toggle、渲染 ✓ / —。與 Checkbox display 對齊(同 boolean primitive)。
+    // 純展示模式:無互動 toggle、渲染 Check / X icon。與 Checkbox display 對齊(同 boolean primitive,
+    // 共用 SelectionControl/boolean-value.tsx SSOT — 勾/叉 icon + 中性 foreground 色)。
     if (resolvedMode === 'display') {
       const isChecked = checkedProp === true
-      return isChecked
-        ? <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>
+      return (
+        <span {...restDomProps} ref={ref as React.Ref<HTMLSpanElement>} className="inline-flex">
+          <BooleanValueIcon checked={isChecked} size={resolvedBoxSize} />
+        </span>
+      )
     }
 
-    // ── mode='readonly' in Field(2026-06-12 user 拍板「灰框 + ✓/—」,與 Checkbox 同款)──
+    // ── mode='readonly' in Field(2026-06-12 拍板「灰框 + 勾/叉」,與 Checkbox 同款;2026-07-09 glyph → Check/X icon)──
     // Field 內 readonly boolean = fieldWrapperStyles readonly 灰框(= Input readonly 同源)
-    // + ✓/— 值語言;standalone readOnly(settings list)維持原樣鎖互動。詳 checkbox.tsx 同段註解。
+    // + 勾/叉 icon 值語言;standalone readOnly(settings list)維持原樣鎖互動。詳 checkbox.tsx 同段註解。
     if (effectiveReadOnly && insideField) {
       const isChecked = (checkedProp ?? defaultCheckedProp) === true
       const boxSize = resolvedBoxSize
@@ -231,7 +235,7 @@ const Switch = React.forwardRef<
             className,
           )}
         >
-          {isChecked ? <span className="text-foreground">✓</span> : <span className="text-fg-muted">—</span>}
+          <BooleanValueIcon checked={isChecked} size={boxSize} />
         </div>
       )
     }