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

package/src/components/Skeleton/skeleton.stories.tsx

@@ -1,6 +1,10 @@
 // @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.
+// @story-baseline: packages/design-system/src/components/DataTable/data-table.stories.tsx#NumberAlignment
 import type { Meta, StoryObj } from '@storybook/react'
+import type { ColumnDef } from '@tanstack/react-table'
 import { Skeleton } from './skeleton'
+import { DataTable } from '@/design-system/components/DataTable/data-table'
+import '@/design-system/components/DataTable/column-types' // ColumnMeta declaration merging
 
 /**
  * Skeleton 展示——在資料載入完成前，用灰色色塊模擬真實內容的形狀與排版。
@@ -58,35 +62,39 @@ export const TaskListLoading: Story = {
   ),
 }
 
+/* ── 表格列載入 ──
+   消費真 <DataTable>(per data-table.spec.md「狀態處理職責邊界」:DataTable 禁內建 loading prop,
+   無資料載入由 consumer 渲 Skeleton placeholder rows;對齊 MUI X `noRowsVariant=skeleton` /
+   Carbon DataTableSkeleton「header 可見 + body cell skeleton」派)。
+   Columns 不設 meta.type → 走 consumer 自訂 cell 渲 Skeleton(meta.type 命中 registry 會繞過自訂 cell)。 */
+interface LoadingRow {
+  id: string
+}
+
+const LOADING_ROWS: LoadingRow[] = Array.from({ length: 4 }, (_, i) => ({ id: `loading-${i + 1}` }))
+
+const loadingColumns: ColumnDef<LoadingRow>[] = [
+  { id: 'txn', header: '交易編號', meta: { width: 160 }, cell: () => <Skeleton className="h-4 w-28" /> },
+  { id: 'amount', header: '金額', meta: { width: 110, align: 'right' }, cell: () => <Skeleton className="h-4 w-16" /> },
+  {
+    id: 'customer',
+    header: '客戶',
+    meta: { width: 200 },
+    cell: () => (
+      <div className="flex items-center gap-2">
+        <Skeleton className="h-6 w-6 rounded-full" />
+        <Skeleton className="h-4 w-24" />
+      </div>
+    ),
+  },
+  { id: 'date', header: '日期', meta: { width: 130 }, cell: () => <Skeleton className="h-4 w-20" /> },
+]
+
 export const TableRowLoading: Story = {
   name: '表格列載入',
   render: () => (
-    <div className="border border-border rounded-lg overflow-hidden max-w-3xl">
-      <table className="w-full">
-        <thead className="bg-muted">
-          <tr>
-            <th className="text-left text-caption text-fg-secondary px-4 py-2 font-medium">交易編號</th>
-            <th className="text-left text-caption text-fg-secondary px-4 py-2 font-medium">金額</th>
-            <th className="text-left text-caption text-fg-secondary px-4 py-2 font-medium">客戶</th>
-            <th className="text-left text-caption text-fg-secondary px-4 py-2 font-medium">日期</th>
-          </tr>
-        </thead>
-        <tbody className="divide-y divide-border">
-          {Array.from({ length: 4 }).map((_, i) => (
-            <tr key={i}>
-              <td className="px-4 py-3"><Skeleton className="h-4 w-28" /></td>
-              <td className="px-4 py-3"><Skeleton className="h-4 w-16" /></td>
-              <td className="px-4 py-3">
-                <div className="flex items-center gap-2">
-                  <Skeleton className="h-6 w-6 rounded-full" />
-                  <Skeleton className="h-4 w-24" />
-                </div>
-              </td>
-              <td className="px-4 py-3"><Skeleton className="h-4 w-20" /></td>
-            </tr>
-          ))}
-        </tbody>
-      </table>
+    <div aria-busy="true" className="max-w-3xl">
+      <DataTable columns={loadingColumns} data={LOADING_ROWS} getRowId={(r) => r.id} height="auto" />
     </div>
   ),
 }

package/src/components/Skeleton/skeleton.tsx

