@qijenchen/design-system 0.1.0-beta.85 → 0.1.0-beta.86

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

@@ -73,7 +73,7 @@ const MultiSelectDemo = () => {
   return (
     <div className="flex flex-col gap-4 max-w-sm">
       <p className="text-caption text-fg-muted">Combobox — checkbox 多選，浮層不關閉</p>
-      <Combobox options={categoryOptions} value={value} onChange={setValue} />
+      <Combobox options={categoryOptions} value={value} onChange={setValue} aria-label="商品分類(SelectMenu multi-select demo)" />
     </div>
   )
 }
@@ -90,7 +90,7 @@ const MultiSearchDemo = () => {
   return (
     <div className="flex flex-col gap-4 max-w-sm">
       <p className="text-caption text-fg-muted">searchable — 浮層內搜尋框，關鍵字保留可連續勾選</p>
-      <Combobox options={countries} value={value} onChange={setValue} searchable />
+      <Combobox options={countries} value={value} onChange={setValue} searchable aria-label="國家(SelectMenu multi-select + search demo)" />
     </div>
   )
 }
@@ -100,23 +100,11 @@ export const MultiSearchable: StoryObj = {
   render: () => <MultiSearchDemo />,
 }
 
-// ── 可清除 ──
-
-const ClearableDemo = () => {
-  const [value, setValue] = useState<string>('in_stock')
-  return (
-    <div className="flex flex-col gap-4 max-w-xs">
-      <p className="text-caption text-fg-muted">clearable — 有值時右側出現清除按鈕</p>
-      <Select options={statusOptions} value={value} onChange={setValue} clearable />
-    </div>
-  )
-}
-
-export const Clearable: StoryObj = {
-  name: '可清除',
-  render: () => <ClearableDemo />,
-}
-
+// @story-trait-rationale: 原 Clearable(可清除)retired 2026-07-17(Dim 25 earn-existence)—
+//   該 story 實際 render `<Select clearable>`,clearable 是 Select trigger/field state 的 API(spec
+//   L45/L53/L160 明定 trigger state 由外層 Select/Combobox own,SelectMenu 本身無此 prop),
+//   且 Select.stories.tsx「可清除」已 own 此 canonical。SelectMenu 展示層只保留浮層自身能力
+//   (搜尋 / 多選 / creatable / 選項狀態),不重演 wrapper 的 field feature。principles 頁對應 LinkTo 同步移除。
 // @story-trait-rationale: AllSizes retired per F migration 2026-05-15 — anatomy.stories.tsx SizeMatrix auto-compile owns size showcase。
 // @story-trait-rationale: 原 States(edit/readonly/disabled/error 觸發器狀態)retired 2026-06-11 —
 //   trigger field state 由 Select.stories.tsx「四模式」owns(SelectMenu 是 internal popover surface,

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

@@ -31,7 +31,7 @@ import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
  * ── 架構 ──
  *   Popover（浮動容器）
  *     └── Command（cmdk，搜尋 + 鍵盤導覽）
- *           ├── CommandInput（搜尋框）
+ *           ├── CommandPrimitive.Input（搜尋框,raw cmdk + 自建 icon/min-h wrapper,非 DS CommandInput）
  *           ├── CommandList（選項列表）
  *           │     └── CommandGroup → MenuItem
  *           └── Footer（多選全選）
@@ -81,6 +81,15 @@ export interface SelectMenuProps {
   onCreate?: (value: string) => void
   /** creatable 的 label 格式，預設 '直接使用「{query}」' */
   createLabel?: (query: string) => string
+  /**
+   * 受控搜尋字串(2026-07-18 決策11:讓 consumer 用**外部搜尋**(如 Select 的 trigger 內嵌 input)
+   * 驅動 creatable create-row 顯隱)。傳入 = 受控(SelectMenu 不自管 search、close 不 reset,由
+   * parent 負責);不傳 = 內部 uncontrolled(既有行為,零影響)。搭配 `searchable=false` +
+   * `creatable` 時,SelectMenu 不畫自己的 input,但 create-row 仍依此 search 顯示。
+   */
+  search?: string
+  /** 受控搜尋變更通知(選配;SelectMenu 內部無 input 時通常由 parent 單向驅動,不需此) */
+  onSearchChange?: (value: string) => void
 
   /** 觸發元件（asChild） */
   children: React.ReactNode
@@ -126,6 +135,14 @@ export interface SelectMenuProps {
    */
   contentId?: string
 
+  /**
+   * 浮層 accessible name(2026-07-17 Dim 10 a11y 修)。Radix Popover 的 content 為
+   * `role="dialog"` 但無自動命名機制 → 無 aria-label 時 dialog 無 accessible name。
+   * 預設「選項清單」讓 SR 使用者知道浮層用途;consumer(Combobox / Select / PeoplePicker)
+   * 可傳更 contextual 的名(如欄位名)。SSOT 放此一處 → 全 SelectMenu consumer 受益。
+   */
+  'aria-label'?: string
+
   className?: string
 }
 
@@ -162,6 +179,8 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
   creatable = false,
   onCreate,
   createLabel = (q) => `直接使用「${q}」`,
+  search: controlledSearch,
+  onSearchChange,
   children,
   searchPlaceholder = '搜尋…', // i18n-allow: DS default; consumer override via searchPlaceholder prop
   emptyText = '沒有符合的選項', // i18n-allow: DS default; consumer override via emptyText prop
@@ -177,6 +196,7 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
   renderLabel,
   onOpenAutoFocus,
   contentId,
+  'aria-label': ariaLabel = '選項清單', // i18n-allow: DS default; consumer override via aria-label prop
   className,
 }, _ref) {
   // ── State ──
@@ -189,7 +209,18 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
     defaultValue: defaultOpen ?? false,
     onChange: controlledOnOpenChange,
   })
