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

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

@@ -0,0 +1,227 @@
+// @anatomy-exempt: anatomy specs / token 對照表格用 raw <table>,非業務資料表。業務資料表才用 <DataTable>。
+// @anatomy-rationale:
+//   ColorMatrix represented as StateBehavior「視覺狀態對照」段 — Switch 不分
+//     variant 色彩(全 DS 統一 track bg-border / bg-primary,thumb 白色),色彩
+//     僅由 state 驅動(OFF / ON / Disabled OFF / Disabled ON / Readonly)。
+//     色彩 token 矩陣已由 StateBehavior(5.)「Track / Thumb / Check icon」三欄
+//     對照涵蓋,獨立 ColorMatrix 會與 StateBehavior 重複。
+import type { Meta, StoryObj } from '@storybook/react'
+import { Switch, type SwitchProps } from './switch'
+import { H3, Desc, Td, Th, Swatch, TokenCell } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+const meta: Meta = {
+  title: 'Design System/Components/Switch/設計規格',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+type InspectorStory = StoryObj<SwitchProps>
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>Anatomy</H3>
+        <Desc>Track(pill 形容器)+ Thumb(白色圓 + 2px border + check icon when ON)。基於 Radix Switch,shadcn 包裝 + 橋接 DS token。</Desc>
+        <div className="flex items-center gap-6 border border-border rounded-lg p-6">
+          <Switch aria-label="關閉狀態 Switch" />
+          <Switch defaultChecked aria-label="開啟狀態 Switch" />
+          <span className="text-caption text-fg-muted font-mono">OFF → ON 切換 track bg-border → bg-primary,thumb 白色 + 2px border 視覺延續</span>
+        </div>
+      </div>
+
+      <div>
+        <H3>Props 速查</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
+            <tbody>
+              {[
+                ['mode', "'edit' | 'view' | 'readonly' | 'disabled'", "'edit'", 'Field mode(默認 inherit Field context 或 edit);view 渲純展示 勾/叉 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 內:灰框 + 勾/叉 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>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const Inspector: InspectorStory = {
+  name: '元件檢閱器',
+  parameters: {
+    docs: {
+      description: {
+        story: '在右側 Controls 面板切換 size / checked / disabled / readOnly / label 組合,即時查看 Switch 狀態。世界級 DS 的 Inspector = Figma inspect 替代。',
+      },
+    },
+  },
+  args: {
+    size: 'md',
+    defaultChecked: true,
+    disabled: false,
+    readOnly: false,
+    label: '啟用通知',
+    description: '收到新訊息時立即提醒',
+  },
+  argTypes: {
+    mode: {
+      control: 'radio',
+      options: ['edit', 'view', 'readonly', 'disabled'],
+      description: 'Field mode;view 渲純展示 勾/叉 icon(語意由 context 提供)',
+    },
+    size: {
+      control: 'radio',
+      options: ['sm', 'md', 'lg'],
+      description: '尺寸(sm = md 視覺同,lg track 24×48)',
+    },
+    defaultChecked: { control: 'boolean', description: '預設 ON / OFF' },
+    disabled: { control: 'boolean', description: '停用(opacity-disabled 保留顏色)' },
+    readOnly: { control: 'boolean', description: '唯讀(standalone 視覺正常鎖互動;Field 內灰框 + 勾/叉 icon)' },
+    label: { control: 'text', description: 'inline label(留空 → 只渲染 switch 本體)' },
+    description: { control: 'text', description: 'inline description(需搭配 label)' },
+  },
+  render: (args) => <Switch {...args} />,
+}
+
+export const SizeMatrix: Story = {
+  name: '尺寸對照表',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>三種 Size — 對齊 field / button tier</H3>
+        <Desc>sm 和 md 視覺完全相同(命名 mapping,讓 consumer 直接傳同一個 size)。lg 是 24×48(track 寬 = 2 × 高,pill 比例固定)。</Desc>
+        <div className="overflow-x-auto mb-4">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Size</Th><Th>Track</Th><Th>Thumb 直徑</Th><Th>白色圓</Th><Th>Check icon</Th><Th>配對 field</Th></tr></thead>
+            <tbody>
+              <tr><Td mono>sm / md ★default</Td><Td mono>20 × 40</Td><Td mono>20</Td><Td mono>16</Td><Td mono>12</Td><Td>field-sm / md</Td></tr>
+              <tr><Td mono>lg</Td><Td mono>24 × 48</Td><Td mono>24</Td><Td mono>20</Td><Td mono>16</Td><Td>field-lg</Td></tr>
+            </tbody>
+          </table>
+        </div>
+        <div className="flex items-center gap-8 border border-border rounded-lg p-4">
+          <div className="flex flex-col items-center gap-2">
+            <Switch size="sm" defaultChecked aria-label="sm 尺寸開啟狀態 Switch" />
+            <span className="text-caption text-fg-muted font-mono">sm</span>
+          </div>
+          <div className="flex flex-col items-center gap-2">
+            <Switch size="md" defaultChecked aria-label="md 尺寸開啟狀態 Switch" />
+            <span className="text-caption text-fg-muted font-mono">md</span>
+          </div>
+          <div className="flex flex-col items-center gap-2">
+            <Switch size="lg" defaultChecked aria-label="lg 尺寸開啟狀態 Switch" />
+            <span className="text-caption text-fg-muted font-mono">lg</span>
+          </div>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const StateBehavior: Story = {
+  name: '狀態行為',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>視覺狀態對照</H3>
+        <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>
+            <tbody>
+              <tr><Td>OFF</Td><Td><TokenCell token="--border" display="bg-border(neutral-5)" /></Td><Td><span className="inline-flex items-center gap-1.5"><Swatch value="--border" size="sm" /><span className="font-mono">白色 + 2px border-border</span></span></Td><Td>—</Td></tr>
+              <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(standalone)</Td><Td>正常顏色</Td><Td>正常視覺</Td><Td>視 on/off</Td></tr>
+            </tbody>
+          </table>
+        </div>
+        <div className="grid grid-cols-2 gap-4 max-w-2xl">
+          <div className="border border-dashed border-divider rounded-md p-3">
+            <div className="text-caption text-fg-muted mb-2">OFF</div>
+            <Switch aria-label="可用的關閉狀態 Switch" />
+          </div>
+          <div className="border border-dashed border-divider rounded-md p-3">
+            <div className="text-caption text-fg-muted mb-2">ON</div>
+            <Switch defaultChecked aria-label="可用的開啟狀態 Switch" />
+          </div>
+          <div className="border border-dashed border-divider rounded-md p-3">
+            <div className="text-caption text-fg-muted mb-2">Disabled OFF</div>
+            <Switch disabled aria-label="停用的關閉狀態 Switch" />
+          </div>
+          <div className="border border-dashed border-divider rounded-md p-3">
+            <div className="text-caption text-fg-muted mb-2">Disabled ON</div>
+            <Switch disabled defaultChecked aria-label="停用的開啟狀態 Switch" />
+          </div>
+          <div className="border border-dashed border-divider rounded-md p-3">
+            <div className="text-caption text-fg-muted mb-2">Readonly ON</div>
+            <Switch readOnly defaultChecked aria-label="唯讀的開啟狀態 Switch" />
+          </div>
+          <div className="border border-dashed border-divider rounded-md p-3">
+            <div className="text-caption text-fg-muted mb-2">Readonly OFF</div>
+            <Switch readOnly aria-label="唯讀的關閉狀態 Switch" />
+          </div>
+        </div>
+      </div>
+
+      <div>
+        <H3>Disabled 策略:opacity 而非灰階 swap</H3>
+        <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>
+  ),
+}
+
+export const LabelIntegration: Story = {
+  name: '標籤 / 說明 整合',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>Inline label / description</H3>
+        <Desc>Switch 可透過 `label` / `description` props 內部直接渲染緊鄰文字,不需 consumer 組合。</Desc>
+        <div className="flex flex-col gap-4 max-w-md border border-dashed border-divider rounded-md p-4">
+          <Switch label="啟用 Bluetooth" defaultChecked />
+          <Switch
+            label="啟用通知"
+            description="收到新訊息時提醒"
+            defaultChecked
+          />
+          <Switch
+            label="Dark mode"
+            description="跟隨系統主題"
+          />
+        </div>
+      </div>
+
+      <div>
+        <H3>在 Field context 內</H3>
+        <Desc>Switch 在 `&lt;Field&gt;` context 內時 label / description prop 會被自動忽略(由 FieldLabel / FieldDescription 接管),避免雙層 label。</Desc>
+      </div>
+    </div>
+  ),
+}
+
+// ── Accessibility ─────────────────────────────────────────────────────────
+// 2026-05-17 ship per audit Dim 13(story-rules.md 6-canonical 含 Accessibility)
+export const Accessibility = {
+  name: '無障礙與鍵盤',
+  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">{"無障礙設計摘要:\n\n  ARIA  :Switch 本體是一顆原生切換按鈕(role=\"switch\" + aria-checked),角色與狀態都由瀏覽器和 Radix 自動提供。可參考 [Radix 無障礙說明](https://www.radix-ui.com/primitives/docs/components/switch#accessibility)。\n\n  鍵盤操作  :\n\n- Tab — 把焦點移到開關上\n- Space / Enter — 切換開 / 關\n\n  焦點外觀  :開關本身就能被 Tab 聚焦(它是一顆按鈕);聚焦時會顯示一圈藍色 focus ring(由設計系統的 focus-visible 樣式提供,2px ring 用 --ring 色)。它是單一控件,沒有「焦點鎖定 / 還原」這種彈窗才有的行為。\n\n  驗證  :Storybook a11y 面板應為 0 critical violation;只用鍵盤即可完整操作(不需滑鼠)。文字對比 WCAG AA ≥ 4.5:1、UI 元素 ≥ 3:1。"}</p>
+    </div>
+  ),
+}

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

@@ -0,0 +1,177 @@
+// @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.
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Switch } from './switch'
+import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
+import { Button } from '@/design-system/components/Button/button'
+
+const meta: Meta = {
+  title: 'Design System/Components/Switch/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+const Rule = ({
+  title, note, children,
+}: {
+  title: string; note?: string; children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-muted mb-5 max-w-[720px] leading-relaxed">{note}</p>}
+    <div className="flex flex-col gap-3 max-w-md">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+// ── WhenToUse — 何時使用 Switch ──────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / VsCheckboxRule / ReadonlyVsDisabledRule(2026-04-26 v3 canonical)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => {
+    const [bluetooth, setBluetooth] = React.useState(true)
+    const [agreeTerms, setAgreeTerms] = React.useState(false)
+    return (
+    <div className="flex flex-col gap-12">
+      {/* 何時用 — 原 WhenToUse */}
+      <div className="prose prose-sm max-w-prose">
+      <p>適合 Switch 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/Switch/展示" name="搭配標籤"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">搭配標籤</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">判斷不確定時,問自己:這是切換即生效的獨立開關,還是表單裡要按送出才成立的勾選?前者用 Switch,後者用 Checkbox。下面幾段有完整對照。</p>
+    </div>
+
+      {/* vs 近親元件 — 原 VsCheckboxRule */}
+      <div>
+        <Rule
+          title="vs 近親元件 — Switch 最適合即時生效的布林開關"
+          note="切換即生效——物理開關類比(牆上 light switch、iPhone settings)。使用者按下那刻 Bluetooth 就開了,不經任何 submit 流程"
+        >
+          <div className="border border-border rounded-lg p-4 space-y-3">
+            <div className="flex items-center justify-between">
+              <div>
+                <div className="text-body font-medium">Bluetooth</div>
+                <div className="text-caption text-fg-muted">切換立刻開 / 關</div>
+              </div>
+              <Switch
+                checked={bluetooth}
+                onCheckedChange={setBluetooth}
+                aria-label="Bluetooth"
+              />
+            </div>
+          </div>
+          <Label>↑ 獨立 inline control,無 submit / cancel 流程</Label>
+        </Rule>
+
+        <Rule
+          title="何時不用 / 替代元件 — Form 內的同意 / 勾選用 Checkbox"
+          note="「我同意服務條款」是「勾選 → 送出 → 法律成立」的書面行為。Switch 的物理開關隱喻暗示「我打開了接受條款這個功能」——心智錯位且違反約定俗成(全球沒有 form 用 Switch 同意條款)"
+        >
+          <div className="border border-border rounded-lg p-4 space-y-3">
+            <Checkbox
+              label="我同意服務條款與隱私政策"
+              checked={agreeTerms}
+              onCheckedChange={(v) => setAgreeTerms(v === true)}
+            />
+            <div className="flex gap-2 pt-2">
+              <Button variant="primary">送出</Button>
+              <Button variant="tertiary">取消</Button>
+            </div>
+          </div>
+          <Label>↑ Form 內同意條款用 Checkbox,隨 submit 才成立</Label>
+        </Rule>
+
+        <Rule
+          title="vs 近親元件 — 判斷法:「旁邊有 submit / cancel button 嗎?」"
+          note="有 → Checkbox(form 流程、值隨 submit 送出);沒有,是獨立 inline control → Switch(切換即生效)"
+        >
+          <Label>三個判斷角度(套用時機、心智模型、是否可反悔)的完整對照,以 Checkbox 為主要說明對象</Label>
+        </Rule>
+      </div>
+
+      {/* vs 近親 — ReadonlyVsDisabledRule — 原 ReadonlyVsDisabledRule */}
+      <div>
+      <Rule
+        title="Readonly(standalone)保留正常顏色(可讀)/ Disabled 降透明度(弱化)"
+        note="兩者都鎖定互動,但視覺訊號不同:readonly 告訴使用者「這個值就是這樣,你看得清」;disabled 告訴使用者「這個 field 目前不可用」(弱化暗示低優先)"
+      >
+        <div className="grid grid-cols-2 gap-4">
+          <div className="border border-dashed border-divider rounded-md p-3">
+            <div className="text-caption text-fg-muted mb-2">Readonly ON(顏色正常)</div>
+            <Switch readOnly defaultChecked aria-label="唯讀的開啟狀態設定" />
+          </div>
+          <div className="border border-dashed border-divider rounded-md p-3">
+            <div className="text-caption text-fg-muted mb-2">Disabled ON(opacity 降低)</div>
+            <Switch disabled defaultChecked aria-label="停用的開啟狀態設定" />
+          </div>
+        </div>
+      </Rule>
+
+      <Rule
+        title="使用場景對照"
+        note="Readonly（獨立設定列表）的值仍很重要，視覺不能弱化；表單內的 readonly 由 Field 以灰框與狀態圖示呈現，DataTable 非編輯態則使用檢視模式。Disabled 表示因方案或權限等外部條件而暫時不可用"
+      >
+        <Label>兩者都不可切換、不在 tab order 內(standalone),機制不同:readonly 用 `pointer-events-none`(視覺正常);disabled 走 native `disabled` + `cursor-not-allowed`(降透明度)。Field 內 readonly 灰框則可聚焦(tabIndex=0)</Label>
+      </Rule>
+    </div>
+    </div>
+    )
+  },
+}
+
+export const DisabledOpacityRule: Story = {
+  name: '停用用半透明保留顏色',
+  render: () => (
+    <div>
+      <Rule
+        title="Switch disabled 用 opacity,不用灰階 swap"
+        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">
+            <div className="text-caption text-fg-muted mb-2">Rest ON</div>
+            <Switch defaultChecked aria-label="可用的開啟狀態 Switch" />
+          </div>
+          <div className="border border-dashed border-divider rounded-md p-3">
+            <div className="text-caption text-fg-muted mb-2">Rest OFF</div>
+            <Switch aria-label="可用的關閉狀態 Switch" />
+          </div>
+          <div className="border border-dashed border-divider rounded-md p-3">
+            <div className="text-caption text-fg-muted mb-2">Disabled ON(opacity 保留顏色)</div>
+            <Switch defaultChecked disabled aria-label="停用的開啟狀態 Switch" />
+          </div>
+          <div className="border border-dashed border-divider rounded-md p-3">
+            <div className="text-caption text-fg-muted mb-2">Disabled OFF</div>
+            <Switch disabled aria-label="停用的關閉狀態 Switch" />
+          </div>
+        </div>
+        <Label>↑ Disabled 仍能分辨 ON(藍)vs OFF(灰)——opacity 降低但顏色身份保留</Label>
+      </Rule>
+
+      <Rule
+        title="對照 Slider / Checkbox:灰階 swap(位置/形狀承載 state)"
+        note="Slider 的 state 是 thumb 位置 + range 長度——灰色 thumb 在灰色 track 上,位置資訊跟 primary 版本完全一樣。Checkbox 的 state 是 checkmark 形狀——灰色框裡的 check 仍清楚可辨。這兩個用灰階 swap 不失 state 資訊"
+      >
+        <Label>判準:「什麼視覺載體承載 state?」位置/形狀 → 灰階 swap;純顏色 → opacity(Switch 特例)</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 若 Switch 改用灰階 swap"
+        note="disabled ON 和 disabled OFF 都會退成「灰 track + 灰 thumb」——殘餘線索只剩 thumb 位置與 thumb 內小 check icon,在灰階低對比下辨識度大幅下降,使用者難以一眼判斷被停用的開關當前是開還是關"
+      >
+        <Label warn>設計上禁止——Switch 的 on/off 最強視覺載體是顏色(thumb 位置 / check icon 只是輔助線索),disabled 必須保留顏色</Label>
+      </Rule>
+    </div>
+  ),
+}

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