@@ -24,7 +24,7 @@ export const skeletonMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  states: [], // 2026-06-11 R2:非互動元件,只有顯示/不顯示(spec L77;同 DescriptionList 先例),
   tokens: {
     bg: ['bg-muted'],
     fg: [],

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

@@ -45,13 +45,13 @@ export const UsageGuidance: Story = {
       <p>適合 Slider 的真實業務場景(點擊跳轉「展示」頁範例):</p>
       <ul className="space-y-1">
         <li>
-          <LinkTo kind="Design System/Components/Slider/展示" name="容器尺寸對齊"><span className="text-primary hover:underline font-medium cursor-pointer">容器尺寸對齊</span></LinkTo>
+          <LinkTo kind="Design System/Components/Slider/展示" name="容器尺寸對齊"><span className="text-primary hover:underline font-medium cursor-pointer">表單內與 Input / NumberInput 並排的數值調整（容器尺寸對齊）</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Slider/展示" name="最小 / 最大 / 步階"><span className="text-primary hover:underline font-medium cursor-pointer">最小 / 最大 / 步階</span></LinkTo>
+          <LinkTo kind="Design System/Components/Slider/展示" name="最小 / 最大 / 步階"><span className="text-primary hover:underline font-medium cursor-pointer">價格 / 數量等有上下限與步階的調整（最小 / 最大 / 步階）</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Slider/展示" name="提交數值回呼"><span className="text-primary hover:underline font-medium cursor-pointer">提交數值回呼</span></LinkTo>
+          <LinkTo kind="Design System/Components/Slider/展示" 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>

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

@@ -1,6 +1,6 @@
 ---
 component: Slider
-family: 4
+family: self-contained
 variants: {}
 sizes:
   sm:
@@ -85,7 +85,7 @@ Slider 接收 `size?: 'sm' | 'md' | 'lg'` prop(預設 `md`),**這個 prop 只決
 
 ### 為什麼不完全對齊 `--field-height-*`
 
-- **現況**:容器高 = `--field-height-sm/md/lg`(對齊);track 厚度固定 4px / thumb 直徑固定 16px / thumb 邊框固定 2px(`border-2`),**皆不隨 size 變化**(偏離 size-proportional scaling)。focus 不加 ring / halo,改用 border 加深(詳「視覺規格」L109)
+- **現況**:容器高 = `--field-height-sm/md/lg`(對齊);track 厚度固定 4px / thumb 直徑固定 16px / thumb 邊框固定 2px,**皆不隨 size 變化**(偏離 size-proportional scaling)。focus 不加 ring / halo,改用 border 加深(詳「視覺規格」表)
 - **Rationale**:Slider 的 thumb 是「位置指示器」,必須足夠大好捕捉(Fitts's Law);縮小成比例(sm=12 / lg=20 之類)會讓 sm 幾乎無法精確拖曳。業界共識:track/thumb 是**單一視覺規格**,`size` 只控容器外高讓 Slider 並排對齊,內部透過 `flex items-center` 垂直置中
 - **世界級對照**:Material 3 Slider(track 4dp thumb 20dp 固定)/ iOS UISlider(track 3pt thumb 28pt 固定)/ Ant Design Slider(track 4px thumb 14px 固定)/ Radix Slider(default 4px track)——全部 thumb / track 尺寸獨立於 form-size system <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
@@ -95,14 +95,14 @@ Slider 接收 `size?: 'sm' | 'md' | 'lg'` prop(預設 `md`),**這個 prop 只決
 
 | 元素 | 值 | Token |
 |---|---|---|
-| **Track** 厚度 | 4px(`h-1`) | — |
+| **Track** 厚度 | 4px | — |
 | **Track** 底色 rest | `bg-secondary` | `--secondary`(neutral-3,跟 Tag neutral / Badge low 同級「微淡可辨」)|
 | **Track** 底色 disabled | `bg-muted` | `--muted`(neutral-2,disabled-like 退化)|
 | **Range** 填滿色 rest | `bg-primary` | `--primary` |
 | **Range** 填滿色 disabled | `bg-border`(neutral-5)| `--border` |
-| **Thumb** 直徑 | 16px(`h-4 w-4`) | — |
+| **Thumb** 直徑 | 16px | — |
 | **Thumb** 底色(rest + disabled 不變)| `bg-surface`(白) | `--surface` |
-| **Thumb** 邊框 rest | `border-2 border-primary`(= Range rest 同色)| `--primary` |
+| **Thumb** 邊框 rest | 2px,色 = Range rest 同 token | `--primary` |
 | **Thumb** 邊框 disabled | `border-border`(= Range disabled 同色)| `--border` |
 | **Thumb** hover | border `primary-hover` + 陰影 `--elevation-100` | `--primary-hover` |
 | **Thumb** active | 陰影 `--elevation-200` | — |
@@ -156,7 +156,7 @@ Slider 不是 button——它是「當前位置指示器」,底色不該動(動
   step={number}                    // 預設 1
   size="sm" | "md" | "lg"          // 預設 md(只影響容器外高)
   disabled={boolean}
-  orientation="horizontal"         // 不支援 vertical(用 TickSlider / 垂直尺若未來需要再擴充)
+  orientation="horizontal"         // 不支援 vertical(DS 尚無垂直變體;未來真有需求再擴充)
   minStepsBetweenThumbs={number}   // range mode 時兩個 thumb 的最小距離
 />
 ```
@@ -293,6 +293,14 @@ Slider 的 `readonly` 等同於 `disabled`——一個不能操作的 slider 本
 
 ---
 
+## 常見誤解
+
+- 「Slider 可以當計數器」——錯。Slider 傳達 position(在哪裡),計數(多少)用 NumberInput ±step(見「何時不用」)
+- 「兩個選項可以用 Range mode」——錯。Range 是連續值區間(value = [start, end]),二元 / 布林選擇用 Switch / SegmentedControl
+- 「focus 要加 ring」——本元件 documented 例外:focus 用 border 加深(同 hover 視覺),不加 ring / halo(見「視覺規格」表)
+
+---
+
 ## Do / Don't
 
 ✅ **Do**
@@ -335,12 +343,7 @@ Slider 的可調維度是 `min` / `max` / `step` / `defaultValue`(值域與步
 
 **ARIA / Pattern**:繼承 Radix `slider` primitive a11y 預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/slider#accessibility)。
 
-**Keyboard 行為**:
-
-- Tab — focus thumb
-- ←/→ — 微調
-- Home/End — min/max
-- PageUp/Down — 大步階
+**Keyboard 行為**:完整鍵盤對照見上方「鍵盤操作(Radix 原生,免手工)」節,不重複列。
 
 **Focus**:Radix primitive 自管 focus / restoration;thumb 鍵盤聚焦時 `outline-none focus-visible:border-primary-hover`(border 加深成 primary-hover,跟 hover 同視覺,不加 ring / halo)。
 
@@ -350,4 +353,5 @@ Slider 的可調維度是 `min` / `max` / `step` / `defaultValue`(值域與步
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `number-input.spec.md`
 - `switch.spec.md`

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

@@ -66,24 +66,8 @@ export const MinMaxStep: Story = {
 }
 
 // @story-trait-rationale: Disabled retired 2026-05-17 per audit Dim 24 —
-//   anatomy.stories.tsx StateBehavior 已 cover disabled state。展示層保留 SizeAlignment + MinMaxStep。
-//   (legacy Disabled body 移到 anatomy StateBehavior demo;若要看 disabled,進 anatomy 頁)
-export const Disabled_REMOVED: Story = {
-  name: '停用狀態（已移至設計規格頁示範）',
-  tags: ['!autodocs', '!dev'],
-  render: () => (
-    <div className="w-[360px] flex flex-col gap-6">
-      <div className="flex flex-col gap-2">
-        <div className="text-caption text-fg-muted">單值 disabled</div>
-        <Slider defaultValue={[60]} disabled />
-      </div>
-      <div className="flex flex-col gap-2">
-        <div className="text-caption text-fg-muted">範圍 disabled</div>
-        <Slider defaultValue={[20, 80]} disabled />
-      </div>
-    </div>
-  ),
-}
+//   anatomy.stories.tsx StateBehavior 已 cover disabled state(單值 + 範圍)。展示層保留 SizeAlignment + MinMaxStep + OnCommit。
+//   2026-06-11:刪除 zombie export `Disabled_REMOVED`,對齊 DS-wide comment-only 退役慣例(deep-audit dim25)。
 
 // ── With live value commit ──────────────────────────────────────────────
 

package/src/components/Slider/slider.tsx

@@ -2,7 +2,7 @@ import * as React from 'react'
 import * as SliderPrimitive from '@radix-ui/react-slider'
 import { cva, type VariantProps } from 'class-variance-authority'
 import { cn } from '@/lib/utils'
-import { useResolvedFieldDisabled } from '@/design-system/components/Field/field-context'
+import { useFieldContext, useResolvedFieldDisabled } from '@/design-system/components/Field/field-context'
 
 /**
  * Slider — 數值範圍選取器
@@ -62,6 +62,9 @@ const Slider = React.forwardRef<
   // 家族整合時繼承其 canonical」)。Slider 已有完整 data-[disabled] 視覺,故只需把 fieldCtx disabled 接上。
   // 2026-06-08 SSOT:讀 useResolvedFieldDisabled()(fieldCtx.disabled)→ <Field disabled> 與 <Field mode="disabled"> 都生效
   const fieldDisabled = useResolvedFieldDisabled()
+  // 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
   // 推導要渲染幾個 thumb:controlled 用 value,uncontrolled 用 defaultValue,
   // 都沒有時 fallback 單 thumb(Radix 預設行為)
   const thumbCount =
@@ -147,6 +150,7 @@ const Slider = React.forwardRef<
                 : ariaLabel
               : undefined
           }
+          aria-labelledby={!ariaLabel && fieldLabelId ? fieldLabelId : undefined}
         />
       ))}
     </SliderPrimitive.Root>
@@ -158,7 +162,7 @@ Slider.displayName = 'Slider'
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const sliderMeta = {
   component: 'Slider',
-  family: 4,
+  family: null, // self-contained(對齊 spec;同 rating.tsx 慣例),
   variants: {},
   // size 只控容器外高,對齊 Field family h-field-*(md density:28/32/36px,uiSize.css)。
   // track 厚度 / thumb 直徑固定不隨 size 變,故無 iconSize / typography。

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

@@ -134,7 +134,7 @@ export const OrientationMatrix: Story = {
         <H3>Horizontal</H3>
         <Desc>步驟水平排列,常見於結帳流程 / wizard 頂部。Indicator 之間有橫向 connector。</Desc>
         <div className="border border-border rounded-lg p-4 max-w-2xl">
-          <Steps value="payment" completedValues={['cart']}>
+          <Steps orientation="horizontal" value="payment" completedValues={['cart']}>
             <StepItem value="cart"><StepLabel>購物車</StepLabel></StepItem>
             <StepItem value="payment"><StepLabel>付款</StepLabel></StepItem>
             <StepItem value="shipping"><StepLabel>配送</StepLabel></StepItem>
@@ -348,7 +348,7 @@ const ErrorInterrupt = () => {
           ))}
         </Steps>
       </div>
-      <div className="text-[11px] text-fg-muted">payment step 發生錯誤:indicator 切 `bg-error` + X icon,label 轉 `--error`。對 focus ring 也從 primary-hover 切到 error-hover。</div>
+      <div className="text-[11px] text-fg-muted">payment step 發生錯誤:indicator 切 `bg-error` + X icon,label 轉 `--error-text`。focus ring 也從 info-hover 切到 error-hover。</div>
     </div>
   )
 }
@@ -391,7 +391,7 @@ export const StateBehavior: Story = {
       <div className="flex flex-col gap-3">
         <span className="text-caption font-medium text-fg-secondary">行為 3:Error interrupt(中斷流程)</span>
         <Desc>
-          任何 step 加入 `errorValues` 時,該 step 轉 error state(紅底 + X icon),label 色轉 `--error`。
+          任何 step 加入 `errorValues` 時,該 step 轉 error state(紅底 + X icon),label 色轉 `--error-text`。
           consumer 若要繼續流程,必須先解除 errorValues 再推進 current——避免靜默跳過錯誤。
         </Desc>
         <ErrorInterrupt />

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

@@ -76,22 +76,19 @@ export const UsageGuidance: Story = {
       <p>適合 Steps 的真實業務場景(點擊跳轉「展示」頁範例):</p>
       <ul className="space-y-1">
         <li>
-          <LinkTo kind="Design System/Components/Steps/展示" name="聚焦環正交示範"><span className="text-primary hover:underline font-medium cursor-pointer">Ring 正交示範</span></LinkTo>
+          <LinkTo kind="Design System/Components/Steps/展示" name="預設"><span className="text-primary hover:underline font-medium cursor-pointer">註冊申請精靈(預設)</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Steps/展示" name="非線性"><span className="text-primary hover:underline font-medium cursor-pointer">非線性</span></LinkTo>
+          <LinkTo kind="Design System/Components/Steps/展示" name="非線性"><span className="text-primary hover:underline font-medium cursor-pointer">工作區設定導覽(非線性)</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Steps/展示" name="水平"><span className="text-primary hover:underline font-medium cursor-pointer">水平</span></LinkTo>
+          <LinkTo kind="Design System/Components/Steps/展示" name="水平"><span className="text-primary hover:underline font-medium cursor-pointer">結帳流程進度(水平)</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Steps/展示" name="多重展開模式"><span className="text-primary hover:underline font-medium cursor-pointer">Multiple 展開模式</span></LinkTo>
-        </li>
-        <li>
-          <LinkTo kind="Design System/Components/Steps/展示" name="欄 節奏 驗證"><span className="text-primary hover:underline font-medium cursor-pointer">欄 節奏 驗證</span></LinkTo>
+          <LinkTo kind="Design System/Components/Steps/展示" 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>
+      <p className="text-fg-secondary mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用下方清單建議的近親元件。</p>
     </div>
 
       {/* 何時不用 / 替代元件 — 原 WhenNotToUse */}
@@ -146,7 +143,7 @@ export const ParentControlled: Story = {
 // ── 規則 2:Ring 是 focus marker,不是 selection ──
 
 export const RingIsFocusMarker: Story = {
-  name: '規則:環 是 聚焦 標記,不是 選取',
+  name: '規則:環是聚焦標記,不是選取',
   render: () => (
     <Section
       title="Ring 表達「你現在在這步」,跟 step 本身的狀態正交"
@@ -181,7 +178,7 @@ export const RingIsFocusMarker: Story = {
 // ── 規則 3:Blue connector 只跟 completedValues 走 ──
 
 export const BlueConnectorLogic: Story = {
-  name: '規則:藍色 連線 只跟 已完成 走',
+  name: '規則:藍色連線只跟已完成走',
   render: () => (
     <Section
       title="藍色代表實際走過的路徑,不是 focus 指向"
@@ -220,7 +217,7 @@ export const BlueConnectorLogic: Story = {
 // ── 規則 4:Column rhythm ──
 
 export const ColumnRhythm: Story = {
-  name: '規則:指示 欄 節奏',
+  name: '規則:指示欄節奏一致',
   render: () => (
     <Section
       title="Indicator 永遠對齊 label 第一行——即使同一 Steps 內混用「有/無 description」"
@@ -259,7 +256,7 @@ export const ColumnRhythm: Story = {
 // ── 規則 5:Linear 點 completed 不自動 unmark ──
 
 export const LinearBackClickDoesNotMutate: Story = {
-  name: '規則:Linear 點回 完成項 不改狀態',
+  name: '規則:Linear 點回完成項不改狀態',
   render: () => {
     const [value, setValue] = React.useState('review')
     const [completed] = React.useState(['info', 'account'])

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

@@ -72,7 +72,7 @@ Steps 是 `patterns/element-anatomy/item-anatomy.spec.md` 的 row primitive **co
 | Prefix | `StepIndicator`(圓形 + 數字 / icon)|
 | Label | `StepLabel` |
 | Description | `StepDescription`(永遠可選)|
-| Suffix | — (Steps 不使用 suffix slot)|
+| Suffix | 展開 chevron(僅 `expansion="multiple"` 且該 step 有 content 時渲染;消費 item-anatomy `<ItemSuffix>`)|
 | Content | `StepContent`(垂直模式特有)|
 
 ### 從 item-layout **繼承**的規則(不重複定義)
@@ -131,6 +131,8 @@ indicator 圓形 flex items-center 居中
 → indicator 位置完全不受 description 有無影響
 ```
 
+實作:indicator 容器(垂直 / 水平)與展開 chevron 一律消費 `patterns/element-anatomy` 的 `<ItemPrefix>` / `<ItemSuffix>` primitive(`h-[1lh] shrink-0 flex items-center` 的 SSOT),不手刻 wrapper(M17)。
+
 ---
 
 ## Size
@@ -173,6 +175,7 @@ indicator 圓形 flex items-center 居中
 | `upcoming` | 灰底(`bg-muted`)+ 灰字(`text-fg-disabled`)| 未走到 |
 | `current` | 藍底(`bg-info`)+ 白字數字 | step === `value` 且不在 completedValues / errorValues |
 | `completed` | 藍底(`bg-info`)+ 白色 ✓ | step 在 `completedValues` 內 |
+| `reachable` | 藍底(`bg-info`)+ 白字數字(僅 linear;sm 為空心環)| linear 下「下一個未完成」step(非 current / completed / error),可點 |
 | `error` | 紅底(`bg-error`)+ 白色 ✕ | step 在 `errorValues` 內(或單項 `state="error"` override)|
 
 ### Sm size 的 state 視覺
@@ -183,28 +186,30 @@ sm 沒有 icon 空間,用色塊表達:
 - `completed` → 藍實心點(`bg-info`)
 - `error` → 紅實心點(`bg-error`)
 
-### 自動推導(linear / non-linear 行為不同)
+### 自動推導(順序即優先級,對齊 `computeState`)
 
-**Consumer 不手寫每個 step 的 state**。State 由 Steps root 的 props + `linear` flag 推導:
+**Consumer 不手寫每個 step 的 state**。State 由 Steps root 的 props 依下列順序推導(`steps.tsx` `computeState`):
 
 ```
-step 在 completedValues                          → completed
-step 在 errorValues                              → error
-linear && step === value(且不在上面兩者)        → current
-其他                                             → upcoming
+per-item state override(escape hatch)              → 直接採用
+step 在 errorValues                                 → error(優先於 completed;交集一律 error)
+step 在 completedValues                             → completed
+step === value                                      → current(linear / non-linear 都成立)
+linear && step 在 reachable(completed ∪ 首個未完成)→ reachable
+其他                                                → upcoming
 ```
 
-**關鍵**:`current` 狀態**只在 linear 模式**下被 auto-promote。非 linear 模式下,使用者「瀏覽」到 upcoming step 時,step 本身的 content state 仍然是 `upcoming`(還沒做),focus 透過 box-shadow 外環視覺表達,**不會**變成 current 的 filled 藍色。
+**關鍵**:`value` 命中的 step 在兩種模式下 content state 都是 `current`,但 **filled 藍的「正在做」視覺只屬於 linear**。非 linear 的 current 渲染中性 `bg-secondary` + `foreground` 數字(見「Non-linear 被選中 ≠ filled 藍」),focus 由 box-shadow 外環表達,**不會**出現 filled 藍。
 
-### 為什麼非 linear 不 promote
+### 為什麼非 linear 的 current 不渲染 filled 藍
 
-非 linear 模式讓使用者跳著點 step(例如設定頁、教學目錄),value 的語意是「使用者在看哪一步」,**不是**「使用者在做哪一步」。如果每次 value 變化就把該 step promote 成 current,會造成:
+非 linear 模式讓使用者跳著點 step(例如設定頁、教學目錄),value 的語意是「使用者在看哪一步」,**不是**「使用者在做哪一步」。如果非 linear 也渲染 filled 藍,會造成:
 
 - 使用者點 upcoming step 想預覽 → step 立刻變 filled 藍,像是「標記為正在做」
 - 跟 mental model「我只是在看,這步還沒做」衝突
-- completedValues 沒有變化,前一個 current 突然不見
+- completedValues 沒有變化,前一個 filled 藍 step 突然不見
 
-正確做法:focus 跟 content state 完全解耦——focus 透過 box-shadow 外環視覺表達,content state 由 linear/completedValues/errorValues 決定。linear 是 `current` 概念存在的前提。
+正確做法:focus 視覺跟「進度視覺」完全解耦——focus 透過 box-shadow 外環表達,filled 藍由 linear / completedValues 決定。filled「正在做」視覺是 linear 的概念。
 
 Per-item `state="error"` prop 存在但是 **escape hatch**,僅用在 inline JSX 想直接宣告錯誤的罕見場景;一般情況用 `errorValues` array 統一管理,不要混用。
 
@@ -251,14 +256,14 @@ sm 的 8px dot 用同一套 `getOuterRingShadow` box-shadow halo 在 dot 外圍
 
 直接在 filled circle 外貼一圈同色 ring 會讀成「雙圈」很醜;先用 `var(--surface)` 拉一圈 2px gap 再疊 ring,讓環跟 indicator 之間有底色間隙,視覺乾淨且各 state 都清楚(對齊 shadcn `ring-offset` / Polaris focus indicator surface-gap canonical)。
 
-### Non-linear 被選中 ≠ current(關鍵規則)
+### Non-linear 被選中 ≠ filled 藍(關鍵規則)
 
-非 linear 模式使用者點 upcoming step 瀏覽時,step 的 **content state 仍是 upcoming**(見「自動推導」節),只是 focused。視覺上會是(md/lg):
-- 底色:`bg-secondary`(**刻意不同於 linear upcoming 的 `bg-muted`**——non-linear 所有 step 都可點 reachable,不該像 linear upcoming 那樣呈現「鎖住/還到不了」的 muted 灰;secondary 傳達「可導覽但非當前」)
+非 linear 模式使用者點 upcoming step 瀏覽時,step 的 content state 變為 `current`(`computeState` 對 value 命中者一律回 current),但渲染**刻意中性**。視覺上會是(md/lg):
+- 底色:`bg-secondary`(**刻意不同於 linear upcoming 的 `bg-muted`**——non-linear 所有 step 都可點,不該像 linear upcoming 那樣呈現「鎖住/還到不了」的 muted 灰;secondary 傳達「可導覽但非當前」)
 - 數字:`foreground`(可讀,非 disabled 弱字——呼應 step 可達)
-- 外環:`--info-hover` box-shadow ring(focus marker,表達「你在看這一步」)
+- 外環:`--border-hover` box-shadow ring(focus marker,表達「你在看這一步」;`resolveRingColor` 對 non-linear current)
 
-**不會**變成 current 的 filled 藍——這對齊使用者 mental model「我只是在看,這步還沒做」。non-linear current 與 upcoming 同為 `bg-secondary` 底,focus 純靠外環色區分(current 用 `--border-hover`、upcoming 用 `--info-hover`)。sm 尺寸的 dot 在 non-linear upcoming 仍用 `fg-disabled` 灰點(8px dot 最小化呈現)。
+**不會**出現 linear current 的 filled 藍——這對齊使用者 mental model「我只是在看,這步還沒做」。non-linear current 與 upcoming 同為 `bg-secondary` 底,被選中(focused)的 step 以 `--border-hover` 外環標示。sm 尺寸的 dot 在 non-linear current 仍用 `fg-disabled` 灰點(8px dot 最小化呈現)。
 
 **Ring 不是 selection marker**。Steps 不是 SelectMenu / DropdownMenu 這類 selection control;ring 是 focus marker 單一語意。`CLAUDE.md` 的「選擇 / 狀態視覺」規則 B 指出的 `bg-neutral-selected`、radio 圓圈等 selection 視覺**都不適用 Steps**——Steps 用 box-shadow 外環表達「you are here」,不是「你選中了這個」。
 
@@ -311,7 +316,7 @@ Description 在 error state 下維持 `text-fg-secondary`(跟其他 state 一樣
 
 | Mode | 點擊規則 |
 |---|---|
-| `linear=true`(預設) | 可點:`completed` / `current` / `error`。**不可點**:`upcoming`(尚未解鎖)。 |
+| `linear=true`(預設) | 可點:`completed` / `current` / `error` / `reachable`(下一個未完成)。**不可點**:`upcoming`(尚未解鎖)。 |
 | `linear=false` | 所有非 `disabled` 的 step 都可點。適合 setting wizard、教學目錄等「步驟之間無強依賴」的場景。 |
 
 ### 點擊 completed step 的行為
@@ -322,7 +327,7 @@ Description 在 error state 下維持 `text-fg-secondary`(跟其他 state 一樣
 2. **`completedValues` 維持不變**,不自動 mutate
 3. 如果應用層驗證使用者改錯某欄位需要 block 後續步驟,應用層自己從 `completedValues` 移除該 step 及其後所有 step(這是 business logic,不是元件責任)
 
-這條規則的核心是:**Steps 是純 controlled 元件,從不偷偷改 parent state**。所有 state mutation 都經過 parent 的 state setter,讓應用層完整掌控推進邏輯。
+這條規則的核心是:**Steps 從不偷偷改 parent state**——進度狀態(`completedValues` / `errorValues`)全由 parent own;`value` 為 controlled / uncontrolled(`defaultValue`)雙模,uncontrolled 僅內部記住 focus,不碰進度。所有進度 mutation 都經過 parent 的 state setter,讓應用層完整掌控推進邏輯。
 
 ---
 
@@ -331,7 +336,7 @@ Description 在 error state 下維持 `text-fg-secondary`(跟其他 state 一樣
 | 模式 | 行為 |
 |---|---|
 | `follow-active`(預設) | 只有 `value` 指向的 step 渲染 `<StepContent>`。value 切換時 content 跟著切。其他 step 即使寫了 `<StepContent>` 也不顯示。 |
-| `multiple` | 每個 step 獨立管理展開狀態,**可同時展開多個**。點 step header 切換該 step 的展開(不切換 `value`)。`defaultExpanded` 接 `"all" \| "none" \| string[]`,預設 `"none"`。 |
+| `multiple` | 每個 step 獨立管理展開狀態,**可同時展開多個**。點 step header 永遠先更新 `value`(focus),並額外切換該 step 的展開。`defaultExpanded` 接 `"all" \| "none" \| string[]`,預設 `"none"`。 |
 
 ### 為什麼 `all` 隸屬於 `multiple`
 
@@ -384,7 +389,7 @@ Description 在 error state 下維持 `text-fg-secondary`(跟其他 state 一樣
 
 1. **Single source of truth**:所有狀態集中在 parent,不可能發生「多個 step 同時是 current」「completedValues 跟 item state 互相矛盾」這類 bug。
 2. **Derived state**:每個 step 的 state 由 parent props 推導,consumer 不手算,不會漂移。
-3. **無 side effect**:Steps 不內部 mutate 狀態,所有變動都走 parent 的 state setter,讓應用層完整掌控推進邏輯(驗證 → 加入 completedValues → 推進 value)。
+3. **無 side effect**:Steps 不偷偷 mutate 進度狀態(completedValues / errorValues),進度變動都走 parent 的 state setter,讓應用層完整掌控推進邏輯(驗證 → 加入 completedValues → 推進 value)。
 4. **對齊業界**:Ant Design Steps(`current` + `status`)、Material Stepper(`activeStep`)、Radix Tabs(`value`)全部用此模式。開發者從這些系統來的直覺可直接套用,學習曲線接近零。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 ### Per-item `state` escape hatch
@@ -428,10 +433,10 @@ Item-level **內容狀態色彩**(completed / current / upcoming / error indicat
 ## 邊界案例
 
 - **Disabled step**:`disabled` step 視覺繼承 SelectionItem disabled token(`text-fg-disabled`,M24),click 不觸發 navigate;`linear` mode 下 upcoming steps 預設 disabled 直到前面 completed。
-- **Loading(async step state fetch)**:Steps primitive 為 sync render,async data fetch 應由 consumer 在外層 Skeleton 取代整個 Steps;Steps 內部不獨立 own loading prop。
-- **Empty(0 steps)**:`items=[]` 無意義(無進度可呈現);consumer 應條件性不渲 Steps 或渲 `<Empty>` 替代,不渲空 Steps container。
-- **Single step / current=0**:合法初始狀態,渲第一個 step 為 current,後續為 upcoming。
-- **Error state(`errorValues`)**:由元件層級 own — 對應 step indicator 切 error token,connector 切 error muted,後續 step 仍 upcoming 但 user 預期 navigation 暫停。
+- **Loading(async step state fetch)**:Steps primitive 為 sync render,async data fetch 應由 consumer 在外層 Skeleton 取代整個 Steps;Steps 內部不獨立 own loading prop,**也無 per-step loading state**(content state 集合不含 loading)— 單一步驟 async 進行中即 current,進度細節由 consumer 在 `StepContent` 內呈現。
+- **Empty(0 steps)**:無任何 `<StepItem>` children 時無進度可呈現;consumer 應條件性不渲 Steps 或渲 `<Empty>` 替代,不渲空 Steps container。
+- **Single step / `value` 指向第一步**:合法初始狀態,第一個 step 渲染 current,後續依推導為 reachable / upcoming。
+- **Error state(`errorValues`)**:由元件層級 own — 對應 step indicator 切 error token、label 切 `text-error-text`(見「Label 色彩」);connector **不**變色,仍按「Connector 路徑色」規則(前一步 completed 才藍,否則灰);後續 step 仍 upcoming。
 - **Dark mode**:走 semantic token + Primary token 自動 adapt。
 - **Density**:Step indicator 32px 對齊 `AVATAR_SIZE.block.sm/md`,connector 細線跨 density 不變(進度視覺對 density 不敏感)。
 
@@ -470,4 +475,5 @@ Item-level **內容狀態色彩**(completed / current / upcoming / error indicat
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `horizontal-overflow.spec.md`
+- `item-anatomy.spec.md`
 - `progress-bar.spec.md`

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

@@ -185,7 +185,7 @@ export const FocusRingCombinations: Story = {
           </StepItem>
           <StepItem value="step-2">
             <StepLabel>Current</StepLabel>
-            <StepDescription>藍底數字 + ring(若 focused)</StepDescription>
+            <StepDescription>中性底(bg-secondary)數字 + ring(若 focused)</StepDescription>
           </StepItem>
           <StepItem value="step-3">
             <StepLabel>Completed</StepLabel>
@@ -283,7 +283,7 @@ export const MultipleExpansion: Story = {
   render: () => (
     <div className="w-[480px]">
       <p className="text-caption text-fg-secondary mb-4">
-        點 step header 切換展開。預設 `all` = 全部展開起手。
+        點 step header 切換展開(並更新 value)。本例顯式傳 `defaultExpanded="all"` 全部展開起手(預設 `"none"`)。
       </p>
       <Steps
         defaultValue="b"
@@ -330,41 +330,6 @@ export const MultipleExpansion: Story = {
   ),
 }
 
-// ── Without description ─────────────────────────────────────────────────
-// 驗證 column rhythm:混用有/無 description 的 step,indicator y 位置不變
-
-export const MixedDescription: Story = {
-  name: '欄 節奏 驗證',
-  render: () => (
-    <div className="flex gap-12">
-      {(['md', 'lg'] as const).map(size => (
-        <div key={size} className="w-[280px]">
-          <div className="text-caption text-fg-muted mb-4">size = {size}</div>
-          <Steps
-            defaultValue="step-3"
-            completedValues={['step-1', 'step-2']}
-            size={size}
-          >
-            <StepItem value="step-1">
-              <StepLabel>建立帳號</StepLabel>
-            </StepItem>
-            <StepItem value="step-2">
-              <StepLabel>驗證 Email</StepLabel>
-              <StepDescription>發送確認信至你的信箱</StepDescription>
-            </StepItem>
-            <StepItem value="step-3">
-              <StepLabel>設定團隊</StepLabel>
-              <StepDescription>
-                命名你的工作區、選擇方案、匯入現有專案;這個步驟結束後可隨時在設定頁
-                調整
-              </StepDescription>
-            </StepItem>
-            <StepItem value="step-4">
-              <StepLabel>邀請成員</StepLabel>
-            </StepItem>
-          </Steps>
-        </div>
-      ))}
-    </div>
-  ),
-}
+// @story-trait-rationale: MixedDescription(欄節奏驗證 grid)retired 2026-06-11 per audit
+//   EXAMPLE_REDUNDANT — indicator 對齊 label 第一行的 column rhythm 已由 anatomy「欄位節奏」+
+//   principles「規則:指示欄節奏一致」雙層 own;展示層不重複 trait 驗證 grid。