@qijenchen/design-system 0.1.0-beta.61 → 0.1.0-beta.63

package/src/components/SelectMenu/select-menu.anatomy.stories.tsx

@@ -108,8 +108,8 @@ export const Overview: Story = {
                   <Td mono>cmdk</Td>
                 </tr>
                 <tr>
-                  <Td mono>CommandInput</Td>
-                  <Td>搜尋框(searchable 模式,高度對齊 field-height)</Td>
+                  <Td mono>CommandPrimitive.Input</Td>
+                  <Td>搜尋框(raw cmdk input + 自建 wrapper,searchable 模式,高度對齊 field-height)</Td>
                   <Td mono>cmdk</Td>
                 </tr>
                 <tr>

package/src/components/SelectMenu/select-menu.principles.stories.tsx

@@ -28,11 +28,11 @@ export const UsageGuidance: Story = {
         <div className="prose prose-sm max-w-prose mb-8">
           <p>適合 SelectMenu 的真實業務場景(點擊跳轉「展示」頁範例):</p>
           <ul className="space-y-1">
-            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" name="單選"><span className="text-primary hover:underline font-medium cursor-pointer">單選</span></LinkTo></li>
-            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" name="搜尋"><span className="text-primary hover:underline font-medium cursor-pointer">搜尋</span></LinkTo></li>
-            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" name="多選"><span className="text-primary hover:underline font-medium cursor-pointer">多選</span></LinkTo></li>
-            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" name="多選 + 搜尋"><span className="text-primary hover:underline font-medium cursor-pointer">多選 + 搜尋</span></LinkTo></li>
-            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" name="可清除"><span className="text-primary hover:underline font-medium cursor-pointer">可清除</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" name="單選"><span className="text-primary hover:underline font-medium cursor-pointer">議題狀態欄位擇一指派(單選)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" name="搜尋"><span className="text-primary hover:underline font-medium cursor-pointer">數百人組織選負責人,輸入過濾(搜尋)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" name="多選"><span className="text-primary hover:underline font-medium cursor-pointer">工單同時貼多個標籤(多選)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" name="多選 + 搜尋"><span className="text-primary hover:underline font-medium cursor-pointer">大量標籤庫中過濾並複選(多選 + 搜尋)</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Internal/SelectMenu/展示" name="可清除"><span className="text-primary hover:underline font-medium cursor-pointer">篩選列一鍵清空已選條件(可清除)</span></LinkTo></li>
           </ul>
           <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方 vs 近親 段)。</p>
         </div>

package/src/components/SelectMenu/select-menu.spec.md

@@ -29,7 +29,7 @@ SelectMenu 是 **Popover + Command 組成的完整下拉選單浮層**——提
 
 ## Controlled-only rationale(Dim 26)
 
-本元件刻意採 **controlled-only** 模式:`value` + `onChange` 必傳,不支援 `defaultValue` uncontrolled fallback。
+本元件刻意採 **controlled-only** 模式:value 軸走 `value` + `onValueChange`(型別宣告 optional、無 runtime 強制,但 internal 消費者 Select / Combobox / PeoplePicker 一律傳入),不支援 `defaultValue` uncontrolled fallback。
 
 **為什麼**:
 - 內部狀態複雜(search filter / range / menu open state)跟 `value` 雙向 sync 會產生 race condition
@@ -54,9 +54,11 @@ SelectMenu 是 **Popover + Command 組成的完整下拉選單浮層**——提
 
 ### 消費者
 
-- `../PeoplePicker/people-picker.tsx` — 人員選擇（永遠 searchable）
-- `../Select/select.tsx` — `searchable` 模式會切換到 SelectMenu 浮層
-- `../Combobox/combobox.tsx` — `searchable` 模式會切換到 SelectMenu 浮層
+- `../Select/select.tsx` — `searchable` 模式會切換到 SelectMenu 浮層（直接 import）
+- `../Combobox/combobox.tsx` — `searchable` 模式會切換到 SelectMenu 浮層（直接 import）
+- `../PeoplePicker/people-picker.tsx` — 人員選擇（永遠 searchable;**間接消費** — wrap Select / Combobox,不直接 import SelectMenu,見 `people-picker.spec.md`「實作基礎」）
+
+**常見誤解**:(1)「要下拉浮層就 import SelectMenu」— internal primitive,一律經 Select / Combobox / PeoplePicker 消費(見上表);(2)「SelectMenu = DropdownMenu」— SelectMenu 是**選值**(值留在 field),DropdownMenu 是**執行動作**(點完即關)— 分界 SSOT 見 `dropdown-menu.spec.md`「與 SelectMenu 的區別」。
 
 ---
 
@@ -65,7 +67,7 @@ SelectMenu 是 **Popover + Command 組成的完整下拉選單浮層**——提
 ```
 Popover（浮動容器，handle 展開 / 定位）
   └─ Command（cmdk — 搜尋 + 鍵盤導覽）
-       ├─ CommandInput（搜尋框，searchable 模式時顯示；選項 > 5 時建議開啟）
+       ├─ 搜尋框（`CommandPrimitive.Input` raw cmdk + 自建 icon/min-h wrapper，非 DS `CommandInput`；searchable 模式時顯示；選項 > 5 時建議開啟）
        ├─ CommandList（捲動區）
        │    └─ CommandGroup（分組標題）
        │         └─ MenuItem（選項 row，消費 item-layout）
@@ -91,7 +93,7 @@ Popover（浮動容器，handle 展開 / 定位）
 
 ## Creatable（建立新選項）
 
-透過 `onCreate` prop 啟用。搜尋無結果時顯示「建立 "xxx"」提示（`Plus` icon + 使用者輸入的字）。
+透過 `creatable` + `onCreate` 啟用。search 非空且**無 label 完全相同(忽略大小寫)的既有選項**時,顯示 create row(`Plus` icon + `createLabel(query)`,預設「直接使用「xxx」」;`select-menu.tsx:219-224`)——完全同名時自動隱藏,防重複建立。
 
 **何時啟用**：
 - Tag input 允許使用者建立新 tag
@@ -122,7 +124,7 @@ Popover（浮動容器，handle 展開 / 定位）
 
 搜尋無結果時顯示 `Empty` 元件，可透過 `emptyText` 自訂訊息（預設「沒有符合的選項」）。
 
-- **Creatable 時**：即使搜尋無結果，仍顯示「建立 "xxx"」讓使用者補建選項
+- **Creatable 時**：即使搜尋無結果，仍顯示 create row 讓使用者補建選項（顯示條件見「Creatable」段）
 - **非 creatable**：顯示 emptyText 提示使用者修改搜尋詞
 
 ---
@@ -135,9 +137,9 @@ Popover（浮動容器，handle 展開 / 定位）
 - **Dropdown 開啟時**：options 替換為 panel-center `<Empty icon={<CircularProgress size={48}/>} className="py-6"/>` compose 視覺（純 spinner，無 description）
 - **CircularProgress 預設 24px**，但在 Empty wrapper 內 48px（取代 Empty 的 48px Avatar icon slot）
 
-對齊 MUI Autocomplete loading dropdown-body + Ant Select loading idiom + DS `empty.spec.md:191`「全頁 loading = Empty + CircularProgress compose」SSOT（SelectMenu loading 用法 canonical row 見 `empty.spec.md:163`）。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+對齊 MUI Autocomplete loading dropdown-body + Ant Select loading idiom + DS `empty.spec.md`「禁止事項」段「loading 用 Empty + CircularProgress compose」SSOT（SelectMenu loading 用法 canonical row 見 `empty.spec.md`「現有消費者」表）。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
-**消費**：Select / Combobox / PeoplePicker forward `loading` prop 到 SelectMenu，本元件不需 consumer 直接知道 Empty + CircularProgress 組合（封裝在內）。
+**消費**：Select / Combobox forward `loading` prop 到 SelectMenu（PeoplePicker 尚未暴露 / 轉發 `loading`，見 `people-picker.spec.md`「邊界案例」），本元件不需 consumer 直接知道 Empty + CircularProgress 組合（封裝在內）。
 
 ---
 
@@ -156,7 +158,8 @@ Popover（浮動容器，handle 展開 / 定位）
 - **Disabled option**:individual MenuItem 透過 `disabled?: boolean` 控制(SelectMenu primitive option contract)。視覺繼承 `MenuItem` SSOT:text → `text-fg-disabled`(M24)、無 hover bg、`aria-disabled="true"`、Enter / click 不觸發 onChange、鍵盤導覽自動 skip。
 - **Disabled trigger**:trigger 由 consumer(Select / Combobox / PeoplePicker)的 `disabled` prop own,本元件不獨立 disable trigger。
 - **Loading**:已 codify(見「Loading」段),`loading=true` 時 dropdown body 切 panel-center Empty + CircularProgress 48px。
-- **Empty**:已 codify(見「Empty state」段),搜尋無結果 + 非 creatable 時渲 emptyText;creatable 時保留「建立 "xxx"」row。
+- **Empty**:已 codify(見「Empty state」段),搜尋無結果 + 非 creatable 時渲 emptyText;creatable 時保留 create row(可鍵盤選取)。
+- **Creatable + search 與既有選項完全同名**(忽略大小寫):create row 隱藏(防重複建立,`select-menu.tsx:219-224`);選取既有選項為唯一路徑。
 - **Dark mode**:走 Popover / MenuItem semantic token 自動 adapt。
 - **Density**:row height 由 `MenuItem` SSOT 控(sm/md/lg);SelectMenu 不獨立 own density。
 
@@ -174,11 +177,12 @@ SelectMenu 是**多區塊 composite primitive**,不擁有獨立色彩決策:
 
 ## shadcn passthrough 例外說明
 
-SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem list + 浮動 surface),純 declarative API。**不套 `forwardRef` / `...props` spread`**,同 PeoplePicker 理由:
+SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem list + 浮動 surface),純 declarative API。**套 `forwardRef` 簽名但 ref 不附著、無 `...props` spread**(shadcn forwardRef + displayName 統一;`select-menu.tsx:122-126` rationale):
 
 - **沒有單一 DOM root 可 ref**:trigger / search input / list / content portal 各自 DOM tree 離散
 - **`...props` spread 目標不明**:composite 的 root wrapper 只是 control 容器,spread 到那裡 consumer 無從預期作用