@@ -1,6 +1,6 @@
 ---
 component: Switch
-family: 4
+family: self-contained
 variants: {}
 sizes:
   sm:
@@ -20,8 +20,6 @@ benchmark:
   - Ant Design Switch: github.com/ant-design/ant-design/tree/master/components/switch
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
-
 # Switch 設計原則
 
 ## 定位
@@ -75,6 +73,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 同款);OFF track `bg-border → bg-border-hover` 深一階(Checkbox 未選 hover 同慣例)
 
 ---
 
@@ -90,8 +89,7 @@ sm 和 md 視覺相同（純粹命名 mapping，讓消費者可直接傳同一
 ### 為什麼不完全對齊 `--field-height-*`
 
 - **現況**:track 高 sm/md=20px / lg=24px(不等於 `--field-height-sm/md/lg` = 28/32/36px);track 寬固定 2× 高(pill 比例);thumb 直徑 = track 高
-- **Rationale**:Switch 是**實體開關類比**(iOS / macOS 系統開關),track 是 pill 形不是 field-like 容器;高度**小於 field-height** 才符合「嵌在一列中的小控件」的語意。放大到 field-height(28/32/36)會破壞 pill 比例(canonical 2:1),視覺語意從 toggle 降級為 generic action button,且失去「可滑動凹槽」的空間 affordance。行高對齊透過 `<Field>` 容器的 `flex items-center` 垂直置中達成 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-- **世界級對照**:iOS `UISwitch` = 32×20pt(獨立 pill 比例,不跟 form field 成比例)/ Material 3 Switch = 52×32dp / GitHub Primer ToggleSwitch = 40×24——全部 pill 比例 2:1、獨立於 field-height <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- **Rationale**:Switch 是**實體開關類比**,track 是 pill 形而不是 field-like 容器;高度**小於 field-height** 才符合「嵌在一列中的小控件」的語意。放大到 field-height(28/32/36)會破壞 canonical 2:1 pill 比例,讓 toggle 看似 generic action button,並削弱可滑動凹槽的 affordance。行高對齊由 `<Field>` 容器的 `flex items-center` 垂直置中達成
 
 ---
 
