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

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 />
+          <Switch defaultChecked />
+          <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' | 'display' | 'readonly' | 'disabled'", "'edit'", 'Field mode(默認 inherit Field context 或 edit);display 渲純展示 ✓/—,語意由 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 拍板)'],
+              ].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', 'display', 'readonly', 'disabled'],
+      description: 'Field mode;display 渲純展示 ✓/—(語意由 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 內灰框 + ✓/—)' },
+    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 />
+            <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 />
+            <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 />
+            <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 內灰框 + ✓/—。</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 />
+          </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 />
+          </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 />
+          </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 />
+          </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 />
+          </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 />
+          </div>
+        </div>
+      </div>
+
+      <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>
+      </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,174 @@
+// @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} />
+            </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 />
+          </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 />
+          </div>
+        </div>
+      </Rule>
+
+      <Rule
+        title="使用場景對照"
+        note="Readonly(standalone settings list):值重要、視覺不能弱化。表單 readonly = Field 內灰框 + ✓/—(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>
+    </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)——track 和 thumb 在 on/off 之間形狀完全相同,只有顏色變。若灰階 swap(primary → border),disabled 的 ON 和 OFF 會看起來一模一樣,使用者無法分辨當前狀態"
+      >
+        <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 />
+          </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 />
+          </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 />
+          </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 />
+          </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」,視覺一模一樣——使用者不知道這個被停用的開關當前是開還是關"
+      >
+        <Label warn>設計上禁止——Switch 是系統內唯一靠顏色承載 state 的元件,必須保留顏色</Label>
+      </Rule>
+    </div>
+  ),
+}
+

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