-  const [search, setSearch] = React.useState('')
+  // search:選配受控(決策11)。傳 `search` prop = 受控(parent 驅動,如 Select trigger input);
+  // 不傳 = 內部 uncontrolled(既有行為)。setSearch 同步內部 + 通知 onSearchChange。
+  const isSearchControlled = controlledSearch !== undefined
+  const [internalSearch, setInternalSearch] = React.useState('')
+  const search = isSearchControlled ? controlledSearch : internalSearch
+  const setSearch = React.useCallback(
+    (next: string) => {
+      if (!isSearchControlled) setInternalSearch(next)
+      onSearchChange?.(next)
+    },
+    [isSearchControlled, onSearchChange],
+  )
 
   // ── Value helpers ──
   const selectedValues = React.useMemo<string[]>(() => {
@@ -279,10 +310,10 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
     return grouped
   }, [groups, options])
 
-  // ── Reset search on close ──
+  // ── Reset search on close(僅 uncontrolled;受控時由 parent 負責 reset)──
   React.useEffect(() => {
-    if (!open) setSearch('')
-  }, [open])
+    if (!open && !isSearchControlled) setInternalSearch('')
+  }, [open, isSearchControlled])
 
   // 2026-06-01 Select/Combobox #15(user 拍板 A):非搜尋時開選單把 focus 移到 cmdk-root,
   // 讓 cmdk 內建方向鍵 / Enter / Home / End 導覽生效。原 PopoverContent default autofocus 找 body