@@ -99,33 +97,52 @@ sm 和 md 視覺相同（純粹命名 mapping，讓消費者可直接傳同一
 
 | 狀態 | Track | Thumb | Check icon |
 |------|-------|-------|-----------|
-| OFF | `bg-border`（neutral-5） | 白色無 border | 無 |
+| 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` + click guard + `aria-readonly` | — |
+| Readonly(Field 內,2026-06-12 user 拍板)| 不渲染 toggle — 改渲染 `fieldWrapperStyles` readonly 灰框(= Input readonly 同源)+ 勾/叉 icon(view 同款值語言) | 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
+### Readonly vs Disabled(standalone;Field 內 readonly = 灰框 + 勾/叉 icon,見上方狀態表)
 
-| | Readonly | Disabled |
+| | 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 |
-| 用途 | 表單 readonly 呈現、DataTable cell 非編輯態 | 外部條件造成不可操作 |
+| 用途 | settings list 鎖定呈現 | 外部條件造成不可操作 |
+
+表單 readonly 呈現 = Field 內灰框 + 勾/叉 icon(2026-06-12 拍板);DataTable cell 非編輯態 = `mode="view"`(勾/叉 icon),皆非本表 standalone readonly。
+
+### `mode` prop(Field mode,正交於 size)
+
+`mode?: 'edit' | 'view' | 'readonly' | 'disabled'`(默認 inherit Field context 或 `'edit'`),對齊 `field-types.ts` FieldMode：
+- `edit`(預設)— 可切換的 Switch。
+- `view` — **純展示**:渲染 勾/叉 icon(非互動 Switch;true=Check / false=X,中性 foreground 色,SSOT = `../SelectionControl/boolean-value.tsx`),語意由 context(如 DataTable boolean cell 的行/列 header)提供,並與 Input·Select·Textarea view mode 一致。
+- `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)。
+
+### Controlled / Uncontrolled dual-mode
+
+`checked` / `defaultChecked` / `onCheckedChange` 保留 Radix Switch 的 dual-mode contract：傳
+`checked` 時由 consumer 受控；只傳 `defaultChecked` 時由 Switch 內部持有。Wrapper
+以共用 `useControllable` 作單一狀態來源，因此 edit 切換後改成 `mode="view"`
+或 Field readonly 時，非互動分支仍會顯示當前值，不會退回初始值。
+Uncontrolled form 的 `reset()` 會回復 `defaultChecked`；controlled 模式不改寫 consumer 值。
 
 ---
 
