@qijenchen/design-system 0.1.0-beta.64 → 0.1.0-beta.65

package/src/components/RadioGroup/radio-group.tsx

@@ -6,11 +6,11 @@ import { cva, type VariantProps } from "class-variance-authority"
 
 import { cn } from "@/lib/utils"
 import type { FieldMode, FieldVariant } from "@/design-system/components/Field/field-types"
-import { useResolvedFieldMode, useResolvedFieldDisabled } from "@/design-system/components/Field/field-context"
+import { useFieldContext, useResolvedFieldMode, useResolvedFieldDisabled, useResolvedFieldSize } from "@/design-system/components/Field/field-context"
 import { SelectionItem } from "@/design-system/components/SelectionControl/selection-item"
 import type { LucideIcon } from "lucide-react"
 import type { AvatarData } from "@/design-system/components/Avatar/avatar"
-import { EMPTY_DISPLAY } from "@/design-system/components/Field/field-wrapper"
+import { EMPTY_DISPLAY, fieldWrapperStyles } from "@/design-system/components/Field/field-wrapper"
 
 // ── RadioGroup display mode ─────────────────────────────────────────────────
 // RadioGroup mode='display' 時:Group 不渲染 Radix primitive(無 radio 視覺),
@@ -29,7 +29,7 @@ export interface RadioGroupProps
    *   display  — **純展示**:不渲染 Radix Root / 任何 radio 視覺;RadioGroup 本體 walk
    *              children,僅 control.value === group.value 那筆把 label 渲染為純文字 span。
    *              對齊 Carbon read-only / DataTable single-select cell read mode。
-   *   readonly — 同 child item 各自 readOnly:radio 視覺保留 + 鎖互動
+   *   readonly — standalone:ReadonlyContext 傳 items 鎖互動保留視覺;Field 內:灰框 + 選中項 label(不渲染 radio 群組)
    *   disabled — 同 RadioGroupPrimitive.Root disabled 屬性
    */
   mode?: FieldMode
@@ -44,12 +44,38 @@ export interface RadioGroupProps
 // (item 已支援 readOnly prop + data-[readonly] 樣式;Radix Root 無 readOnly,故用 context)。
 const RadioGroupReadonlyContext = React.createContext(false)
 