@@ -307,6 +338,8 @@ const SelectMenu = React.forwardRef<HTMLElement, SelectMenuProps>(function Selec
       <RowSizeProvider value={size}>
       <PopoverContent
         id={contentId}
+        // 2026-07-17 Dim 10 a11y 修:role="dialog" 浮層 accessible name(Radix Popover 無自動命名)
+        aria-label={ariaLabel}
         // w-auto override PopoverContent default w-72(rich-popover canonical)— SelectMenu 走「跟 trigger 同寬」
         // canonical(spec L72)。minWidth = max(trigger-width, 240px sensible-min)— 對齊 shadcn / Material / Ant
         // select dropdown 共識(2026-05-04 D1 verify SelectMenu spec implementation)。

package/src/components/SelectionControl/boolean-value.tsx

@@ -1,4 +1,4 @@
-// @internal — boolean 值展示符號 SSOT(display / readonly 態);consumer 用 Checkbox / Switch 不直用。
+// @internal — boolean 值展示符號 SSOT(view / readonly 態);consumer 用 Checkbox / Switch 不直用。
 // ── 消費的 SSOT ──
 // - lucide-react Check / X(DS icon canonical:成功/勾 = Check、關閉/否 = X,見 ui-development.md「Icon canonical」)
 // - components/Field/field-context.ts(FieldSize 型別 → icon 尺寸對齊 value 文字)
@@ -23,7 +23,7 @@ const booleanIconSize: Record<FieldSize, string> = {
 
 /**
  * BooleanValueIcon — boolean 值的展示符號(true = Check 勾 / false = X 叉),中性 `text-foreground` 色。
- * Checkbox / Switch 的 display + readonly 態、DataTable boolean cell(經 Checkbox)全消費此 SSOT。
+ * Checkbox / Switch 的 view + readonly 態、DataTable boolean cell(經 Checkbox)全消費此 SSOT。
  */
 export function BooleanValueIcon({
   checked,

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

@@ -192,7 +192,7 @@ export const Overview: Story = {
                 <Td mono>disabled</Td>
                 <Td mono>boolean</Td>
                 <Td mono>false</Td>
-                <Td>label / description / icon → text-fg-disabled(M24);label 另加 cursor-not-allowed</Td>
+                <Td>label / description / icon 全轉 text-fg-disabled（disabled 狀態優先於 muted 裝飾色）；label 另加 cursor-not-allowed</Td>
               </tr>
               <tr>
                 <Td mono>htmlFor</Td>

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

@@ -9,7 +9,7 @@ const meta: Meta = {
 export default meta
 type Story = StoryObj
 
-// ── WhenToUse — 何時使用 SelectionControl ──────────────────────
+// ── WhenToUse — 何時使用 SelectionItem ──────────────────────
 
 
 // ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
@@ -21,7 +21,7 @@ export const UsageGuidance: Story = {
     <div className="flex flex-col gap-12">
       {/* 何時用 — 原 WhenToUse */}
       <div className="prose prose-sm max-w-prose">
-      <p>適合 SelectionControl 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <p>適合 SelectionItem 的真實業務場景(點擊跳轉「展示」頁範例):</p>
       <ul className="space-y-1">
         <li>
           <LinkTo kind="Design System/Internal/SelectionControl/展示" name="通知偏好"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">通知偏好</span></LinkTo>
@@ -36,14 +36,14 @@ export const UsageGuidance: Story = {
           <LinkTo kind="Design System/Internal/SelectionControl/展示" name="前綴頭像"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">前綴頭像</span></LinkTo>
         </li>
       </ul>
-      <p className="text-fg-muted mt-3">判斷不確定時,參考下方「SelectionControl 與 Checkbox + Field 的差異」說明;若場景不符,改用對應的近親元件。</p>
+      <p className="text-fg-muted mt-3">判斷不確定時,參考下方「SelectionItem 與 Checkbox + Field 的差異」說明;若場景不符,改用對應的近親元件。</p>
     </div>
 
       {/* vs 近親 — VsCheckboxRule — 原 VsCheckboxRule */}
       <div className="prose prose-sm max-w-prose">
       <p>兩者表達 selectable state,但結構與場景不同:</p>
       <ul>
-        <li><strong>SelectionControl rich row(本 primitive,經 Checkbox / RadioGroup 消費)</strong>—大塊 row(含 icon / avatar / multi-line description),適合 settings / list-as-page;Notion/Slack idiom</li>
+        <li><strong>SelectionItem rich row(本 primitive,經 Checkbox / RadioGroup 消費)</strong>—大塊 row(含 icon / avatar / multi-line description),適合 settings / list-as-page;Notion/Slack idiom</li>
         <li><strong>Checkbox + Field</strong>—緊湊 form 欄位;適合 form group 多選</li>
       </ul>
       <p className="text-fg-muted">判斷:row 是 page content(讀取/設定)→ Checkbox / RadioGroup 的 rich-row 形態(內部消費 SelectionItem,不裸用 &lt;SelectionItem&gt;);row 是 form input(submit value)→ Checkbox + Field。</p>

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

@@ -60,7 +60,7 @@ export const UsageGuidance: Story = {
           <LinkTo kind="Design System/Components/Separator/展示" name="垂直"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">垂直分隔</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Separator/展示" name="在 DropdownMenu 內"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">在 DropdownMenu 內</span></LinkTo>
+          <LinkTo kind="Design System/Components/DropdownMenu/展示" name="基本"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">在 DropdownMenu 內(DropdownMenuSeparator,見 DropdownMenu 展示「基本」)</span></LinkTo>
         </li>
         <li>
           <LinkTo kind="Design System/Components/Separator/展示" name="在 DescriptionList 區塊之間"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">在 DescriptionList 區塊之間</span></LinkTo>

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

@@ -1,4 +1,5 @@
 // @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+// @overlay-open-skip: 本檔為 usage-guidance(設計原則)story——每個 Rule 卡片以「關閉的 trigger 按鈕」並排比較 Sheet / Dialog / Popover 何時用;全部 defaultOpen 會讓多個 portal 疊在一起、視覺全毀。overlay 開啟狀態的視覺覆蓋由 sheet.stories.tsx(展示)+ sheet.anatomy.stories.tsx(Inspector defaultOpen)負責。
 import React from 'react'
 import LinkTo from '@storybook/addon-links/react'
 import type { Meta, StoryObj } from '@storybook/react'
@@ -179,7 +180,8 @@ export const UsageGuidance: Story = {
           <PopoverTrigger asChild>
             <Button variant="tertiary" startIcon={Filter}>篩選</Button>
           </PopoverTrigger>
-          <PopoverContent align="start">
+          {/* naked popover(無 PopoverTitle)→ 自傳 aria-label 讓 role="dialog" 有 accessible name(popover.spec.md A11y) */}
+          <PopoverContent align="start" aria-label="依狀態篩選">
             <PopoverBody>
               <CheckboxGroup>
                 <Checkbox defaultChecked label="進行中" />
@@ -264,7 +266,7 @@ export const SidePropRule: Story = {
       >
         <Sheet>
           <SheetTrigger asChild>
-            <Button variant="tertiary">分享選項(mobile 常用 bottom)</Button>
+            <Button variant="tertiary">分享</Button>
           </SheetTrigger>
           <SheetContent side="bottom" className="max-w-full">
             <SheetHeader>
@@ -309,7 +311,7 @@ export const HeaderFooterStructureRule: Story = {
       >
         <Sheet>
           <SheetTrigger asChild>
-            <Button variant="tertiary">標準結構範例</Button>
+            <Button variant="tertiary">建立新客戶</Button>
           </SheetTrigger>
           <SheetContent side="right" className="flex flex-col sm:max-w-lg">
             <SheetHeader>

package/src/components/Sheet/sheet.tsx

@@ -88,8 +88,11 @@ const sheetVariants = cva(
   }
 )
 
+// asChild Omit(2026-07-18 決策2):SheetContent 是固定 edge-anchored surface(overlay + sheetVariants
+// 定位/slide 動畫 + onOpenAutoFocus),恆渲染 {children}(consumer body 多節點)→ <Content asChild>
+// Radix Slot React.Children.only crash。children 保留(consumer body)。同 Dialog 收窄。
 interface SheetContentProps
-  extends React.ComponentPropsWithoutRef<typeof SheetPrimitive.Content>,
+  extends Omit<React.ComponentPropsWithoutRef<typeof SheetPrimitive.Content>, 'asChild'>,
     VariantProps<typeof sheetVariants> {}
 
 // AutoFocus canonical(對齊 Dialog / Material / Polaris)— 見 dialog.tsx handleOpenAutoFocus 註解

package/src/components/Sidebar/sidebar.tsx

@@ -1286,7 +1286,7 @@ SidebarMenuSkeleton.displayName = "SidebarMenuSkeleton"
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const sidebarMeta = {
   component: 'Sidebar',
-  family: null, // non-family composite / overlay / layout
+  family: 1, // Family 1(Menu item layout)消費者 — 對齊 sidebar.spec.md frontmatter family: 1(SidebarMenuButton rows 消費 item-anatomy;同 tree-view.tsx 慣例)
   variants: {
     default: { when: '標準導覽 row,參與 single-selection' },
     meta: { when: 'Section 底部命令 row(Show more / 新增),不參與 selection' },

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

@@ -62,6 +62,7 @@ export const Inspector: Story = {
     docs: { description: { story: '右側 Controls 切 props 即時 render,取代 Figma inspect。調整 `min` / `max` / `step` / `defaultValue` 看值域行為,切 `size` 看容器高度 tier(track / thumb 視覺固定)。' } },
   },
   args: {
+    'aria-label': '音量',
     defaultValue: [60],
     min: 0,
     max: 100,
@@ -130,7 +131,7 @@ export const SizeMatrix: Story = {
           {(['sm', 'md', 'lg'] as const).map(size => (
             <div key={size} className="flex items-center gap-3 border border-dashed border-divider rounded-md p-3">
               <span className="text-caption text-fg-muted font-mono w-8">{size}</span>
-              <Slider size={size} defaultValue={[50]} className="flex-1" />
+              <Slider size={size} defaultValue={[50]} aria-label="音量" className="flex-1" />
             </div>
           ))}
         </div>
@@ -149,15 +150,15 @@ export const StateBehavior: Story = {
         <div className="flex flex-col gap-3">
           <div className="border border-dashed border-divider rounded-md p-3">
             <div className="text-caption text-fg-muted mb-2">Default</div>
-            <Slider defaultValue={[50]} />
+            <Slider defaultValue={[50]} aria-label="音量" />
           </div>
           <div className="border border-dashed border-divider rounded-md p-3">
             <div className="text-caption text-fg-muted mb-2">Disabled</div>
-            <Slider defaultValue={[50]} disabled />
+            <Slider defaultValue={[50]} disabled aria-label="音量" />
           </div>
           <div className="border border-dashed border-divider rounded-md p-3">
             <div className="text-caption text-fg-muted mb-2">Range + Disabled</div>
-            <Slider defaultValue={[20, 80]} disabled />
+            <Slider defaultValue={[20, 80]} disabled aria-label="價格區間" />
           </div>
         </div>
       </div>

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

@@ -65,7 +65,7 @@ export const UsageGuidance: Story = {
         >
           <div className="flex items-center gap-3">
             <span className="text-body w-12">音量</span>
-            <Slider value={volume} onValueChange={setVolume} className="flex-1" />
+            <Slider value={volume} onValueChange={setVolume} aria-label="音量" className="flex-1" />
             <span className="text-caption text-fg-muted font-mono w-10">{volume[0]}%</span>
           </div>
         </Rule>
@@ -76,7 +76,7 @@ export const UsageGuidance: Story = {
         >
           <div className="flex items-center gap-3">
             <span className="text-body w-12">價格</span>
-            <Slider value={price} onValueChange={setPrice} min={0} max={10000} step={100} className="flex-1" />
+            <Slider value={price} onValueChange={setPrice} min={0} max={10000} step={100} aria-label="價格範圍" className="flex-1" />
             <span className="text-caption text-fg-muted font-mono w-24">${price[0]} - ${price[1]}</span>
           </div>
         </Rule>
@@ -87,7 +87,7 @@ export const UsageGuidance: Story = {
         >
           <div className="flex items-center gap-3">
             <span className="text-body w-12">大小</span>
-            <Slider defaultValue={[50]} step={50} min={0} max={100} className="flex-1" />
+            <Slider defaultValue={[50]} step={50} min={0} max={100} aria-label="大小" className="flex-1" />
             <span className="text-caption text-fg-muted font-mono w-10">中</span>
           </div>
           <Label warn>↑ 強制拖到 0 / 50 / 100 的 Slider = 反模式。改 SegmentedControl:</Label>
@@ -135,13 +135,13 @@ export const PositionAsStateRule: Story = {
         <div className="flex items-center gap-4">
           <div className="flex-1">
             <div className="text-caption text-fg-muted mb-1">Rest(primary)</div>
-            <Slider defaultValue={[60]} />
+            <Slider defaultValue={[60]} aria-label="亮度" />
           </div>
         </div>
         <div className="flex items-center gap-4">
           <div className="flex-1">
             <div className="text-caption text-fg-muted mb-1">Disabled(灰階——位置/長度完全可辨)</div>
-            <Slider defaultValue={[60]} disabled />
+            <Slider defaultValue={[60]} disabled aria-label="亮度" />
           </div>
         </div>
         <Label>↑ 灰階後 thumb 位置(60%)+ range 填滿長度(0-60%)仍然清楚。不需要保留藍色</Label>
@@ -194,7 +194,7 @@ export const HoverUsesShadowRule: Story = {
       >
         <div>
           <div className="text-caption text-fg-muted mb-1">Hover thumb → 陰影 elevation-100</div>
-          <Slider defaultValue={[50]} />
+          <Slider defaultValue={[50]} aria-label="音量" />
         </div>
         <Label>↑ hover 時 thumb 加 elevation-100,不改底色。對齊 Material 3 / iOS / Linear 共識</Label>
       </Rule>

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

@@ -129,11 +129,13 @@ Slider 不是 button——它是「當前位置指示器」,底色不該動(動
   step={number}                    // 預設 1
   size="sm" | "md" | "lg"          // 預設 md(只影響容器外高)
   disabled={boolean}
-  orientation="horizontal"         // 不支援 vertical(DS 尚無垂直變體;未來真有需求再擴充)
   minStepsBetweenThumbs={number}   // range mode 時兩個 thumb 的最小距離
 />
 ```
 
+- **不支援 vertical**:`orientation` 已自型別排除(`slider.tsx` `Omit<..., 'orientation'>`);DS 尚無垂直變體,未來真有需求再擴充。
+- **`value` / `defaultValue` 必為非空陣列**:至少一個元素(`[single]` 或 `[min, max]` range)。傳空陣列 `[]` 時 Radix 無對應值會隱藏 thumb,留下沒有可操作 thumb 的空軌道 → `slider.tsx` 正規化為 `[min]`(`min` 未傳時為 `0`),保證至少一個坐落在 `min` 的可操作 thumb。省略值(不傳 `value` / `defaultValue`)時走 Radix 預設單 thumb。
+
 ### Range mode(雙 thumb)
 
 Radix Slider 原生支援多 thumb——只要 `value` / `defaultValue` 傳長度 > 1 的 array,就自動渲染對應數量的 thumb,range(填滿段)落在最小和最大 thumb 之間。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
@@ -214,6 +216,10 @@ Disabled slider 要傳達的兩件事——thumb 位置、range 長度——**
 
 Slider 沒有獨立的 error 視覺——拖曳選值本身不太會「無效」。如果業務邏輯需要限制範圍,用 `min` / `max` 直接限制使用者能拖到的範圍,不要讓他拖到再報錯。
 
+### 無 Loading state(N/A)
+
+Slider 是**同步輸入 primitive**,thumb 上不加 spinner。值本身即為當前狀態,沒有「載入中的值」這種中間態。若資料尚未就緒(例如初始範圍要等 API 回),loading 由父層或 `Field` 擁有(在 Field 層顯示 skeleton / spinner),Slider 本身只在值到位後渲染——不在 thumb / track 疊加載入視覺。
+
 ### Readonly(僅 Field cascade,無獨立 prop)
 
 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 元件。
@@ -278,6 +284,12 @@ Inspector 提供 `min` / `max` / `step` / `defaultValue` × `size` 即時調整(
 
 **ARIA / Pattern**:繼承 Radix `slider` primitive a11y 預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/slider#accessibility)。
 
+**Accessible name(命名,強制)**:`role="slider"` 的 thumb **必須有 accessible name**,否則螢幕閱讀器只讀出數值、不知這是「什麼」的值。Radix 對**單 thumb 不會自動產生名稱**(只有 2+ thumb 才給 Minimum / Maximum 泛稱)。命名三層(`slider.tsx` 已實作,由高到低優先):
+
+1. **consumer `aria-label`**:standalone(不在 Field 內)的 Slider **必傳** `aria-label`(例:`<Slider aria-label="音量" />`);多 thumb 時自動展開為 `{label} (1)` / `{label} (2)` 區分各 thumb。
+2. **Field 自動接線**:包在 `<Field>` 內且未傳 `aria-label` 時,thumb 自動 `aria-labelledby` 接 `FieldLabel`(元件讀 `fieldCtx.labelId`)——此情境不需另傳 `aria-label`。
+3. **Radix fallback**:兩者皆無時,2+ thumb 由 Radix 提供 Minimum / Maximum 泛稱;單 thumb 則**無名稱**(= 需靠上面兩層補)。
+
 **Keyboard 行為**:完整鍵盤對照見上方「鍵盤操作(Radix 原生,免手工)」節,不重複列。
 
 **Focus**:Radix primitive 自管 focus / restoration;thumb 鍵盤聚焦時 `outline-none focus-visible:border-primary-hover`(border 升 hover 階,跟 hover 同視覺,不加 ring / halo)。

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

@@ -2,6 +2,7 @@
 import * as React from 'react'
 import type { Meta, StoryObj } from '@storybook/react'
 import { Slider } from './slider'
+import { NumberInput } from '@/design-system/components/NumberInput/number-input'
 
 const meta: Meta<typeof Slider> = {
   title: 'Design System/Components/Slider/展示',
@@ -21,19 +22,19 @@ type Story = StoryObj<typeof Slider>
 export const SizeAlignment: Story = {
   name: '容器尺寸對齊',
   render: () => (
-    <div className="w-[360px] flex flex-col gap-6">
+    <div className="w-[420px] flex flex-col gap-6">
       <p className="text-caption text-fg-secondary max-w-[480px]">
         三個 size 下 track 厚度與 thumb 直徑一致——只有容器外高跟著
-        `--field-height-*` 變。這讓 Slider 能在 Field 內跟 Input / Select /
-        NumberInput 並排對齊,同時保持自己的視覺身分不變。
+        `--field-height-*` 變。這讓 Slider 能在同一列跟 NumberInput 等 field
+        控件並排、field-height 完美對齊,同時保持自己的視覺身分不變。
       </p>
       {(['sm', 'md', 'lg'] as const).map(size => (
         <div key={size} className="flex flex-col gap-2">
-          <div className="text-caption text-fg-muted">
-            size = {size}(h-field-{size})
-          </div>
-          <div className="border border-dashed border-border rounded-md p-0">
-            <Slider size={size} defaultValue={[40]} />
+          <div className="text-caption text-fg-muted">size = {size}</div>
+          <div className="flex items-center gap-3">
+            <span className="text-body w-10 shrink-0">音量</span>
+            <Slider size={size} defaultValue={[40]} aria-label="音量" className="flex-1" />
+            <NumberInput size={size} value={40} onChange={() => {}} className="w-20 shrink-0" />
           </div>
         </div>
       ))}
@@ -46,20 +47,25 @@ export const SizeAlignment: Story = {
 export const MinMaxStep: Story = {
   name: '最小 / 最大 / 步階',
   render: () => {
-    const [value, setValue] = React.useState([32])
+    const [quality, setQuality] = React.useState([80])
     return (
       <div className="w-[360px] flex flex-col gap-4">
-        <div className="text-caption text-fg-muted">
-          min=0, max=100, step=4
+        <p className="text-caption text-fg-secondary">
+          匯出圖片品質——限制在 10–100% 之間,每次以 5% 為一階(min / max / step)
+        </p>
+        <div className="flex items-center gap-3">
+          <span className="text-body w-16 shrink-0">圖片品質</span>
+          <Slider
+            value={quality}
+            onValueChange={setQuality}
+            min={10}
+            max={100}
+            step={5}
+            aria-label="匯出圖片品質"
+            className="flex-1"
+          />
+          <span className="text-caption text-fg-muted font-mono w-10 shrink-0">{quality[0]}%</span>
         </div>
-        <Slider
-          value={value}
-          onValueChange={setValue}
-          min={0}
-          max={100}
-          step={4}
-        />
-        <p className="text-caption text-fg-secondary">Value: {value[0]}</p>
       </div>
     )
   },
@@ -74,24 +80,30 @@ export const MinMaxStep: Story = {
 export const OnCommit: Story = {
   name: '提交數值回呼',
   render: () => {
-    const [live, setLive] = React.useState([50])
-    const [committed, setCommitted] = React.useState([50])
+    const [preview, setPreview] = React.useState([3000])
+    const [applied, setApplied] = React.useState([3000])
     return (
       <div className="w-[360px] flex flex-col gap-4">
         <p className="text-caption text-fg-secondary">
-          拖曳時 live 跟著變,放開才更新 committed(適合昂貴操作如 API
-          query、圖片重繪)
+          價格上限篩選——拖曳時即時預覽,放開才送出查詢(適合昂貴操作如 API
+          query、重新載入結果)
         </p>
-        <Slider
-          value={live}
-          onValueChange={setLive}
-          onValueCommit={setCommitted}
-        />
+        <div className="flex items-center gap-3">
+          <span className="text-body w-12 shrink-0">價格</span>
+          <Slider
+            value={preview}
+            onValueChange={setPreview}
+            onValueCommit={setApplied}
+            min={0}
+            max={10000}
+            step={100}
+            aria-label="價格上限"
+            className="flex-1"
+          />
+        </div>
         <div className="flex flex-col gap-1 text-caption">
-          <span className="text-fg-secondary">Live: {live[0]}</span>
-          <span className="text-foreground font-medium">
-            Committed: {committed[0]}
-          </span>
+          <span className="text-fg-secondary">即時預覽:${preview[0]}</span>
+          <span className="text-foreground font-medium">已套用查詢:${applied[0]}</span>
         </div>
       </div>
     )

package/src/components/Slider/slider.tsx

@@ -70,18 +70,27 @@ const Slider = React.forwardRef<
   // 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
+  // Degenerate-input 硬化(2026-07 deep-audit d7i20 / d8i7):value / defaultValue 傳空陣列
+  // 時,Radix 無對應值 → thumb display:none,留下沒有可操作 thumb 的空軌道。正規化為 `[min]`
+  // (min 未傳時 Radix 預設 0),保證至少一個坐落在 min 的可操作 thumb —— 對齊 spec API
+  //「value / defaultValue 必為非空陣列」契約,且不影響任何有效輸入。
+  const minValue = (props as { min?: number }).min ?? 0
+  const safeValue =
+    Array.isArray(value) && value.length === 0 ? [minValue] : value
+  const safeDefaultValue =
+    Array.isArray(defaultValue) && defaultValue.length === 0 ? [minValue] : defaultValue
   // 推導要渲染幾個 thumb:controlled 用 value,uncontrolled 用 defaultValue,
   // 都沒有時 fallback 單 thumb(Radix 預設行為)
   const thumbCount =
-    (Array.isArray(value) && value.length) ||
-    (Array.isArray(defaultValue) && defaultValue.length) ||
+    (Array.isArray(safeValue) && safeValue.length) ||
+    (Array.isArray(safeDefaultValue) && safeDefaultValue.length) ||
     1
 
   return (
     <SliderPrimitive.Root
       ref={ref}
-      value={value}
-      defaultValue={defaultValue}
+      value={safeValue}
+      defaultValue={safeDefaultValue}
       className={cn(sliderRootVariants({ size }), fieldReadonly && 'pointer-events-none', className)}
       {...props}
       disabled={(props as { disabled?: boolean }).disabled || fieldDisabled}

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

@@ -251,9 +251,9 @@ export const SizeMatrix: Story = {
             <div key={size} className="border border-dashed border-divider rounded-md p-4">
               <div className="text-caption text-fg-muted mb-2 font-mono">size="{size}"</div>
               <Steps size={size} value="b" completedValues={['a']}>
-                <StepItem value="a"><StepLabel>第一步</StepLabel></StepItem>
-                <StepItem value="b"><StepLabel>第二步</StepLabel></StepItem>
-                <StepItem value="c"><StepLabel>第三步</StepLabel></StepItem>
+                <StepItem value="a"><StepLabel>填寫資料</StepLabel></StepItem>
+                <StepItem value="b"><StepLabel>確認訂單</StepLabel></StepItem>
+                <StepItem value="c"><StepLabel>完成付款</StepLabel></StepItem>
               </Steps>
             </div>
           ))}
@@ -421,12 +421,12 @@ export const IndentAlignment: Story = {
         <Desc>**刻意打破 item-layout 的 24px 閾值規則**——不管 indicator 尺寸、不管有無 description,一律 inline 對齊。Column rhythm 優先於「大 prefix 視覺重量平衡文字塊」。這是 Steps 跟其他 row primitive 的本質差異——Steps 是「一條有連接關係的進度路徑」,column rhythm 是元件本身。</Desc>
         <div className="border border-border rounded-lg p-4 max-w-md">
           <Steps orientation="vertical" value="b" completedValues={['a']}>
-            <StepItem value="a"><StepLabel>簡短 label</StepLabel></StepItem>
+            <StepItem value="a"><StepLabel>驗證電子信箱</StepLabel></StepItem>
             <StepItem value="b">
-              <StepLabel>帶有描述的 label</StepLabel>
-              <StepDescription>即使有多行 description,indicator 仍然對齊 label 第一行,保持 column rhythm</StepDescription>
+              <StepLabel>完善公司資料</StepLabel>
+              <StepDescription>填寫營業登記號碼、負責人身分與收款銀行帳戶,審核通過後才會開通金流收款功能</StepDescription>
             </StepItem>
-            <StepItem value="c"><StepLabel>另一個 label</StepLabel></StepItem>
+            <StepItem value="c"><StepLabel>啟用收款</StepLabel></StepItem>
           </Steps>
         </div>
         <p className="text-footnote text-fg-muted mt-3">業界共識:Apple HIG、Material 3、Linear、GitHub Actions 的 steps 都是 indicator 對齊 label 第一行</p>

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

@@ -128,7 +128,7 @@ export const ParentControlled: Story = {
             </StepItem>
             <StepItem value="payment">
               <StepLabel>付款</StepLabel>
-              <StepDescription>此頁為 current + error</StepDescription>
+              <StepDescription>信用卡授權失敗,請確認卡號與有效期限後重新付款</StepDescription>
             </StepItem>
             <StepItem value="done">
               <StepLabel>完成</StepLabel>

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

@@ -221,8 +221,8 @@ Per-item `state="error"` prop 存在但是 **escape hatch**,僅用在 inline JSX
 
 ### Outer ring 的關鍵設計
 
-- **Bounding box 固定**:box-shadow 不佔 layout(zero layout impact),focused / non-focused 的 indicator 佔用完全相同的寬高(md=24px,lg=32px,sm=24px hit area)
-- **Surface gap + ring 兩層 box-shadow 實作**:`0 0 0 2px var(--surface), 0 0 0 4px <ringColor>`——內圈先用 surface 色拉開 2px gap,外圈再疊 2px ring 色,形成「indicator 外有一圈帶間隙的環」(對齊 Polaris / shadcn focus-ring surface-gap idiom)
+- **Bounding box 固定**:focus 外環以 box-shadow 表達,不改變 indicator 的 bounding box——focused / non-focused 佔用完全相同的寬高(md=24px,lg=32px,sm=24px hit area)
+- **Surface gap + ring 兩層外環**:內圈先用 surface 色拉開一段 gap,外圈再疊 ring 色,形成「indicator 外有一圈帶間隙的環」——精確 gap / ring 寬度與 box-shadow 值見 steps.tsx `getOuterRingShadow`(對齊 Polaris / shadcn focus-ring surface-gap idiom)<!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 - **Ring 色由 state 決定**:`error` → `--error-hover`;non-linear `current` → `--border-hover`;其餘(含 linear current / completed / upcoming / reachable)→ `--info-hover`
 
 ### State × Focus 視覺矩陣(md/lg)
@@ -346,6 +346,8 @@ Description 在 error state 下維持 `text-fg-secondary`(跟其他 state 一樣
 
 `orientation="horizontal"` 時 `<StepContent>` 一律不渲染,`expansion` prop 被忽略。水平空間不夠塞 content 區,強塞會破壞 stepper 的掃視節奏。Consumer 可以共用同一份 JSX 在兩種 orientation 間切換,不會報錯。
 
+**展開 controlled/uncontrolled(2026-07-18 user 拍板補完整雙向)**:`multiple` 模式支援 controlled `expanded: string[]` + `onExpandedChange`(與 `defaultExpanded` uncontrolled 二選一)。理由:Steps 整體 API 哲學是 **parent 掌控狀態**(`value` / `completedValues` / `errorValues` 全 parent-controlled),唯獨展開狀態原只 uncontrolled 自相矛盾;且最近親 `TreeView` 就是完整雙向(`expandedIds` + `onExpandedChange` + `defaultExpandedIds`)。對齊 Radix/MUI/Ant Accordion 全數雙向。傳 `expanded` 時展開狀態由 consumer 掌控,toggle step 經 `onExpandedChange` 回寫新陣列。
+
 ---
 
 ## Orientation