@@ -141,7 +158,9 @@ Switch 可透過 `label` / `description` props 內部直接渲染緊鄰文字：
 
 ### Horizontal Field 自動齊右(2026-04-20)
 
-在 `<Field orientation="horizontal">` 內 Switch 自動 `ml-auto`(control area 是 `flex items-center`,Switch 被推到最右邊),**不需要 consumer 傳 className**。這對齊 iOS Settings / macOS System Settings / GitHub Settings / Figma preferences 的 canonical:**toggle 永遠齊右,label 左對齊、固定寬度**——視覺掃描快、列與列對齊一致。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+在 `<Field orientation="horizontal">` 內 Switch 自動 `ml-auto`(control area 是 `flex items-center`,Switch 被推到最右邊),**不需要 consumer 傳 className**。Settings list 的 canonical 是 **toggle 齊右、label 左對齊、固定寬度**，讓列與列對齊並加快掃描。
+
+**⚠️ 自動齊右只適用「純 settings list」情境**(整排獨立 toggle)— 適用判準見下方「兩種對齊慣例」表。**混合表單**(同表單有 Input / SegmentedControl 等其他控件)= Form-edit 情境 → Switch 應與其他控件**左對齊**:consumer 傳 `className="ml-0"` 覆寫(cn 合併時 consumer className 在後,tailwind-merge 以 `ml-0` 蓋掉內部 `ml-auto`)。錨例:`field.stories.tsx`「SegmentedControl 作為 Field 控制元件」混合表單段(2026-06-10 user 拍板修正)。
 
 視覺上等同於 horizontal `<DescriptionItem>`(label 左 / value 右 `justify-between`)——同一個心智模型:**label 描述、trailing slot 呈現狀態**(value 或 toggle)。
 