+// walk children 找 control.value === selectedValue 的 SelectionItem label(display / readonly-in-Field 共用)
+function findSelectedRadioLabel(children: React.ReactNode, selectedValue: string | undefined): React.ReactNode {
+  let selectedLabel: React.ReactNode = null
+  React.Children.forEach(children, (child) => {
+    if (!React.isValidElement(child)) return
+    const cProps = child.props as { control?: unknown; label?: React.ReactNode; value?: unknown }
+    // 形狀 1:<RadioGroupItem value label>(主用法)— value/label 直掛 props
+    if (cProps.value === selectedValue && cProps.value !== undefined) {
+      selectedLabel = cProps.label ?? selectedValue
+      return
+    }
+    // 形狀 2:<SelectionItem control={<RadioGroupItem value/>} label>(組合用法)
+    const control = cProps.control
+    if (React.isValidElement(control)) {
+      const controlValue = (control.props as { value?: unknown }).value
+      if (controlValue === selectedValue) {
+        selectedLabel = cProps.label ?? selectedValue
+      }
+    }
+  })
+  return selectedLabel
+}
+
 const RadioGroup = React.forwardRef<
   React.ElementRef<typeof RadioGroupPrimitive.Root>,
   RadioGroupProps
 >(({ className, mode, variant: _chrome, value, defaultValue, ...props }, ref) => {
   // 2026-06-08 SSOT cascade:resolvedMode 經 resolver hook 讀 fieldCtx(原 root 完全不讀 → <Field disabled>/<Field mode> 失效)
   const resolvedMode = useResolvedFieldMode({ mode, disabled: (props as { disabled?: boolean }).disabled })
+  const fieldCtx = useFieldContext()
+  // readonly 灰框 size:走 SSOT resolver(RadioGroup 無 size prop → ctx > 'md')
+  const resolvedBoxSize = useResolvedFieldSize(undefined, 'md') as 'sm' | 'md' | 'lg'
   // mode='display' — 純展示 selected option 的 label,不渲染任何 radio control 視覺。
   // 對齊 Carbon read-only single-select(只顯示 selected 內容)+ Airtable / Notion read-only。
   // 實作:walk children 找 control.value === selectedValue 的 SelectionItem,render label plain text。
@@ -59,18 +85,7 @@ const RadioGroup = React.forwardRef<
     if (!selectedValue) {
       return <div role="group" className={cn('grid', className)}><span className="text-fg-muted">{EMPTY_DISPLAY}</span></div>
     }
-    let selectedLabel: React.ReactNode = null
-    React.Children.forEach(props.children, (child) => {
-      if (!React.isValidElement(child)) return
-      const cProps = child.props as { control?: unknown; label?: React.ReactNode }
-      const control = cProps.control
-      if (React.isValidElement(control)) {
-        const controlValue = (control.props as { value?: unknown }).value
-        if (controlValue === selectedValue) {
-          selectedLabel = cProps.label ?? selectedValue
-        }
-      }
-    })
+    const selectedLabel = findSelectedRadioLabel(props.children, selectedValue)
     return (
       <div role="group" className={cn('grid', className)}>
         <span className="text-foreground">{selectedLabel ?? selectedValue}</span>
@@ -78,6 +93,35 @@ const RadioGroup = React.forwardRef<
     )
   }
 
+  // ── mode='readonly' in Field(2026-06-12 user 拍板,與 Checkbox/Switch 灰框模型一致)──
+  // Field 內 readonly 單選 = fieldWrapperStyles readonly 灰框 + 選中項 label 文字
+  // (= Select readonly 同款呈現:同為「單選資料」,鎖定時呈現一致)。
+  // standalone readonly(無 Field)維持原樣鎖互動(ReadonlyContext 路徑)。
+  if (resolvedMode === 'readonly' && fieldCtx?.hasFieldWrapper === true) {
+    const selectedValue = (value ?? defaultValue) as string | undefined
+    const selectedLabel = selectedValue ? findSelectedRadioLabel(props.children, selectedValue) : null
+    const boxSize = resolvedBoxSize
+    return (
+      <div
+        role="radiogroup"
+        aria-readonly="true"
+        aria-labelledby={fieldCtx?.labelId}
+        aria-invalid={fieldCtx?.invalid || undefined}
+        data-readonly="true"
+        tabIndex={0}
+        className={cn(
+          fieldWrapperStyles({ size: boxSize, mode: 'readonly', variant: 'default' }),
+          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+          className,
+        )}
+      >
+        {selectedValue
+          ? <span className="text-foreground">{selectedLabel ?? selectedValue}</span>
+          : <span className="text-fg-muted">{EMPTY_DISPLAY}</span>}
+      </div>
+    )
+  }
+
   // mode='disabled' → Radix Root disabled(原生 propagate 給所有 item);
   // mode='readonly' → context 傳 readOnly 給 items(item 渲染為 data-[readonly] 鎖互動 + aria-readonly)。
   return (

package/src/components/Rating/rating.tsx

@@ -2,7 +2,7 @@
 import * as React from 'react'
 import { Star, type LucideIcon } from 'lucide-react'
 import { cn } from '@/lib/utils'
-import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled } from '@/design-system/components/Field/field-context'
+import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode } from '@/design-system/components/Field/field-context'
 
 /**
  * Rating — 星星評分元件
@@ -98,7 +98,7 @@ const Rating = React.forwardRef<HTMLDivElement, RatingProps>(
       max = 5,
       size: sizeProp,
       precision = 'full',
-      readOnly = false,
+      readOnly: readOnlyProp = false,
       disabled: disabledProp,
       loading = false,
       icon: Icon = Star,
@@ -115,6 +115,10 @@ const Rating = React.forwardRef<HTMLDivElement, RatingProps>(
     const fieldCtx = useFieldContext()  // 保留:aria-labelledby 用 fieldCtx.labelId
     // 2026-06-08 SSOT:<Field disabled> cascade(原 isInteractive 只看 local disabled prop)
     const disabled = useResolvedFieldDisabled(disabledProp)
+    // <Field mode="readonly"> cascade(2026-06-12 補):Rating 的 readonly 呈現 = 星星本身
+    // (星星即值語言,role=img,全業界 review-stars canonical)——不包灰框,只鎖互動。
+    const resolvedMode = useResolvedFieldMode({ mode: undefined, disabled, readOnly: readOnlyProp })
+    const readOnly = readOnlyProp || resolvedMode === 'readonly'
     const size = useResolvedFieldSize<'xs' | 'sm' | 'md' | 'lg'>(sizeProp, 'xs')  // SSOT:統一 size resolution(Rating default 'xs')
     const [internalValue, setInternalValue] = React.useState(defaultValue)
     const [hoverValue, setHoverValue] = React.useState<number | null>(null)
@@ -157,7 +161,7 @@ const Rating = React.forwardRef<HTMLDivElement, RatingProps>(
         //   Standalone → 仍需 consumer 傳 aria-label。對齊 TimePicker / DatePicker 同 canonical
         //   (time-picker.tsx:313 / date-picker.tsx:514:aria-labelledby={fieldCtx?.labelId})。
         //   置於 {...props} 前,consumer 顯式傳的 aria-labelledby 仍可覆寫。
-        aria-labelledby={isInteractive ? fieldCtx?.labelId : undefined}
+        aria-labelledby={fieldCtx?.labelId}  // 2026-06-12 修:readonly/disabled(role=img)也需 accessible name,labelledby 對 img 合法
         aria-valuenow={isInteractive ? currentValue : undefined}
         aria-valuemin={isInteractive ? 0 : undefined}
         aria-valuemax={isInteractive ? max : undefined}

package/src/components/Sidebar/sidebar.spec.md

@@ -130,6 +130,8 @@ SidebarProvider              ← 全域 context（open 狀態、cookie、快捷
 
 **Chrome header 不跟 size 變**：`SidebarHeader` / `SidebarFooter` 固定用 `var(--chrome-header-height)`,只跟 **density** 連動,不跟 `size` prop 變——因為 header 是結構槽位,不是 row。
 
+**SidebarHeader brand 必單行(2026-06-12 明文,fork drift anchor)**:Avatar 24 + 名稱單行,**無副標 slot**——Fixed-h chrome 結構上不可成長;plan/org 等第二行資訊歸 workspace switcher dropdown row,對齊 Slack/Notion/Linear 現行版單行。shadcn TeamSwitcher demo 的「Acme Inc + Enterprise」兩行是 demo 慣例非本 DS canonical(fork repo AI 曾以訓練先驗在 spec 沉默處回填此副標)。Registry antiPattern `sidebar-header-subtitle-second-line` 機械攔(flex-col 直接子層簽名)。
+
 ---
 
 ## 內容形態選擇（核心設計決策）

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

@@ -104,7 +104,8 @@ export const ColorMatrix: Story = {
               <tr><Td>Range 填滿色 default</Td><Td><TokenCell token="--primary" display="bg-primary" /></Td><Td><TokenCell token="--primary" /></Td></tr>
               <tr><Td>Range 填滿色 disabled</Td><Td><TokenCell token="--border" display="bg-border" /></Td><Td><TokenCell token="--border" display="--border(neutral-5)" /></Td></tr>
               <tr><Td>Thumb 直徑</Td><Td mono>16px(h-4 w-4)</Td><Td>—</Td></tr>
-              <tr><Td>Thumb 底色</Td><Td><TokenCell token="--surface" display="bg-surface(白,default+disabled 不變)" /></Td><Td><TokenCell token="--surface" /></Td></tr>
+              <tr><Td>Thumb 底色 rest</Td><Td><TokenCell token="--on-emphasis" display="bg-on-emphasis(白,深淺不反轉)" /></Td><Td><TokenCell token="--on-emphasis" /></Td></tr>
+              <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>

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

@@ -101,7 +101,8 @@ Slider 接收 `size?: 'sm' | 'md' | 'lg'` prop(預設 `md`),**這個 prop 只決
 | **Range** 填滿色 rest | `bg-primary` | `--primary` |
 | **Range** 填滿色 disabled | `bg-border`(neutral-5)| `--border` |
 | **Thumb** 直徑 | 16px | — |
-| **Thumb** 底色(rest + disabled 不變)| `bg-surface`(白) | `--surface` |
+| **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` |
@@ -191,11 +192,11 @@ Radix Slider 原生支援多 thumb——只要 `value` / `defaultValue` 傳長
 
 | State | 視覺 | 觸發 |
 |---|---|---|
-| Rest | track `bg-secondary`,range `bg-primary`,thumb `bg-surface + border-primary` | 預設 |
+| 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 聚焦 |
-| Disabled | 灰階降級:range `bg-border`、thumb `border-border`(= range 同 token)、thumb bg 保留 `bg-surface` 白底、`cursor-not-allowed`、hover 陰影關閉 | `disabled` prop 或 Field context disabled |
+| 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)。
 
@@ -208,7 +209,7 @@ track (muted, n-2) < range = thumb border (border, n-5) < text (n-7+)
 **三階**,不是四階。Range 和 Thumb border 刻意用同一個 token(見前面「Range 色 ↔ Thumb border 色的綁定規則」),不拆成兩階。
 
 - **Track n-2**:最底的凹槽底線
-- **Range + Thumb border n-5**:同層——thumb border 是 range 的連續視覺,兩者融為一體;thumb 的 fill 保持 surface 色,與 range fill 對比,位置由 range 的長度段決定
+- **Range + Thumb border n-5**:同層——thumb border 是 range 的連續視覺,兩者融為一體;thumb 的 fill(rest 白 / disabled canvas)與 range fill 對比,位置由 range 的長度段決定
 - **Text n-7+**:label / description 在所有視覺元件之上
 
 ### 為什麼 range disabled 不用 `--fg-disabled`
@@ -267,7 +268,7 @@ Switch 是**唯一需要 opacity 的特例**,因為它的 on/off 沒有任何形
 
 ### 常見錯誤(避免)
 
-**不要把 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 +276,9 @@ Switch 是**唯一需要 opacity 的特例**,因為它的 on/off 沒有任何形
 
 Slider 沒有獨立的 error 視覺——拖曳選值本身不太會「無效」。如果業務邏輯需要限制範圍,用 `min` / `max` 直接限制使用者能拖到的範圍,不要讓他拖到再報錯。
 
-### 無 readonly mode
+### Readonly(僅 Field cascade,無獨立 prop)
 
-Slider 的 `readonly` 等同於 `disabled`——一個不能操作的 slider 本質上就是 disabled。不同於 Input 有「可以 focus 但不能改」的 readonly 差異,slider 的 focus 除了拖曳沒有其他行為。若要顯示「歷史值」,用純文字或另一個 display 元件。
+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 元件。
 
 ---
 

package/src/components/Slider/slider.tsx

@@ -2,7 +2,7 @@ import * as React from 'react'
 import * as SliderPrimitive from '@radix-ui/react-slider'
 import { cva, type VariantProps } from 'class-variance-authority'
 import { cn } from '@/lib/utils'
-import { useFieldContext, useResolvedFieldDisabled } from '@/design-system/components/Field/field-context'
+import { useFieldContext, useResolvedFieldDisabled, useResolvedFieldMode } from '@/design-system/components/Field/field-context'
 
 /**
  * Slider — 數值範圍選取器
@@ -61,7 +61,10 @@ const Slider = React.forwardRef<
   // Field 家族整合:被 <Field mode="disabled"> 包裹時自動 disabled(per slider.spec.md「Slider 作為 Field
   // 家族整合時繼承其 canonical」)。Slider 已有完整 data-[disabled] 視覺,故只需把 fieldCtx disabled 接上。
   // 2026-06-08 SSOT:讀 useResolvedFieldDisabled()(fieldCtx.disabled)→ <Field disabled> 與 <Field mode="disabled"> 都生效
+  // 2026-06-12 補:<Field mode="readonly"> → 鎖互動保留視覺(readonly ≠ disabled,不降色)
   const fieldDisabled = useResolvedFieldDisabled()
+  const fieldMode = useResolvedFieldMode({ mode: undefined, disabled: undefined, readOnly: undefined })
+  const fieldReadonly = fieldMode === 'readonly'
   // 2026-06-10 a11y:Field 內 Slider thumb(role=slider)無 accessible name(deep-audit axe 抓 aria-input-field-name)
   // → 預設接 FieldLabel(aria-labelledby),consumer ariaLabel 優先。對齊 rating/time-picker labelId 接線。
   const fieldLabelId = useFieldContext()?.labelId
@@ -77,9 +80,12 @@ const Slider = React.forwardRef<
       ref={ref}
       value={value}
       defaultValue={defaultValue}
-      className={cn(sliderRootVariants({ size }), className)}
+      className={cn(sliderRootVariants({ size }), fieldReadonly && 'pointer-events-none', className)}
       {...props}
       disabled={(props as { disabled?: boolean }).disabled || fieldDisabled}
+      // <Field mode="readonly"> cascade(2026-06-12 補):鎖互動、保留正常視覺(readonly
+      // 不降色;值仍可讀)。pointer-events-none 擋滑鼠,thumb tabIndex=-1 擋鍵盤。
+      data-readonly={fieldReadonly || undefined}
     >
       {/*
         Track — rest 用 bg-secondary(n-3,「微淡可辨」),disabled 用 bg-muted(n-2,退化)。
@@ -115,27 +121,34 @@ const Slider = React.forwardRef<
           - Rest: `border-primary` ↔ Range `bg-primary`
           - Disabled: `border-border` ↔ Range `bg-border`
         這個一致性讓 thumb border 跟 range 融為一體,看起來像「range 包住 thumb」
-        的連續視覺。thumb 的白底則是「被 range 圍住的空心洞」,讓 thumb 的位置
-        清楚浮出。不論 state,thumb border 跟 range 永遠同色。
+        的連續視覺。不論 state,thumb border 跟 range 永遠同色。
 
-        **為什麼 thumb bg 不能改**:`bg-surface`(白)必須在 rest / disabled 都維持,
-        否則會融入 track 的 `bg-muted` 裡消失。這是之前踩過的同色融色 bug
-        (曾經寫成 `data-[disabled]:bg-muted` 讓 thumb 跟 track 完全融合)。
+        **Thumb bg 兩態(2026-06-12 user 拍板,深色模式破洞修正)**:
+          - Rest/hover/active:`bg-on-emphasis`(固定白、深淺主題不反轉)— 對齊自家
+            Switch thumb(switch.tsx bg-on-emphasis)+ Radix Themes(thumb 字面 white
+            無 dark override)+ Apple iOS(深色模式旋鈕仍白)。原 `bg-surface` 在深色
+            = 8% 白半透明 → thumb 變深色破洞且 track 穿透。
+          - Disabled:`bg-canvas`(不透明頁面背景色)— 沉回背景表達「不可動」,
+            = Radix disabled thumb 用 gray-1(app background)同款;不透明故 track
+            不穿透。不可用 bg-muted(曾踩 thumb 跟 track 同色融合 bug;canvas 與
+            track 的 muted 隔 n-5 邊框 + 不同值,不融)。
       */}
       {Array.from({ length: thumbCount }).map((_, i) => (
         <SliderPrimitive.Thumb
           key={i}
+          tabIndex={fieldReadonly ? -1 : undefined}
+          aria-readonly={fieldReadonly || undefined}
           className={cn(
             'block h-4 w-4 shrink-0 rounded-full cursor-grab',
-            'bg-surface border-2 border-primary',
+            'bg-on-emphasis border-2 border-primary',
             'transition-all duration-150',
             // Hover:border 加深到 primary-hover + elevation 陰影
             '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
             'outline-none focus-visible:border-primary-hover',
-            // Disabled:border 跟 Range 一起退成 border(n-5),bg 保留 bg-surface
-            'data-[disabled]:cursor-not-allowed data-[disabled]:border-border',
+            // Disabled:border 跟 Range 一起退成 border(n-5),bg 沉回 canvas(不透明背景色)
+            'data-[disabled]:cursor-not-allowed data-[disabled]:border-border data-[disabled]:bg-canvas',
             'data-[disabled]:hover:[box-shadow:none]',
           )}
           // aria-label 策略(對齊 WAI-ARIA APG multi-thumb slider + Radix 原生語意標籤):
@@ -174,7 +187,7 @@ export const sliderMeta = {
   },
   states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-muted', 'bg-primary', 'bg-secondary', 'bg-surface'],
+    bg: ['bg-muted', 'bg-primary', 'bg-secondary', 'bg-on-emphasis', 'bg-canvas'],
     fg: [],
     ring: [],
   },

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

@@ -45,7 +45,7 @@ export const Overview: Story = {
                 ['label', 'ReactNode', '—', 'inline label(Field context 內會被忽略)'],
                 ['description', 'ReactNode', '—', 'inline description(與 label 搭配)'],
                 ['disabled', 'boolean', 'false', '停用(opacity-disabled 保留顏色,見 spec)'],
-                ['readOnly', 'boolean', 'false', '鎖定互動但視覺正常(pointer-events-none + aria-readonly)'],
+                ['readOnly', 'boolean', 'false', 'standalone:鎖定互動視覺正常;Field 內:灰框 + ✓/—(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>
               ))}
@@ -87,7 +87,7 @@ export const Inspector: InspectorStory = {
     },
     defaultChecked: { control: 'boolean', description: '預設 ON / OFF' },
     disabled: { control: 'boolean', description: '停用(opacity-disabled 保留顏色)' },
-    readOnly: { control: 'boolean', description: '唯讀(視覺正常,互動鎖定)' },
+    readOnly: { control: 'boolean', description: '唯讀(standalone 視覺正常鎖互動;Field 內灰框 + ✓/—)' },
     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 視覺正常但互動鎖定。</Desc>
+        <Desc>disabled 用 opacity-disabled 保留顏色(Switch 特例,見下「Disabled 策略」)。readonly:standalone 視覺正常鎖互動;Field 內灰框 + ✓/—。</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>
@@ -144,7 +144,7 @@ export const StateBehavior: Story = {
               <tr><Td>ON</Td><Td><TokenCell token="--primary" display="bg-primary" /></Td><Td><span className="inline-flex items-center gap-1.5"><Swatch value="--primary" size="sm" /><span className="font-mono">白色 + 2px primary border</span></span></Td><Td><TokenCell token="--primary" display="primary check" /></Td></tr>
               <tr><Td>Disabled OFF</Td><Td>opacity-disabled 套於整體</Td><Td>同 OFF(顏色保留)</Td><Td>—</Td></tr>
               <tr><Td>Disabled ON</Td><Td>opacity-disabled 套於整體</Td><Td>同 ON(顏色保留)</Td><Td>同 ON</Td></tr>
-              <tr><Td>Readonly</Td><Td>正常顏色</Td><Td>正常視覺</Td><Td>視 on/off</Td></tr>
+              <tr><Td>Readonly(standalone)</Td><Td>正常顏色</Td><Td>正常視覺</Td><Td>視 on/off</Td></tr>
             </tbody>
           </table>
         </div>

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

@@ -99,7 +99,7 @@ export const UsageGuidance: Story = {
       {/* vs 近親 — ReadonlyVsDisabledRule — 原 ReadonlyVsDisabledRule */}
       <div>
       <Rule
-        title="Readonly 保留正常顏色(可讀)/ Disabled 降透明度(弱化)"
+        title="Readonly(standalone)保留正常顏色(可讀)/ Disabled 降透明度(弱化)"
         note="兩者都鎖定互動,但視覺訊號不同:readonly 告訴使用者「這個值就是這樣,你看得清」;disabled 告訴使用者「這個 field 目前不可用」(弱化暗示低優先)"
       >
         <div className="grid grid-cols-2 gap-4">
@@ -116,9 +116,9 @@ export const UsageGuidance: Story = {
 
       <Rule
         title="使用場景對照"
-        note="Readonly:表單 readonly 呈現、DataTable cell 非編輯態——值重要、視覺不能弱化。Disabled:外部條件造成暫時不可用(方案限制、權限不足)——傳達「現在用不到」"
+        note="Readonly(standalone settings list):值重要、視覺不能弱化。表單 readonly = Field 內灰框 + ✓/—(2026-06-12 拍板);DataTable cell 非編輯態 = mode display。Disabled:外部條件造成暫時不可用(方案限制、權限不足)——傳達「現在用不到」"
       >
-        <Label>兩者都不可切換、不在 tab order 內,但機制不同:readonly 用 `pointer-events-none`(視覺正常);disabled 走 native `disabled` + `cursor-not-allowed`(降透明度)</Label>
+        <Label>兩者都不可切換、不在 tab order 內(standalone),機制不同:readonly 用 `pointer-events-none`(視覺正常);disabled 走 native `disabled` + `cursor-not-allowed`(降透明度)。Field 內 readonly 灰框則可聚焦(tabIndex=0)</Label>
       </Rule>
     </div>
     </div>

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

@@ -102,7 +102,8 @@ 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 | 視覺同一般態 | 但 `pointer-events-none` + `aria-readonly` | — |
+| Readonly(standalone)| 視覺同一般態 | 但 `pointer-events-none` + `aria-readonly` | — |
+| Readonly(Field 內,2026-06-12 user 拍板)| 不渲染 toggle — 改渲染 `fieldWrapperStyles` readonly 灰框(= Input readonly 同源)+ ✓/—(display 同款值語言) | role="switch" + aria-checked + aria-readonly + 可 focus | — |
 
 ### Disabled 用 `opacity`
 
@@ -117,22 +118,25 @@ sm 和 md 視覺相同（純粹命名 mapping，讓消費者可直接傳同一
 
 詳細對照見 `../Slider/slider.spec.md`「Disabled 策略」節。
 
-### Readonly vs Disabled
+### Readonly vs Disabled(standalone;Field 內 readonly = 灰框 + ✓/—,見上方狀態表)
 
-| | Readonly | Disabled |
+| | Readonly(standalone) | Disabled |
 |---|---|---|
 | 視覺 | 正常顏色（可讀） | 降透明度（弱化） |
 | 互動 | 不可切換（pointer-events-none） | 不可切換（cursor-not-allowed） |
 | aria | `aria-readonly` | `disabled` |
 | Tab 焦點 | 不在 tab order | 不在 tab order |
-| 用途 | 表單 readonly 呈現、DataTable cell 非編輯態 | 外部條件造成不可操作 |
+| 用途 | settings list 鎖定呈現 | 外部條件造成不可操作 |
+
+表單 readonly 呈現 = Field 內灰框 + ✓/—(2026-06-12 拍板);DataTable cell 非編輯態 = `mode="display"`(✓/—),皆非本表 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` / `disabled` — 同上表「Readonly vs Disabled」(readonly=正常色鎖互動 / disabled=opacity 弱化)。
+- `readonly` — **Field 內** = 灰框 + ✓/—(消費 `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)。
 
 ---
 
@@ -177,7 +181,7 @@ Switch 可透過 `label` / `description` props 內部直接渲染緊鄰文字：
 
 ## 邊界案例
 
-- **Readonly 的滑鼠 / 鍵盤**：`pointer-events-none` 使點擊無反應；`tabIndex=-1` 不入 tab order，故無鍵盤互動（視覺正常、僅鎖互動）
+- **Readonly 的滑鼠 / 鍵盤**(standalone)：`pointer-events-none` 使點擊無反應；`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

@@ -5,7 +5,8 @@ import { Check } from 'lucide-react'
 import { cva, type VariantProps } from 'class-variance-authority'
 import { cn } from '@/lib/utils'
 import type { FieldMode, FieldVariant } from '@/design-system/components/Field/field-types'
-import { useFieldContext, useResolvedFieldDisabled, useResolvedFieldMode } from '@/design-system/components/Field/field-context'
+import { useFieldContext, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldSize } from '@/design-system/components/Field/field-context'
+import { fieldWrapperStyles } from '@/design-system/components/Field/field-wrapper'
 
 /**
  * Switch — 開關控件
@@ -22,7 +23,8 @@ import { useFieldContext, useResolvedFieldDisabled, useResolvedFieldMode } from
  *   OFF: track border (neutral-5), thumb 白色 + 2px border-border(neutral-5,與 OFF track 同色)無 check
  *   ON:  track primary, thumb 白色 + 2px primary border + primary check icon
  *   disabled: opacity-disabled（整體透明度）
- *   readOnly: 視覺同一般態，但 pointer-events-none + aria-readonly
+ *   readOnly(standalone): 視覺同一般態，但 pointer-events-none + aria-readonly
+ *   readOnly(Field 內): 渲染 readonly 灰框 + ✓/—(2026-06-12 拍板,= Input readonly 同視覺語言)
  *
  * ── label / description / readOnly ──
  * Switch 可以透過 `label` 和 `description` props 在元件內直接渲染緊鄰的文字，
@@ -42,7 +44,8 @@ import { useFieldContext, useResolvedFieldDisabled, useResolvedFieldMode } from
  *
  * readOnly 模式：
  *   <Switch readOnly checked={true} label="..." />
- *   視覺維持 ON/OFF 正確狀態，但無法互動、不在 tab order 內、寫入 aria-readonly。
+ *   standalone:視覺維持 ON/OFF 正確狀態,但無法互動、不在 tab order 內、寫入 aria-readonly。
+ *   Field 內:渲染 readonly 灰框 + ✓/—(不渲染 toggle;見 forwardRef 內 readonly 分支)。
  *   與 disabled 的差異：readonly 不降色（可讀），disabled 降色（弱化）。
  */
 
@@ -98,9 +101,9 @@ export interface SwitchProps
    */
   description?: React.ReactNode
   /**
-   * readonly 模式：鎖定互動但維持 ON/OFF 視覺正確。
-   * 與 disabled 的差異：readonly 不降色（可讀），disabled 降色（弱化）。
-   * 用於表單 readonly 呈現、DataTable cell 非編輯態。
+   * readonly 模式:standalone = 鎖定互動但維持 ON/OFF 視覺;Field 內 = 灰框 + ✓/—。
+   * 與 disabled 的差異:readonly 不降色(可讀),disabled 降色(弱化)。
+   * DataTable cell 非編輯態用 mode="display"(✓/—),非 readOnly。
    */
   readOnly?: boolean
   /**
@@ -108,8 +111,8 @@ export interface SwitchProps
    *   edit     — 一般可互動 Switch(預設)
    *   display  — **純展示**:渲染 ✓ / —(無互動 primitive、無 input chrome);
    *              對齊 Carbon read-only / DataTable boolean cell。
-   *              `readonly` 保留 toggle 視覺 + 鎖互動;`display` 完全無 toggle 形體 — 兩者語意分離(field-types.ts)。
-   *   readonly — 同 readOnly prop
+   *              `display` 完全無 toggle 形體;`readonly` 視場景(field-types.ts)。
+   *   readonly — standalone 同 readOnly prop(保留視覺鎖互動);Field 內 = 灰框 + ✓/—
    *   disabled — 同 disabled prop
    */
   mode?: FieldMode
@@ -151,6 +154,10 @@ const Switch = React.forwardRef<
     const disabled = useResolvedFieldDisabled(disabledProp)
     const resolvedMode = useResolvedFieldMode({ mode, disabled, readOnly })
     const effectiveReadOnly = readOnly || resolvedMode === 'readonly'
+    // mode='disabled' 直傳(無 Field ctx 的 cell 場景)必須落到真 disabled chrome(同 Checkbox 2026-06-12 修)
+    const effectiveDisabled = disabled || resolvedMode === 'disabled'
+    // readonly 灰框 size:走 SSOT resolver(prop > ctx > 'md',field-context.ts:150-161)
+    const resolvedBoxSize = useResolvedFieldSize(size ?? undefined, 'md') as 'sm' | 'md' | 'lg'
     const insideField = fieldCtx?.hasFieldWrapper === true
     const effectiveLabel = insideField ? undefined : label
     const effectiveDescription = insideField ? undefined : description
@@ -176,12 +183,38 @@ const Switch = React.forwardRef<
         : <span 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 boxSize = resolvedBoxSize
+      return (
+        <div
+          role="switch"
+          aria-checked={isChecked}
+          aria-readonly="true"
+          aria-labelledby={fieldCtx?.labelId}
+          aria-invalid={fieldCtx?.invalid || undefined}
+          data-readonly="true"
+          tabIndex={0}
+          className={cn(
+            fieldWrapperStyles({ size: boxSize, mode: 'readonly', variant: 'default' }),
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+            className,
+          )}
+        >
+          {isChecked ? <span className="text-foreground">✓</span> : <span className="text-fg-muted">—</span>}
+        </div>
+      )
+    }
+
     const rootEl = (
       <SwitchPrimitives.Root
         id={inputId}
         className={cn(switchVariants({ size }), alignRightInField, className)}
         ref={ref}
-        disabled={disabled}
+        disabled={effectiveDisabled}
         aria-readonly={effectiveReadOnly || undefined}
         data-readonly={effectiveReadOnly || undefined}
         tabIndex={effectiveReadOnly ? -1 : undefined}
@@ -220,7 +253,7 @@ const Switch = React.forwardRef<
         htmlFor={inputId}
         className={cn(
           'inline-flex items-start gap-3 select-none',
-          disabled ? 'cursor-not-allowed' : readOnly ? 'cursor-default' : 'cursor-pointer'
+          effectiveDisabled ? 'cursor-not-allowed' : readOnly ? 'cursor-default' : 'cursor-pointer'
         )}
       >
         {/* Label↔desc gap typography-mode-aware:
@@ -237,7 +270,7 @@ const Switch = React.forwardRef<
             className={cn(
               // Reading mode 字級:lg → text-body-lg (16px),sm/md → text-body (14px)
               sizeKey === 'lg' ? 'text-body-lg' : 'text-body',
-              disabled ? 'text-fg-disabled' : 'text-foreground'
+              effectiveDisabled ? 'text-fg-disabled' : 'text-foreground'
             )}
           >
             {effectiveLabel}
@@ -245,7 +278,7 @@ const Switch = React.forwardRef<
           {effectiveDescription != null && (
             <span
               className={cn(
-                disabled ? 'text-fg-disabled' : 'text-fg-secondary'
+                effectiveDisabled ? 'text-fg-disabled' : 'text-fg-secondary'
               )}
               // Reading mode description:**最小 14px**(spec 14→14px, 16→14px),lh 預設 1.5。
               // 用 inline style 直接繞過 tailwind-merge 對 text-body / text-fg-* 的潛在衝突。

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

@@ -166,13 +166,13 @@ export const Inspector: Story = {
               </>
             )}
           </TabsList>
-          <TabsContent value="overview" className="mt-4 text-body text-fg-secondary">
+          <TabsContent value="overview" className=" text-body text-fg-secondary">
             專案的總覽資訊(KPI / 最近活動 / 團隊成員簡介)
           </TabsContent>
-          <TabsContent value="members" className="mt-4 text-body text-fg-secondary">
+          <TabsContent value="members" className=" text-body text-fg-secondary">
             專案成員列表(3 人待邀請)
           </TabsContent>
-          <TabsContent value="settings" className="mt-4 text-body text-fg-secondary">
+          <TabsContent value="settings" className=" text-body text-fg-secondary">
             專案設定(12 個通知待閱讀)
           </TabsContent>
         </Tabs>

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

@@ -120,7 +120,7 @@ export const UsageGuidance: Story = {
                 <TabsTrigger value="products">產品</TabsTrigger>
                 <TabsTrigger value="settings" startIcon={Settings}>設定</TabsTrigger>
               </TabsList>
-              <TabsContent value="orders" className="mt-4 text-body text-fg-muted">(訂單頁的 toolbar、filters、table…)</TabsContent>
+              <TabsContent value="orders" className="text-body text-fg-muted">(訂單頁的 toolbar、filters、table…)</TabsContent>
             </Tabs>
           </div>
           <div>

package/src/components/Tabs/tabs.spec.md

@@ -181,6 +181,10 @@ Tabs 是 **navigation anchor**，不是 compact control：
 
 **Triggers 之間 gap**：使用 `--layout-space-loose`（md density 16px / lg density 24px），與其他「pattern 層級的鬆散留白」共用同一 token。Tabs 的 gap 不是裝飾性空白，而是告訴使用者「每個 tab 是獨立的視圖入口」的視覺分隔。
 
+**TabsList 容器寬度(2026-06-12 user 拍板,解 L58 spec≠code)**:**跨滿父容器**(none 模式 `w-full`;scroll/menu 模式 inner list `min-w-full` 保留溢出成長)——底線連成整條、右端達內容區邊緣,與「跨父容器寬度、與 header border 對齊」的角色定義一致(對齊 Ant nav `left:0;right:0` 底線 / Primer UnderlineNav;shadcn 為 pill 式不同型不適用)。Trigger 本身仍 hug content(上段不變)。**左右邊距 ownership**:TabsList **不自加水平 padding**——邊距由容器的 `--layout-space-loose` gutter 提供(standalone = 父容器 padding;withTabs = 繼承 header padding,W2 lockstep),故 tab 左緣永遠對齊兄弟內容左緣。
+
+**TabsContent 與 TabsList 間距(2026-06-12 user 拍板)**:`--layout-space-tight`(md 12px,density 連動),**內建於 TabsContent**(`mt-[var(--layout-space-tight)]`,className 可覆寫;full-height 佈局用 `mt-0`)。依 `layoutSpace.spec`「親疏 3 級」第一級(同 bundle,元件 spec own)+ 規則 3「直接功能依賴 = tight」精神;**不**取 Ant 的固定 16px(M23 自家 token 優先)。內容本身的排版歸 item-anatomy / 各內容元件管,本條只管 list↔content gap。
+
 ---
 
 ## Underline 與 TabsList border 的視覺關係

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

@@ -32,10 +32,10 @@ export const Default: Story = {
         <TabsTrigger value="notifications" badge={<Badge count={3} />}>通知</TabsTrigger>
         <TabsTrigger value="settings">設定</TabsTrigger>
       </TabsList>
-      <TabsContent value="overview" className="p-4 text-body text-fg-secondary">專案的總覽資訊（KPI、最近活動、團隊成員簡介）</TabsContent>
-      <TabsContent value="members" className="p-4 text-body text-fg-secondary">專案成員列表（3 人待邀請）</TabsContent>
-      <TabsContent value="notifications" className="p-4 text-body text-fg-secondary">3 則未讀通知（提及、指派、留言回覆）</TabsContent>
-      <TabsContent value="settings" className="p-4 text-body text-fg-secondary">專案設定（一般、權限、整合）</TabsContent>
+      <TabsContent value="overview" className="text-body text-fg-secondary">專案的總覽資訊（KPI、最近活動、團隊成員簡介）</TabsContent>
+      <TabsContent value="members" className="text-body text-fg-secondary">專案成員列表（3 人待邀請）</TabsContent>
+      <TabsContent value="notifications" className="text-body text-fg-secondary">3 則未讀通知（提及、指派、留言回覆）</TabsContent>
+      <TabsContent value="settings" className="text-body text-fg-secondary">專案設定（一般、權限、整合）</TabsContent>
     </Tabs>
   ),
 }