-- **API 邊界明確**:SelectMenu 暴露「選值」語意(value / onChange / options / mode),不暴露 DOM 細節
+- **API 邊界明確**:SelectMenu 暴露「選值」語意(value / onValueChange / options / mode),不暴露 DOM 細節
+- **`className` 合併到 PopoverContent**(contextually 最接近 user-facing surface)
 
 `displayName = 'SelectMenu'` 保留。若 consumer 需要 DOM-level 控制(custom trigger / portal / search input ref),改用底層 Popover + Command 自組。
 
@@ -220,3 +224,6 @@ SelectMenu 是 **composite**(Popover trigger + Command search + 滾動 MenuItem
 
 - `command.spec.md`
 - `dropdown-menu.spec.md`
+- `menu-item.spec.md`
+- `popover.spec.md`
+- `select.spec.md`

package/src/components/SelectMenu/select-menu.stories.tsx

@@ -118,31 +118,38 @@ export const Clearable: StoryObj = {
 }
 
 // @story-trait-rationale: AllSizes retired per F migration 2026-05-15 — anatomy.stories.tsx SizeMatrix auto-compile owns size showcase。
-// ── 狀態 ──
-
-export const States: StoryObj = {
-  name: '狀態',
-  render: () => {
-    const [value, setValue] = React.useState('in_stock')
-    return (
-      <div className="flex flex-col gap-6 max-w-xs">
-        <div>
-          <span className="text-caption text-fg-muted mb-1 block">edit</span>
-          <Select options={statusOptions} value={value} onChange={setValue} />
-        </div>
-        <div>
-          <span className="text-caption text-fg-muted mb-1 block">readonly</span>
-          <Select mode="readonly" options={statusOptions} value={value} />
-        </div>
-        <div>
-          <span className="text-caption text-fg-muted mb-1 block">disabled</span>
-          <Select mode="disabled" options={statusOptions} value={value} />
-        </div>
-        <div>
-          <span className="text-caption text-fg-muted mb-1 block">error</span>
-          <Select options={statusOptions} value={value} onChange={setValue} error />
-        </div>
-      </div>
-    )
-  },
+// @story-trait-rationale: 原 States(edit/readonly/disabled/error 觸發器狀態)retired 2026-06-11 —
+//   trigger field state 由 Select.stories.tsx「四模式」owns(SelectMenu 是 internal popover surface,
+//   不 own input state,見檔頭 rationale)。本層改示範浮層自己 own 的選項狀態。
+// ── 選項狀態(浮層內)──
+
+const assigneeOptions = [
+  { value: 'ada', label: 'Ada Chen', description: 'Design Engineer' },
+  { value: 'ben', label: 'Ben Liu', description: 'Frontend' },
+  { value: 'cindy', label: 'Cindy Wang', description: '休假中,暫不可指派', disabled: true },
+  { value: 'derek', label: 'Derek Kao', description: 'Backend' },
+]
+
+const OptionStatesDemo = () => {
+  const [value, setValue] = React.useState<string>('ada')
+  return (
+    <div className="flex flex-col gap-4 max-w-xs">
+      <p className="text-caption text-fg-secondary">
+        浮層內選項狀態 — 已選中(勾選標記)、disabled(休假成員不可選)、搜尋無結果(輸入不存在的名字)
+      </p>
+      <Select
+        options={assigneeOptions}
+        value={value}
+        onChange={setValue}
+        searchable
+        placeholder="指派負責人…"
+        aria-label="指派負責人(SelectMenu option-states demo)"
+      />
+    </div>
+  )
+}
+
+export const OptionStates: StoryObj = {
+  name: '選項狀態',
+  render: () => <OptionStatesDemo />,
 }

package/src/components/SelectMenu/select-menu.tsx

@@ -1,8 +1,13 @@
+/**
+ * @internal — DS-internal 單元(per `.claude/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。
+ * 不進 root barrel front-door;由 Select / Combobox wrap 消費,end-user app 請用 wrapper 元件。
+ */
 // @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 * as React from 'react'
 import { Plus, Search } from 'lucide-react'
 import type { LucideIcon } from 'lucide-react'
 import { cn } from '@/lib/utils'
+import { useControllable } from '@/design-system/hooks/use-controllable'
 import type { AvatarData } from '@/design-system/components/Avatar/avatar'
 import { Popover, PopoverContent, PopoverTrigger } from '@/design-system/components/Popover/popover'
 import { Command, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator } from '@/design-system/components/Command/command'
@@ -150,9 +155,15 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
   className,
 }, _ref) {
   // ── State ──
-  const [internalOpen, setInternalOpen] = React.useState(defaultOpen ?? false)
-  const open = controlledOpen ?? internalOpen
-  const setOpen = controlledOnOpenChange ?? setInternalOpen
+  // 2026-06-11 R2 bug fix:原手寫 `setOpen = controlledOnOpenChange ?? setInternalOpen` 在
+  // uncontrolled + onOpenChange listener 場景(傳 onOpenChange 不傳 open)會讓 listener 蓋掉
+  // internal setter → menu 開不了。改消費 DS 既有 useControllable(select.tsx 同 canonical):
+  // uncontrolled 時 internal state 為準、onOpenChange 僅通知。
+  const [open, setOpen] = useControllable<boolean>({
+    value: controlledOpen,
+    defaultValue: defaultOpen ?? false,
+    onChange: controlledOnOpenChange,
+  })
   const [search, setSearch] = React.useState('')
 
   // ── Value helpers ──

package/src/components/SelectionControl/selection-item.anatomy.stories.tsx

@@ -132,7 +132,7 @@ export const Overview: Story = {
                 <Td mono>content · description</Td>
                 <Td>輔助文字(reading mode,最小 14px)</Td>
                 <Td mono>text-fg-secondary · line-height 1.5</Td>
-                <Td mono>mt-0.5</Td>
+                <Td mono>mt-[var(--item-gap-label-desc-reading)]（lg → -reading-lg）</Td>
               </tr>
             </tbody>
           </table>

package/src/components/SelectionControl/selection-item.spec.md

@@ -34,6 +34,8 @@ SelectionItem 是 **Checkbox 和 RadioGroup 共用的 item 佈局 primitive**—
 
 **SelectionControl 是 internal primitive**——不直接使用，透過 Checkbox / RadioGroup 消費。
 
+**icon / avatar prefix 消費路徑(2026-06-12 M30 修)**:`<Checkbox icon={...}>` / `<RadioGroupItem avatar={...}>` 直接轉發本 primitive 的既有槽(本檔「3-slot 結構」+ selection-item.tsx jsDoc 為對齊規則 SSOT)——不需也不准裸用 `<SelectionItem>`。
+
 | 場景 | 正確做法 |
 |------|---------|
 | 建立一組 Checkbox 選項 | 用 `Checkbox`（內部消費 SelectionItem）|
@@ -71,6 +73,7 @@ Checkbox 和 Radio 視覺幾乎完全一致（差異只在形狀 `rounded-md` vs
 - 單行時總高度 = field-height（對齊同 size 的 Input）
 - 多行時 padding 不變，自然撐高
 - density 切換時 field-height 自動調整，padding 跟著算
+- **size 對應**：sm / md → `text-body` + `--field-height-{sm,md}`；lg → `text-body-lg` + `--field-height-lg`——與同 size Input 消費同一 token，是「單行高度對齊 Input」的機械保證
 
 ### Clamp 政策
 
@@ -100,8 +103,8 @@ SelectionItem 是**純 layout primitive**,只處理 3-slot 結構 + padding 公
 ## 邊界案例
 
 - **Disabled**:`disabled` 把 label / description / prefix icon 統一切 `text-fg-disabled`(M24 disabled>muted);control(Checkbox 方框 / Radio 圓圈)的 disabled 視覺由 consumer control 自己 own。SelectionItem 不獨立 own control state。
-- **Loading**:SelectionItem 為 layout primitive 非 async surface;無 loading state。Group-level loading 由 consumer(CheckboxGroup / RadioGroup)在外層處理(Skeleton stack)。
-- **Empty**:label 必傳(internal API contract);無 label-empty 場景。若 `description` 缺,layout 自動收斂為單行。
+- **Loading**:SelectionItem 為 layout primitive 非 async surface;無 loading state。傳入的 control(Checkbox / Radio)亦無 loading prop(tsx 驗證);group-level loading 由 consumer(CheckboxGroup / RadioGroup)在外層處理(Skeleton stack)。
+- **Empty**:label 為 required prop(省略 = TS error);傳空字串不防呆——會渲染空 `<label>`(點擊目標退化),consumer(Checkbox / RadioGroup)契約上必傳有效 label。若 `description` 缺,layout 自動收斂為單行。
 - **Dark mode / density**:走 semantic token 自動 adapt;`py` padding 公式對齊 `--field-height-{sm/md/lg}` density token。
 
 ---
@@ -128,3 +131,11 @@ SelectionItem 是純佈局元件,本身**不接管**鍵盤、焦點與勾選狀
 
 **驗證**: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`
+- `item-anatomy.spec.md`
+- `menu-item.spec.md`
+- `radio-group.spec.md`

package/src/components/SelectionControl/selection-item.stories.tsx

@@ -14,7 +14,7 @@ const meta: Meta<typeof SelectionItem> = {
     docs: {
       description: {
         component:
-          'SelectionItem 是 Checkbox 與 RadioGroup 共用的 item 佈局 primitive——提供 control + optional prefix(icon/avatar) + content(label/description) 的 3-slot 結構,並處理 `py = (field-height - 1lh) / 2` 的 padding 公式讓單行高度對齊同 size 的 Input。App 層級應使用 Checkbox / RadioGroup,不直接使用 SelectionItem——以下情境展示 primitive 被兩個 consumer 包出的樣貌。',
+          'SelectionItem 是 Checkbox 與 RadioGroup 共用的 item 佈局 primitive——提供 control + optional prefix(icon/avatar) + content(label/description) 的 3-slot 結構,並處理 `py = (field-height - 1lh) / 2` 的 padding 公式讓單行高度對齊同 size 的 Input。App 層級應使用 Checkbox / RadioGroup,不直接使用 SelectionItem——前兩個情境展示 primitive 被 Checkbox / RadioGroup 包出的樣貌;後兩個(前綴圖示 / 前綴頭像)直接以 primitive 展示 prefix slot 結構(docs 結構展示用,非 App 層用法)。',
       },
     },
   },

package/src/components/SelectionControl/selection-item.tsx

@@ -1,3 +1,7 @@
+/**
+ * @internal — DS-internal 單元(per `.claude/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。
+ * 不進 root barrel front-door;由 Checkbox / RadioGroup wrap 消費,end-user app 請用 wrapper 元件。
+ */
 import * as React from 'react'
 import { cva, type VariantProps } from 'class-variance-authority'
 import type { LucideIcon } from 'lucide-react'
@@ -9,7 +13,7 @@ import { ICON_SIZE, AVATAR_SIZE } from '@/design-system/patterns/element-anatomy
 // Checkbox 和 RadioGroup 共用的 item 佈局。
 //
 // 結構(item-anatomy.spec.md 4-slot 模型):
-//   [control] [optional prefix(icon|avatar)] [content(label/desc)] [optional suffix]
+//   [control] [optional prefix(icon|avatar)] [content(label/desc)](3-slot,見 spec「定位」)
 //
 // padding 公式：py = (field-height - 1lh) / 2
 //   - 單行時 item 高度 = field-height（對齊同 size 的 Input）
@@ -169,6 +173,8 @@ function ContentSlot({ htmlFor, disabled, label, description, sizeKey, labelClam
     <div className="min-w-0 flex-1">
       <label
         htmlFor={htmlFor}
+        // 2026-06-10 a11y:styled-disabled label 明告 inactive(WCAG 1.4.3 豁免可機判;對齊 FieldLabel 同修;a11y 補強不動 SSOT = AUTO 分權,user verbatim「確保所有的任務你都有做到完美做到完整」)
+        aria-disabled={disabled || undefined}
         className={cn(
           'cursor-pointer block break-words',
           labelClampClass,
@@ -252,7 +258,7 @@ export const selectionItemMeta = {
     lg: {},
   },
   defaultSize: 'md',
-  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],
+  states: ['default', 'disabled'], // disabled 是唯一視覺狀態;selected / hover 屬傳入的 control(spec「為何無 ColorMatrix / StateBehavior」)
   tokens: {
     fg: ['text-foreground', 'text-fg-secondary', 'text-fg-disabled'],
   },

package/src/components/Separator/separator.principles.stories.tsx

@@ -54,10 +54,10 @@ export const UsageGuidance: Story = {
       <p>適合 Separator 的真實業務場景(點擊跳轉「展示」頁範例):</p>
       <ul className="space-y-1">
         <li>
-          <LinkTo kind="Design System/Components/Separator/展示" name="Horizontal"><span className="text-primary hover:underline font-medium cursor-pointer">Horizontal</span></LinkTo>
+          <LinkTo kind="Design System/Components/Separator/展示" name="水平"><span className="text-primary hover:underline font-medium cursor-pointer">水平分隔</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Separator/展示" name="Vertical"><span className="text-primary hover:underline font-medium cursor-pointer">Vertical</span></LinkTo>
+          <LinkTo kind="Design System/Components/Separator/展示" name="垂直"><span className="text-primary hover:underline font-medium cursor-pointer">垂直分隔</span></LinkTo>
         </li>
         <li>
           <LinkTo kind="Design System/Components/Separator/展示" name="在 DropdownMenu 內"><span className="text-primary hover:underline font-medium cursor-pointer">在 DropdownMenu 內</span></LinkTo>

package/src/components/Separator/separator.spec.md

@@ -29,16 +29,16 @@ Separator 是語意分隔元件，用於標示內容群組之間的邊界。
 ### Consumer 手動放 → Separator 元件
 
 Consumer 在 JSX 裡明確放置分隔線的場景：
-- `<SidebarSeparator />` 在 sidebar 群組間
-- `<DropdownMenuSeparator />` 在操作選單項目間
-- `<ButtonDivider />` 在按鈕群組內
+- `<SidebarSeparator />` 在 sidebar 群組間（消費 DS Separator）
+- `<DropdownMenuSeparator />` 在操作選單項目間（Radix Menu 自有 separator primitive，非 DS Separator）
+- `<ButtonDivider />` 在按鈕群組內（raw div + `role="separator"`，非 DS Separator）
 
-為什麼：Consumer 控制的分隔點需要語意標記（`role="separator"`），讓輔助技術能辨識內容群組邊界。
+為什麼：Consumer 控制的分隔點由放置者宣告語意——DS Separator 預設 decorative（`role="none"`，SR 靜默），真實切分內容區段時 `decorative={false}` 才輸出 `role="separator"`（詳「A11y 預設」段）。
 
 ### 元件自動分隔相鄰群組 → CSS `[&+&]`
 
 元件內部自動在相鄰同類群組間產生分隔線：
-- `MenuGroup`:相鄰同類群組之間自動出現 `border-divider` 分隔(見 `menu.tsx`)
+- `MenuGroup`:相鄰同類群組之間自動出現 `border-divider` 分隔(見 `menu-item.tsx`)
 - `SidebarGroup`:相鄰群組之間自動產生分隔線(見 `sidebar.tsx`)
 
 為什麼：Consumer 只需要思考「分組」，不需要記得放分隔線。CSS 相鄰選擇器無法用元件替代（無處插入 DOM node）。
@@ -76,6 +76,12 @@ Consumer 在 JSX 裡明確放置分隔線的場景：
 - ❌ 用 `--border` token 做分隔線（應該用 `--divider`）
 - ❌ 用 `bg-border` 做 ButtonDivider 等 consumer 放置的分隔線
 
+## 邊界案例
+
+- **Vertical 方向**：`h-full` 取父容器高度——父容器無確定高度（auto）時 separator 高度為 0、不可見；需父容器有確定高度或 flex row 的 stretch 對齊
+- **空容器 / 0 寬**：horizontal `w-full` 隨父寬，父寬為 0 時無可見線；Separator 不自帶 min-width / min-height
+- **厚度固定 1px**（`h-px` / `w-px`）、非互動無 hover / focus——無 size / state 變體（見下「為何無 …」段）
+
 ## 為何無 Inspector / ColorMatrix / SizeMatrix / StateBehavior
 
 Separator 是**視覺分隔 primitive**(一條 1px 線),結構極薄:

package/src/components/Sheet/sheet.anatomy.stories.tsx

@@ -7,6 +7,7 @@ import {
   SheetHeader,
   SheetTitle,
   SheetDescription,
+  SheetBody,
   SheetFooter,
 } from './sheet'
 import { Button } from '@/design-system/components/Button/button'
@@ -36,10 +37,10 @@ export const Overview: Story = {
                 <SheetTitle>修復付款流程 bug</SheetTitle>
                 <SheetDescription>#PROJ-1234 · 指派給陳大明</SheetDescription>
               </SheetHeader>
-              <div className="flex-1 p-4 text-body">
+              <SheetBody className="text-body">
                 <p className="mb-3 text-fg-secondary">使用者於結帳最後一步點選「完成付款」後,頁面卡在轉圈動畫超過 30 秒,最終回到購物車且訂單未成立。重現率約 1/5,僅出現在 Safari 17。</p>
                 <p className="text-caption text-fg-muted">優先級 P1 · 影響 230 筆訂單 · 截止 2026-04-25</p>
-              </div>
+              </SheetBody>
               <SheetFooter>
                 <Button variant="tertiary">標記為已解決</Button>
                 <Button variant="primary">儲存變更</Button>
@@ -118,10 +119,10 @@ export const Inspector: Story = {
             <SheetTitle>修復付款流程 bug</SheetTitle>
             <SheetDescription>#PROJ-1234 · 指派給陳大明</SheetDescription>
           </SheetHeader>
-          <div className="flex-1 p-4 text-body">
+          <SheetBody className="text-body">
             <p className="mb-3 text-fg-secondary">使用者於結帳最後一步點選「完成付款」後,頁面卡在轉圈動畫超過 30 秒,最終回到購物車且訂單未成立。重現率約 1/5,僅出現在 Safari 17。</p>
             <p className="text-caption text-fg-muted">優先級 P1 · 影響 230 筆訂單 · 截止 2026-04-25</p>
-          </div>
+          </SheetBody>
           {showFooter && (
             <SheetFooter>
               <Button variant="tertiary">標記為已解決</Button>
@@ -166,9 +167,9 @@ export const SideMatrix: Story = {
               <SheetTitle>Q1 財報</SheetTitle>
               <SheetDescription>最後編輯：2026-04-18 17:32</SheetDescription>
             </SheetHeader>
-            <div className="flex-1 p-4">
+            <SheetBody>
               <p className="text-body text-fg-secondary">本季營收 NT$4,820 萬,較上季成長 12%;毛利率 38.5%。下方附完整損益表與部門別明細,可直接在此面板註記後送交財務複核。</p>
-            </div>
+            </SheetBody>
             <SheetFooter>
               <Button variant="primary">儲存</Button>
             </SheetFooter>

package/src/components/Sheet/sheet.principles.stories.tsx

@@ -10,6 +10,7 @@ import {
   SheetHeader,
   SheetTitle,
   SheetDescription,
+  SheetBody,
   SheetFooter,
   SheetClose,
 } from './sheet'
@@ -32,7 +33,6 @@ import { Button } from '@/design-system/components/Button/button'
 import { Field, FieldLabel } from '@/design-system/components/Field/field'
 import { Input } from '@/design-system/components/Input/input'
 import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
-import { ScrollArea } from '@/design-system/components/ScrollArea/scroll-area'
 
 const meta: Meta = {
   title: 'Design System/Components/Sheet/設計原則',
@@ -75,10 +75,10 @@ export const UsageGuidance: Story = {
       <p>適合 Sheet 的真實業務場景(點擊跳轉「展示」頁範例):</p>
       <ul className="space-y-1">
         <li>
-          <LinkTo kind="Design System/Components/Sheet/展示" name="右側建立 專案"><span className="text-primary hover:underline font-medium cursor-pointer">右側建立 專案</span></LinkTo>
+          <LinkTo kind="Design System/Components/Sheet/展示" name="建立新專案（右側滑入）"><span className="text-primary hover:underline font-medium cursor-pointer">建立新專案（右側滑入）</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Sheet/展示" name="右側編輯 使用者 詳情"><span className="text-primary hover:underline font-medium cursor-pointer">右側編輯 使用者 詳情</span></LinkTo>
+          <LinkTo kind="Design System/Components/Sheet/展示" name="編輯成員詳情（右側滑入）"><span className="text-primary hover:underline font-medium cursor-pointer">編輯成員詳情（右側滑入）</span></LinkTo>
         </li>
       </ul>
       <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>
@@ -99,10 +99,9 @@ export const UsageGuidance: Story = {
               <SheetTitle>專案設定</SheetTitle>
               <SheetDescription>修改此專案的基本資訊與通知偏好</SheetDescription>
             </SheetHeader>
-            {/* Overlay body 長內容必用 ScrollArea 而非 native overflow-y-auto,對齊 DS
-                跨 OS 一致設計準則(避免 Windows/Linux 右側被吃 15-17px)。 */}
-            <ScrollArea className="flex-1">
-              <div className="py-4 flex flex-col gap-4">
+            {/* Body 必用 SheetBody(內建 ScrollArea + 浮層 padding SSOT px-loose/pt-tight/pb-bottom);
+                自組 ScrollArea + py-4 = 水平 0 padding 歷史 bug,詳 sheet.tsx SheetBody comment。 */}
+            <SheetBody className="flex flex-col gap-4">
                 <Field>
                   <FieldLabel>名稱</FieldLabel>
                   <Input defaultValue="產品路線圖" />
@@ -118,8 +117,7 @@ export const UsageGuidance: Story = {
                     <Checkbox label="每日摘要" />
                   </div>
                 </Field>
-              </div>
-            </ScrollArea>
+            </SheetBody>
             <SheetFooter>
               <SheetClose asChild>
                 <Button variant="tertiary">取消</Button>
@@ -163,28 +161,12 @@ export const UsageGuidance: Story = {
         <Label>Dialog:刪除確認、放棄變更、登入、付款確認</Label>
       </Rule>
 
-      {/* 何時不用 / 替代元件 — 原 WhenNotSheetRule */}
+      {/* 何時不用 / 替代元件 — 原 WhenNotSheetRule。
+          短確認 → Dialog 的完整 live 對照已在上方「Dialog — 居中 modal」段示範,此處不重複(2026-06-11 精簡)。 */}
       <Rule
         title="何時不用 / 替代元件 — 短確認 / 不可逆動作 → Dialog"
-        note="「刪除 / 登出 / 放棄變更」這類要使用者完全停下做決定的場景,用 Dialog 的居中 modal 強制聚焦。Sheet 側滑視覺不夠強,使用者可能點旁邊就跳過"
+        note="「刪除 / 登出 / 放棄變更」這類要使用者完全停下做決定的場景,用 Dialog 的居中 modal 強制聚焦。Sheet 側滑視覺不夠強,使用者可能點旁邊就跳過(live 對照見上方「Dialog — 居中 modal」段)"
       >
-        <Dialog>
-          <DialogTrigger asChild>
-            <Button variant="primary" danger startIcon={Trash2}>刪除帳號</Button>
-          </DialogTrigger>
-          <DialogContent autoHeight maxWidth="420px">
-            <DialogHeader>
-              <DialogTitle>確定要刪除帳號?</DialogTitle>
-            </DialogHeader>
-            <DialogBody>
-              <p className="text-body">所有資料將於 30 天後永久移除,此動作無法復原。</p>
-            </DialogBody>
-            <DialogFooter>
-              <Button variant="tertiary">取消</Button>
-              <Button variant="primary" danger>確認刪除</Button>
-            </DialogFooter>
-          </DialogContent>
-        </Dialog>
         <Label>↑ 短決策應該用 Dialog(Sheet 太長太輕)</Label>
       </Rule>
 
@@ -243,9 +225,9 @@ export const SidePropRule: Story = {
               <SheetTitle>任務詳情</SheetTitle>
               <SheetDescription>#PROJ-234 · 指派給Ada Chen</SheetDescription>
             </SheetHeader>
-            <div className="flex-1 py-4 text-body text-fg-secondary">
+            <SheetBody className="text-body text-fg-secondary">
               登入頁在連續輸入錯誤密碼 3 次後未顯示鎖定提示,使用者反覆嘗試仍無回饋。建議補上鎖定倒數與重設連結。
-            </div>
+            </SheetBody>
           </SheetContent>
         </Sheet>
         <Label>↑ 列表點 row → 右側滑入編輯,左側列表仍可見</Label>
@@ -287,13 +269,13 @@ export const SidePropRule: Story = {
             <SheetHeader>
               <SheetTitle>分享</SheetTitle>
             </SheetHeader>
-            <div className="flex-1 py-4 flex flex-col gap-2">
+            <SheetBody className="flex flex-col gap-2">
               {['複製連結', '傳送到 Email', '加入我的最愛', '匯出 PDF'].map(name => (
                 <button key={name} type="button" className="px-3 py-2 text-body text-left hover:bg-neutral-hover rounded-md">
                   {name}
                 </button>
               ))}
-            </div>
+            </SheetBody>
           </SheetContent>
         </Sheet>
         <Label>↑ 手機拇指操作區 → bottom Sheet</Label>
@@ -322,7 +304,7 @@ export const HeaderFooterStructureRule: Story = {
     <div>
       <Rule
         title="標準結構 — Header(標題 + 描述) + 主內容 + Footer(按鈕列)"
-        note="與 Dialog 共用 overlay-surface 視覺語言(bg-surface-raised / elevation-200;容器邊框用較淡的 border-divider,Dialog 用 border-border)。Header 放 SheetTitle + SheetDescription,Footer 放按鈕列;主內容區 flex-1 + ScrollArea(跨 OS 一致捲軸,非 native overflow-y-auto)吃長內容"
+        note="與 Dialog 共用 overlay-surface 視覺語言(bg-surface-raised / elevation-200;容器邊框用較淡的 border-divider,Dialog 用 border-border)。Header 放 SheetTitle + SheetDescription,Footer 放按鈕列;主內容區用 SheetBody(內建 ScrollArea 跨 OS 一致捲軸 + 浮層 padding SSOT)吃長內容"
       >
         <Sheet>
           <SheetTrigger asChild>
@@ -333,9 +315,8 @@ export const HeaderFooterStructureRule: Story = {
               <SheetTitle>建立新客戶</SheetTitle>
               <SheetDescription>填寫基本資料後可進行付款設定</SheetDescription>
             </SheetHeader>
-            {/* Overlay body 長內容必用 ScrollArea,對齊 DS 跨 OS 一致 canonical */}
-            <ScrollArea className="flex-1">
-              <div className="py-4 flex flex-col gap-4">
+            {/* Body 必用 SheetBody(內建 ScrollArea + 浮層 padding SSOT) */}
+            <SheetBody className="flex flex-col gap-4">
                 <Field>
                   <FieldLabel>公司名稱</FieldLabel>
                   <Input placeholder="輸入公司名稱" />
@@ -344,8 +325,7 @@ export const HeaderFooterStructureRule: Story = {
                   <FieldLabel>聯絡人 Email</FieldLabel>
                   <Input placeholder="contact@example.com" />
                 </Field>
-              </div>
-            </ScrollArea>
+            </SheetBody>
             <SheetFooter>
               <SheetClose asChild>
                 <Button variant="tertiary">取消</Button>