@@ -149,12 +168,12 @@ Switch 可透過 `label` / `description` props 內部直接渲染緊鄰文字：
 
 ### 對齊情境:Settings list vs Form edit(2026-04-20)
 
-世界級對照 Switch 在 horizontal layout 有**兩種**對齊慣例,由 **context 決定**:
+Switch 在 horizontal layout 有**兩種**對齊慣例,由 **context 決定**:
 
-| Context | 對齊 | 世界級對照 |
+| Context | 對齊 | 本 DS 判準 |
 |---------|------|-----------|
-| **Settings list**(獨立每項 row,一項一個偏好,即時生效,無 submit) | **齊右** | macOS System Settings / iOS Settings / GitHub Settings / Linear Settings |
-| **Form edit**(多欄位混合 control,使用者 submit 才生效) | **緊跟 label / 與其他 control 對齊** | Ant Design Form layout=horizontal / Material Form / Polaris Form | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| **Settings list**(獨立每項 row,一項一個偏好,即時生效,無 submit) | **齊右** | trailing value/control 對齊，方便逐列掃描 |
+| **Form edit**(多欄位混合 control,使用者 submit 才生效) | **緊跟 label / 與其他 control 對齊** | 跟同表單其他 field control 共用起始線 |
 
 **判斷法**:這個頁面有 submit button 嗎?
 - **有** → form → Switch 本來就不是 canonical(該用 Checkbox,見上「與 Checkbox 的分界」)—— 若硬要用 Switch 代替 submit-flow Checkbox,需 consumer 明確不 ml-auto。