@@ -0,0 +1,238 @@
+---
+component: Switch
+family: self-contained
+variants: {}
+sizes:
+  sm:
+    when: "form field-height 28 / compact chrome / dialog / panel context"
+  md:
+    when: "default general UI"
+  lg:
+    when: "touch / prominent CTA / stakeholder-facing surface"
+traits:
+  - hasSizes
+  - hasInteractiveStates
+  - isSelectionSingle
+benchmark:
+  - Radix Switch primitive: github.com/radix-ui/primitives/tree/main/packages/react/switch
+  - MUI Switch: github.com/mui/material-ui/tree/master/packages/mui-material/src/Switch
+  - Carbon Toggle: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Toggle
+  - 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 設計原則
+
+## 定位
+
+Switch 是**即時套用的布林開關**——切換即生效，心智模型是「實體開關」（牆上 light switch、iPhone settings 開關）。
+
+**Layout Family**：非上述 family — self-contained primitive（獨立視覺，無 slot 結構）。
+
+**實作基礎**：基於 Radix Switch（shadcn 包裝）+ 橋接 DS token。
+
+---
+
+## 何時用
+
+- **系統設定類 toggle**：Bluetooth / Wi-Fi / 飛航模式 / Dark mode / Push 通知
+- **即時功能開關**：is_public / is_featured（admin 即時切換）、自動儲存 on/off
+- **獨立 inline control**：切換即生效，旁邊沒有 submit / cancel button 流程
+- **物理開關類比**：使用者心智模型是「我現在要打開 / 關閉這個功能」
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| Form 內的布林欄位（隨 submit 生效）| `Checkbox` | 見下「與 Checkbox 的分界」 |
+| 同意條款 / 隱私政策 | `Checkbox` | 條款是「勾選送出才成立」的書面行為，不是物理開關 |
+| 多選（複選多個選項）| `Checkbox` stack | Switch 是單一布林，多選用 Checkbox |
+| 三態或更多（enum）| `RadioGroup` / `SegmentedControl` | Switch 只有 on/off |
+| 有進度的動作（「正在開啟中」）| `Button` with loading state | Switch 是瞬時切換，不承載進度 |
+
+---
+
+## 與 Checkbox 的分界
+
+**兩者都是布林 on/off，判斷核心是「套用時機」與「心智模型」**。
+
+**完整對照 SSOT 在 `../Checkbox/checkbox.spec.md`「與 Switch 的分界」段落**——Checkbox 是此比較的 owner（包含三個判斷角度 + 9 項情境對照表）。
+
+簡言：
+- **Form 內、有 submit 流程、使用者可反悔** → `Checkbox`
+- **獨立 inline、切換即生效、無 submit** → `Switch`
+
+---
+
+## 結構
+
+```
+Track（pill 形，rounded-full）
+  └─ Thumb（白色圓 + 2px border + check icon when ON）
+```
+
+- Track 寬 = 2 × 高（pill 比例）
+- Thumb 直徑 = track 高度
+- ON 狀態 thumb 右滑 `translateX(trackHeight)`
+
+---
+
+## 尺寸
+
+| Size | Track | Thumb | 白色圓 | Check icon | 配對 field |
+|------|-------|-------|-------|-----------|-----------|
+| sm / md（預設）| 20 × 40 | 20 | 16 | 12 | field sm / md |
+| lg | 24 × 48 | 24 | 20 | 16 | field lg |
+
+sm 和 md 視覺相同（純粹命名 mapping，讓消費者可直接傳同一個 size 對齊 Field family）。
+
+### 為什麼不完全對齊 `--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 -->
+
+---
+
+## 視覺狀態
+
+| 狀態 | Track | Thumb | Check icon |
+|------|-------|-------|-----------|
+| OFF | `bg-border`（neutral-5） | 白色 + 2px `border-border`（neutral-5，與 OFF track 同色） | 無 |
+| ON | `bg-primary` | 白色 + 2px primary border | primary check |
+| Disabled | 套 `opacity-disabled`（整體透明度降級） | 同 ON/OFF | 同 ON/OFF |
+| Readonly(standalone)| 視覺同一般態 | 但 `pointer-events-none` + `aria-readonly` | — |
+| Readonly(Field 內,2026-06-12 user 拍板)| 不渲染 toggle — 改渲染 `fieldWrapperStyles` readonly 灰框(= Input readonly 同源)+ ✓/—(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` 區分)。
+
+**對照**：
+- Checkbox disabled 可以灰階 swap——checkmark 形狀承載 state，顏色只是裝飾
+- Slider disabled 可以灰階 swap——thumb 位置和 range 長度承載 state
+- Switch disabled **必須保留顏色**——沒有形狀差異，灰階後 state 失傳
+
+詳細對照見 `../Slider/slider.spec.md`「Disabled 策略」節。
+
+### Readonly vs Disabled(standalone;Field 內 readonly = 灰框 + ✓/—,見上方狀態表)
+
+| | Readonly(standalone) | Disabled |
+|---|---|---|
+| 視覺 | 正常顏色（可讀） | 降透明度（弱化） |
+| 互動 | 不可切換（pointer-events-none） | 不可切換（cursor-not-allowed） |
+| aria | `aria-readonly` | `disabled` |
+| Tab 焦點 | 不在 tab order | 不在 tab order |
+| 用途 | 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` — **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)。
+
+---
+
+## label / description 整合
+
+Switch 可透過 `label` / `description` props 內部直接渲染緊鄰文字：
+
+```tsx
+<Switch label="啟用通知" description="收到新訊息時提醒" />
+```
+
+在 `<Field>` context 內時 label / description prop 自動忽略（由 FieldLabel / FieldDescription 接管），避免雙層 label。
+
+### 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 -->
+
+**⚠️ 自動齊右只適用「純 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)。
+
+**同一畫面多個 horizontal Switch Field → 必搭配 `FieldGroup horizontalLabelWidth={...}`**:否則每個 label 會被內容撐到不同寬度,Switch 左邊緣不對齊,整排參差不齊(世界級 UI 通病,Settings 類型畫面特別明顯)。見 `../Field/field.spec.md`「FieldGroup horizontalLabelWidth cascade」。
+
+### 對齊情境:Settings list vs Form edit(2026-04-20)
+
+世界級對照 Switch 在 horizontal layout 有**兩種**對齊慣例,由 **context 決定**:
+
+| Context | 對齊 | 世界級對照 |
+|---------|------|-----------|
+| **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 -->
+
+**判斷法**:這個頁面有 submit button 嗎?
+- **有** → form → Switch 本來就不是 canonical(該用 Checkbox,見上「與 Checkbox 的分界」)—— 若硬要用 Switch 代替 submit-flow Checkbox,需 consumer 明確不 ml-auto。
+- **無** → settings list → **auto ml-auto 齊右 canonical**(本元件 2026-04-20 行為)
+
+本 DS 的 `auto ml-auto` 邏輯是**為 settings list 最佳化**。若 consumer 把 Switch 放 submit form 並想「緊跟 label」,需自行在 `<Switch className="ml-0">` 覆寫——但更推薦重新考慮是不是該用 Checkbox。
+
+> **記住**:在 form 內 + Switch 緊跟 label 的覆寫寫法是 **`<Switch className="ml-0" />`**。這是**目前唯一**需要 consumer 明示 override 的 Switch 行為(其他 layout 都 auto)。但 99% 情境使用者應該先問「是不是該用 Checkbox」——Switch 即時生效的心智模型跟 submit form 本來就衝突。
+
+---
+
+## 邊界案例
+
+- **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）
+- **無 indeterminate 三態**：Switch 只有 on/off；三態用 RadioGroup / SegmentedControl（見「何時不用」）
+
+---
+
+## 禁止事項
+
+- ❌ 用 Switch 做 form 內的同意 / 勾選——「我同意條款」是書面成立行為，用 Checkbox
+- ❌ 把 Switch 當三態使用（例：「on / off / auto」）——用 RadioGroup / SegmentedControl
+- ❌ 對 disabled 狀態用灰階 swap 而非 opacity——會讓 on/off 視覺無法區分（見「Disabled 用 opacity」段）
+- ❌ Switch 的 on/off 顯示「正在處理中」進度——用 Button + loading state
+- ❌ 直接改動 track 顏色承載額外語意（例如 error 時改紅）——Switch 是單純布林，錯誤訊息放外部 help text
+
+---
+
+## 為何無 ColorMatrix
+
+- **無 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` + `Inspector` + `SizeMatrix` + `StateBehavior` + 元件特有 `LabelIntegration`(Field 包裝後的 label/description 管理)+ `Accessibility`。
+
+---
+
+## 相關
+
+- `../Checkbox/checkbox.spec.md` — **與 Switch 的分界 SSOT owner**（套用時機、心智模型、情境對照）
+- `../Slider/slider.spec.md` — Disabled 策略對照（為什麼 Switch 用 opacity 而 Slider 用灰階）
+- `../Field/field.spec.md` — Switch 作為 Field control 的整合（label/description 由 Field 接管）
+- `../Field/field-controls.spec.md` — Field Control 共用規則
+- `../Button/button.spec.md` — `pressed` 狀態的 toggle button（非單純布林，有 label/icon 的情況改用 pressed Button）
+
+## A11y 預設
+
+**ARIA / Pattern**:繼承 Radix `switch` primitive a11y 預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/switch#accessibility)。
+
+**Keyboard 行為**:
+
+- Tab — focus
+- Space / Enter — toggle on/off
+
+**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)。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `checkbox.spec.md`
+- `combobox.spec.md`
+- `radio-group.spec.md`
+- `select.spec.md`