@@ -166,22 +185,31 @@ Switch 可透過 `label` / `description` props 內部直接渲染緊鄰文字：
 
 ---
 
+## 邊界案例
+
+- **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）
+- **無 indeterminate 三態**：Switch 只有 on/off；三態用 RadioGroup / SegmentedControl（見「何時不用」）
+
+---
+
 ## 禁止事項
 
 - ❌ 用 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
 
 ---
 
-## 為何無 Inspector / ColorMatrix
+## 為何無 ColorMatrix
 
-- **無 Inspector**:Switch 決策維度只有 `size`(sm / md / lg)× `checked`(ON / OFF)× `disabled` / `readonly`——已由 `SizeMatrix` / `StateBehavior`(四 state + disabled 策略 + readonly) / `LabelIntegration`(Field 整合)三張 story 完整覆蓋。互動 Inspector 切 checked 只是重複 StateBehavior 的 ON / OFF 對照——Switch 是二元元件,互動試玩對教學價值低。
-- **無 ColorMatrix**:Switch 只有一套色彩——ON 用 `bg-primary`(track) + `bg-surface`(thumb),OFF 用 `bg-muted`(track) + `bg-surface`(thumb),無 variant / hue 變體。狀態色完全內嵌在 `StateBehavior` story(ON / OFF / disabled 的 track bg + thumb 綁定)。重寫 ColorMatrix = 複製 StateBehavior 內容。
+- **無 ColorMatrix**:Switch 只有一套色彩——ON 用 `bg-primary`(track) + `bg-on-emphasis`(thumb),OFF 用 `bg-border`(neutral-5)(track) + `bg-on-emphasis`(thumb),無 variant / hue 變體。狀態色完全內嵌在 `StateBehavior` story(ON / OFF / disabled 的 track bg + thumb 綁定)。重寫 ColorMatrix = 複製 StateBehavior 內容。
 
-對應 anatomy story:保留 `Overview` + `SizeMatrix` + `StateBehavior` + 元件特有 `LabelIntegration`(Field 包裝後的 label/description 管理)。
+對應 anatomy story:`Overview` + `Inspector` + `SizeMatrix` + `StateBehavior` + 元件特有 `LabelIntegration`(Field 包裝後的 label/description 管理)+ `Accessibility`。
 
 ---
 
@@ -202,7 +230,7 @@ Switch 可透過 `label` / `description` props 內部直接渲染緊鄰文字：
 - Tab — focus
 - Space / Enter — toggle on/off
 
-**Focus**:Radix primitive 自管 focus trap / restoration / visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。
+**Focus**:Switch 本體是原生切換按鈕,本身即可被 Tab 聚焦;聚焦時的 focus-visible ring 由 design-system 的 focus-visible 樣式提供(`focus-visible:ring-2 focus-visible:ring-ring`)。Switch 是單一控件,不涉及 focus trap / restoration(那是 Dialog / Popover 等容器才有的行為)。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
@@ -210,6 +238,7 @@ Switch 可透過 `label` / `description` props 內部直接渲染緊鄰文字：
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `checkbox.spec.md`
 - `combobox.spec.md`
 - `radio-group.spec.md`
 - `select.spec.md`