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

package/dist/components/Slider/slider.js

@@ -3,6 +3,7 @@ import * as React from "react";
 import * as SliderPrimitive from "@radix-ui/react-slider";
 import { cva } from "class-variance-authority";
 import { cn } from "../../lib/utils.js";
+import { useResolvedFieldDisabled, useResolvedFieldMode, useFieldContext } from "../Field/field-context.js";
 const sliderRootVariants = cva(
   // 容器外層:水平置中 + relative(Radix 會絕對定位內部元素)
   // flex items-center 讓 track+thumb 在任何 field-height 下都垂直置中
@@ -35,15 +36,25 @@ const sliderRootVariants = cva(
   }
 );
 const Slider = React.forwardRef(({ className, size, value, defaultValue, "aria-label": ariaLabel, ...props }, ref) => {
-  const thumbCount = Array.isArray(value) && value.length || Array.isArray(defaultValue) && defaultValue.length || 1;
+  var _a;
+  const fieldDisabled = useResolvedFieldDisabled();
+  const fieldMode = useResolvedFieldMode({ mode: void 0, disabled: void 0, readOnly: void 0 });
+  const fieldReadonly = fieldMode === "readonly";
+  const fieldLabelId = (_a = useFieldContext()) == null ? void 0 : _a.labelId;
+  const minValue = props.min ?? 0;
+  const safeValue = Array.isArray(value) && value.length === 0 ? [minValue] : value;
+  const safeDefaultValue = Array.isArray(defaultValue) && defaultValue.length === 0 ? [minValue] : defaultValue;
+  const thumbCount = Array.isArray(safeValue) && safeValue.length || Array.isArray(safeDefaultValue) && safeDefaultValue.length || 1;
   return /* @__PURE__ */ jsxs(
     SliderPrimitive.Root,
     {
       ref,
-      value,
-      defaultValue,
-      className: cn(sliderRootVariants({ size }), className),
+      value: safeValue,
+      defaultValue: safeDefaultValue,
+      className: cn(sliderRootVariants({ size }), fieldReadonly && "pointer-events-none", className),
       ...props,
+      disabled: props.disabled || fieldDisabled,
+      "data-readonly": fieldReadonly || void 0,
       children: [
         /* @__PURE__ */ jsx(SliderPrimitive.Track, { className: cn(
           "relative grow overflow-hidden rounded-full h-1",
@@ -62,20 +73,27 @@ const Slider = React.forwardRef(({ className, size, value, defaultValue, "aria-l
         Array.from({ length: thumbCount }).map((_, i) => /* @__PURE__ */ jsx(
           SliderPrimitive.Thumb,
           {
+            tabIndex: fieldReadonly ? -1 : void 0,
+            "aria-readonly": fieldReadonly || void 0,
             className: cn(
               "block h-4 w-4 shrink-0 rounded-full cursor-grab",
-              "bg-surface border-2 border-primary",
-              "transition-all duration-150",
-              // Hover:border 加深到 primary-hover + elevation 陰影
+              "bg-on-emphasis border-2 border-primary",
+              "transition-all duration-150 motion-reduce:duration-0",
+              // Hover:border 升 hover 階(light mode 淺一階 lift,= Button primary hover 變色邏輯)
+              // + elevation 陰影。2026-07-06 修語:原註解寫「加深」但 primary-hover 比 base 淺,
+              // 措辭與 token 相反 — token 不遷就錯註解,註解修正。
               "hover:border-primary-hover hover:[box-shadow:var(--elevation-100)]",
-              "active:cursor-grabbing active:border-primary-hover active:[box-shadow:var(--elevation-200)]",
-              // Focus:border 加深(跟 hover 同視覺),不加 ring 或 halo
+              // Active(按壓拖曳):深一階 primary-active(= Button active 邏輯 button.tsx active:*-active
+              // 對照組;原誤用 hover 階 = 全 DS 唯一 active-用-hover 偏移,2026-07-06 雙向全掃修正)
+              "active:cursor-grabbing active:border-primary-active active:[box-shadow:var(--elevation-200)]",
+              // Focus:跟 hover 同視覺(hover 階),不加 ring 或 halo
               "outline-none focus-visible:border-primary-hover",
-              // Disabled:border 跟 Range 一起退成 border(n-5),bg 保留 bg-surface
-              "data-[disabled]:cursor-not-allowed data-[disabled]:border-border",
+              // Disabled:border 跟 Range 一起退成 border(n-5),bg 沉回 canvas(不透明背景色)
+              "data-[disabled]:cursor-not-allowed data-[disabled]:border-border data-[disabled]:bg-canvas",
               "data-[disabled]:hover:[box-shadow:none]"
             ),
-            "aria-label": ariaLabel ? thumbCount > 1 ? `${ariaLabel} (${i + 1})` : ariaLabel : thumbCount > 1 ? `Thumb ${i + 1}` : void 0
+            "aria-label": ariaLabel ? thumbCount > 1 ? `${ariaLabel} (${i + 1})` : ariaLabel : void 0,
+            "aria-labelledby": !ariaLabel && fieldLabelId ? fieldLabelId : void 0
           },
           i
         ))
@@ -86,16 +104,20 @@ const Slider = React.forwardRef(({ className, size, value, defaultValue, "aria-l
 Slider.displayName = "Slider";
 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。
+  // fieldHeight key 對齊 compile-stories.mjs 消費 schema(同 Button/Checkbox/Switch)。
   sizes: {
-    sm: { px: 28, when: "Toolbar / inline 編輯" },
-    md: { px: 36, when: "預設 — Form / cell inline edit" },
-    lg: { px: 44, when: "Marketing / 高 touch 區" }
+    sm: { fieldHeight: 28, when: "Toolbar / inline 編輯" },
+    md: { fieldHeight: 32, when: "預設 — Form / cell inline edit" },
+    lg: { fieldHeight: 36, when: "Marketing / 高 touch 區" }
   },
   states: ["default", "hover", "active", "focus-visible", "disabled"],
   tokens: {
-    bg: ["bg-muted", "bg-primary", "bg-secondary", "bg-surface"],
+    bg: ["bg-muted", "bg-primary", "bg-secondary", "bg-on-emphasis", "bg-canvas"],
     fg: [],
     ring: []
   }

package/dist/components/Slider/slider.js.map

@@ -1 +1 @@
-{"version":3,"file":"slider.js","sources":["../../../src/components/Slider/slider.tsx"],"sourcesContent":["import * as React from 'react'\nimport * as SliderPrimitive from '@radix-ui/react-slider'\nimport { cva, type VariantProps } from 'class-variance-authority'\nimport { cn } from '@/lib/utils'\n\n/**\n * Slider — 數值範圍選取器\n *\n * 基於 Radix Slider primitive,橋接設計系統 token。詳細設計原則見 `slider.spec.md`。\n *\n * ── 核心設計 ──\n * 1. **視覺單一**:track 厚度、thumb 直徑、ring 尺寸都是固定值,不隨 `size` 變\n * 2. **`size` 只控容器外高**:對齊 Field family 的 `h-field-*` tier,讓 Slider 能跟\n *    Input / NumberInput / Select 在 Field 內並排對齊\n * 3. **Range mode 免費**:Radix 原生支援 `value: number[]`,傳多值自動多 thumb\n * 4. **Hover / active 用 elevation 陰影**:不用色變,避免暗示「這是 button」\n */\n\nconst sliderRootVariants = cva(\n  // 容器外層:水平置中 + relative(Radix 會絕對定位內部元素)\n  // flex items-center 讓 track+thumb 在任何 field-height 下都垂直置中\n  //\n  // ── Disabled 策略:灰階 token swap(對齊 Button / Checkbox)──\n  // Slider 的藍色 range 是美學視覺,不是 semantic state——使用者從 disabled\n  // slider 需要辨識的是 thumb 位置 + range 長度,這兩者不依賴顏色。失去藍色\n  // 沒有資訊損失。\n  //\n  // 跟 Switch 的差別:Switch 的 on/off 是純顏色差異(沒有形狀差異),所以必須\n  // 靠 opacity 保留色彩身分。Slider 的位置/長度是形狀差異,不需要保留顏色身分,\n  // 跟 Checkbox(checkmark 形狀 = semantic 載體)同類,應該走灰階。\n  //\n  // 詳細判準見 `slider.spec.md` 的「Disabled 策略」章節。\n  [\n    'relative flex items-center w-full min-w-0 touch-none select-none',\n    'data-[disabled]:cursor-not-allowed',\n  ],\n  {\n    variants: {\n      size: {\n        sm: 'h-field-sm',\n        md: 'h-field-md',\n        lg: 'h-field-lg',\n      },\n    },\n    defaultVariants: {\n      size: 'md',\n    },\n  },\n)\n\nexport interface SliderProps\n  extends Omit<React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root>, 'children'>,\n    VariantProps<typeof sliderRootVariants> {}\n\nconst Slider = React.forwardRef<\n  React.ElementRef<typeof SliderPrimitive.Root>,\n  SliderProps\n>(({ className, size, value, defaultValue, 'aria-label': ariaLabel, ...props }, ref) => {\n  // 推導要渲染幾個 thumb:controlled 用 value,uncontrolled 用 defaultValue,\n  // 都沒有時 fallback 單 thumb(Radix 預設行為)\n  const thumbCount =\n    (Array.isArray(value) && value.length) ||\n    (Array.isArray(defaultValue) && defaultValue.length) ||\n    1\n\n  return (\n    <SliderPrimitive.Root\n      ref={ref}\n      value={value}\n      defaultValue={defaultValue}\n      className={cn(sliderRootVariants({ size }), className)}\n      {...props}\n    >\n      {/*\n        Track — rest 用 bg-secondary(n-3,「微淡可辨」),disabled 用 bg-muted(n-2,退化)。\n        跟 Tag neutral / Badge low 同家族。\n      */}\n      <SliderPrimitive.Track className={cn(\n        'relative grow overflow-hidden rounded-full h-1',\n        // Rest:bg-secondary(n-3,「微淡可辨」的 subtle fill,跟 Tag neutral / Badge low 同級)\n        // Disabled:bg-muted(n-2,「disabled-like 退化」底色)\n        'bg-secondary data-[disabled]:bg-muted',\n      )}>\n        {/*\n          Range — 填滿段。\n\n          ── Range 色 = Thumb border 色(語意一致) ──\n          Rest 兩者都是 `primary`,disabled 兩者都是 `border`(n-5)。為什麼要一致?\n          Range 是「填充視覺」,Thumb border 是「thumb 的輪廓線」——視覺上 thumb\n          的 border 剛好是 range 的延續(thumb 坐落在 range 的端點上,border 跟\n          range 在色彩上融為一體,看起來像「range 包住 thumb」而不是「thumb 浮在\n          range 上」)。兩個 token 綁在一起,不論什麼 state 都一致。\n        */}\n        <SliderPrimitive.Range\n          className={cn(\n            'absolute h-full bg-primary',\n            'data-[disabled]:bg-border',\n          )}\n        />\n      </SliderPrimitive.Track>\n\n      {/*\n        Thumb — N 個(由 thumbCount 決定)。\n        白底 + 2px 邊框,邊框色 = Range 色(**一致綁定**):\n          - Rest: `border-primary` ↔ Range `bg-primary`\n          - Disabled: `border-border` ↔ Range `bg-border`\n        這個一致性讓 thumb border 跟 range 融為一體,看起來像「range 包住 thumb」\n        的連續視覺。thumb 的白底則是「被 range 圍住的空心洞」,讓 thumb 的位置\n        清楚浮出。不論 state,thumb border 跟 range 永遠同色。\n\n        **為什麼 thumb bg 不能改**:`bg-surface`(白)必須在 rest / disabled 都維持,\n        否則會融入 track 的 `bg-muted` 裡消失。這是之前踩過的同色融色 bug\n        (曾經寫成 `data-[disabled]:bg-muted` 讓 thumb 跟 track 完全融合)。\n      */}\n      {Array.from({ length: thumbCount }).map((_, i) => (\n        <SliderPrimitive.Thumb\n          key={i}\n          className={cn(\n            'block h-4 w-4 shrink-0 rounded-full cursor-grab',\n            'bg-surface border-2 border-primary',\n            'transition-all duration-150',\n            // Hover:border 加深到 primary-hover + elevation 陰影\n            'hover:border-primary-hover hover:[box-shadow:var(--elevation-100)]',\n            'active:cursor-grabbing active:border-primary-hover active:[box-shadow:var(--elevation-200)]',\n            // Focus:border 加深(跟 hover 同視覺),不加 ring 或 halo\n            'outline-none focus-visible:border-primary-hover',\n            // Disabled:border 跟 Range 一起退成 border(n-5),bg 保留 bg-surface\n            'data-[disabled]:cursor-not-allowed data-[disabled]:border-border',\n            'data-[disabled]:hover:[box-shadow:none]',\n          )}\n          aria-label={ariaLabel ? (thumbCount > 1 ? `${ariaLabel} (${i + 1})` : ariaLabel) : (thumbCount > 1 ? `Thumb ${i + 1}` : undefined)}\n        />\n      ))}\n    </SliderPrimitive.Root>\n  )\n})\nSlider.displayName = 'Slider'\n\n// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)\n// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs\nexport const sliderMeta = {\n  component: 'Slider',\n  family: 4,\n  variants: {},\n  sizes: {\n    sm: { px: 28, when: 'Toolbar / inline 編輯' },\n    md: { px: 36, when: '預設 — Form / cell inline edit' },\n    lg: { px: 44, when: 'Marketing / 高 touch 區' },\n  },\n  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],\n  tokens: {\n    bg: ['bg-muted', 'bg-primary', 'bg-secondary', 'bg-surface'],\n    fg: [],\n    ring: [],\n  },\n} as const\n\nexport { Slider, sliderRootVariants }\n"],"names":[],"mappings":";;;;;AAkBA,MAAM,qBAAqB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAczB;AAAA,IACE;AAAA,IACA;AAAA,EAAA;AAAA,EAEF;AAAA,IACE,UAAU;AAAA,MACR,MAAM;AAAA,QACJ,IAAI;AAAA,QACJ,IAAI;AAAA,QACJ,IAAI;AAAA,MAAA;AAAA,IACN;AAAA,IAEF,iBAAiB;AAAA,MACf,MAAM;AAAA,IAAA;AAAA,EACR;AAEJ;AAMA,MAAM,SAAS,MAAM,WAGnB,CAAC,EAAE,WAAW,MAAM,OAAO,cAAc,cAAc,WAAW,GAAG,MAAA,GAAS,QAAQ;AAGtF,QAAM,aACH,MAAM,QAAQ,KAAK,KAAK,MAAM,UAC9B,MAAM,QAAQ,YAAY,KAAK,aAAa,UAC7C;AAEF,SACE;AAAA,IAAC,gBAAgB;AAAA,IAAhB;AAAA,MACC;AAAA,MACA;AAAA,MACA;AAAA,MACA,WAAW,GAAG,mBAAmB,EAAE,KAAA,CAAM,GAAG,SAAS;AAAA,MACpD,GAAG;AAAA,MAMJ,UAAA;AAAA,QAAA,oBAAC,gBAAgB,OAAhB,EAAsB,WAAW;AAAA,UAChC;AAAA;AAAA;AAAA,UAGA;AAAA,QAAA,GAYA,UAAA;AAAA,UAAC,gBAAgB;AAAA,UAAhB;AAAA,YACC,WAAW;AAAA,cACT;AAAA,cACA;AAAA,YAAA;AAAA,UACF;AAAA,QAAA,GAEJ;AAAA,QAeC,MAAM,KAAK,EAAE,QAAQ,WAAA,CAAY,EAAE,IAAI,CAAC,GAAG,MAC1C;AAAA,UAAC,gBAAgB;AAAA,UAAhB;AAAA,YAEC,WAAW;AAAA,cACT;AAAA,cACA;AAAA,cACA;AAAA;AAAA,cAEA;AAAA,cACA;AAAA;AAAA,cAEA;AAAA;AAAA,cAEA;AAAA,cACA;AAAA,YAAA;AAAA,YAEF,cAAY,YAAa,aAAa,IAAI,GAAG,SAAS,KAAK,IAAI,CAAC,MAAM,YAAc,aAAa,IAAI,SAAS,IAAI,CAAC,KAAK;AAAA,UAAA;AAAA,UAdnH;AAAA,QAAA,CAgBR;AAAA,MAAA;AAAA,IAAA;AAAA,EAAA;AAGP,CAAC;AACD,OAAO,cAAc;AAId,MAAM,aAAa;AAAA,EACxB,WAAW;AAAA,EACX,QAAQ;AAAA,EACR,UAAU,CAAA;AAAA,EACV,OAAO;AAAA,IACL,IAAI,EAAE,IAAI,IAAI,MAAM,sBAAA;AAAA,IACpB,IAAI,EAAE,IAAI,IAAI,MAAM,+BAAA;AAAA,IACpB,IAAI,EAAE,IAAI,IAAI,MAAM,wBAAA;AAAA,EAAwB;AAAA,EAE9C,QAAQ,CAAC,WAAW,SAAS,UAAU,iBAAiB,UAAU;AAAA,EAClE,QAAQ;AAAA,IACN,IAAI,CAAC,YAAY,cAAc,gBAAgB,YAAY;AAAA,IAC3D,IAAI,CAAA;AAAA,IACJ,MAAM,CAAA;AAAA,EAAC;AAEX;"}
+{"version":3,"file":"slider.js","sources":["../../../src/components/Slider/slider.tsx"],"sourcesContent":["import * as React from 'react'\nimport * as SliderPrimitive from '@radix-ui/react-slider'\nimport { cva, type VariantProps } from 'class-variance-authority'\nimport { cn } from '@/lib/utils'\nimport { useFieldContext, useResolvedFieldDisabled, useResolvedFieldMode } from '@/design-system/components/Field/field-context'\n\n/**\n * Slider — 數值範圍選取器\n *\n * 基於 Radix Slider primitive,橋接設計系統 token。詳細設計原則見 `slider.spec.md`。\n *\n * ── 核心設計 ──\n * 1. **視覺單一**:track 厚度、thumb 直徑、thumb 邊框都是固定值,不隨 `size` 變\n * 2. **`size` 只控容器外高**:對齊 Field family 的 `h-field-*` tier,讓 Slider 能跟\n *    Input / NumberInput / Select 在 Field 內並排對齊\n * 3. **Range mode 免費**:Radix 原生支援 `value: number[]`,傳多值自動多 thumb\n * 4. **Hover / active 用 elevation 陰影**:不用色變,避免暗示「這是 button」\n */\n\nconst sliderRootVariants = cva(\n  // 容器外層:水平置中 + relative(Radix 會絕對定位內部元素)\n  // flex items-center 讓 track+thumb 在任何 field-height 下都垂直置中\n  //\n  // ── Disabled 策略:灰階 token swap(對齊 Button / Checkbox)──\n  // Slider 的藍色 range 是美學視覺,不是 semantic state——使用者從 disabled\n  // slider 需要辨識的是 thumb 位置 + range 長度,這兩者不依賴顏色。失去藍色\n  // 沒有資訊損失。\n  //\n  // 跟 Switch 的差別:Switch 的 on/off 是純顏色差異(沒有形狀差異),所以必須\n  // 靠 opacity 保留色彩身分。Slider 的位置/長度是形狀差異,不需要保留顏色身分,\n  // 跟 Checkbox(checkmark 形狀 = semantic 載體)同類,應該走灰階。\n  //\n  // 詳細判準見 `slider.spec.md` 的「Disabled 策略」章節。\n  [\n    'relative flex items-center w-full min-w-0 touch-none select-none',\n    'data-[disabled]:cursor-not-allowed',\n  ],\n  {\n    variants: {\n      size: {\n        sm: 'h-field-sm',\n        md: 'h-field-md',\n        lg: 'h-field-lg',\n      },\n    },\n    defaultVariants: {\n      size: 'md',\n    },\n  },\n)\n\nexport interface SliderProps\n  // 'orientation' 一併 Omit(2026-07-07 deep-audit A.1b 殘項):spec「不支援 vertical」宣稱的\n  // 型別面機械封鎖 — DS 樣式(track h-1 / w-full / items-center)假設 horizontal,透傳 vertical 壞版。\n  extends Omit<React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root>, 'children' | 'orientation'>,\n    VariantProps<typeof sliderRootVariants> {}\n\n// code-quality-allow: long-function — foundational composite(thumb-count 推導 + Field disabled 整合 + multi-mode render)\nconst Slider = React.forwardRef<\n  React.ElementRef<typeof SliderPrimitive.Root>,\n  SliderProps\n>(({ className, size, value, defaultValue, 'aria-label': ariaLabel, ...props }, ref) => {\n  // Field 家族整合:被 <Field mode=\"disabled\"> 包裹時自動 disabled(per slider.spec.md「Slider 作為 Field\n  // 家族整合時繼承其 canonical」)。Slider 已有完整 data-[disabled] 視覺,故只需把 fieldCtx disabled 接上。\n  // 2026-06-08 SSOT:讀 useResolvedFieldDisabled()(fieldCtx.disabled)→ <Field disabled> 與 <Field mode=\"disabled\"> 都生效\n  // 2026-06-12 補:<Field mode=\"readonly\"> → 鎖互動保留視覺(readonly ≠ disabled,不降色)\n  const fieldDisabled = useResolvedFieldDisabled()\n  const fieldMode = useResolvedFieldMode({ mode: undefined, disabled: undefined, readOnly: undefined })\n  const fieldReadonly = fieldMode === 'readonly'\n  // 2026-06-10 a11y:Field 內 Slider thumb(role=slider)無 accessible name(deep-audit axe 抓 aria-input-field-name)\n  // → 預設接 FieldLabel(aria-labelledby),consumer ariaLabel 優先。對齊 rating/time-picker labelId 接線。\n  const fieldLabelId = useFieldContext()?.labelId\n  // Degenerate-input 硬化(2026-07 deep-audit d7i20 / d8i7):value / defaultValue 傳空陣列\n  // 時,Radix 無對應值 → thumb display:none,留下沒有可操作 thumb 的空軌道。正規化為 `[min]`\n  // (min 未傳時 Radix 預設 0),保證至少一個坐落在 min 的可操作 thumb —— 對齊 spec API\n  //「value / defaultValue 必為非空陣列」契約,且不影響任何有效輸入。\n  const minValue = (props as { min?: number }).min ?? 0\n  const safeValue =\n    Array.isArray(value) && value.length === 0 ? [minValue] : value\n  const safeDefaultValue =\n    Array.isArray(defaultValue) && defaultValue.length === 0 ? [minValue] : defaultValue\n  // 推導要渲染幾個 thumb:controlled 用 value,uncontrolled 用 defaultValue,\n  // 都沒有時 fallback 單 thumb(Radix 預設行為)\n  const thumbCount =\n    (Array.isArray(safeValue) && safeValue.length) ||\n    (Array.isArray(safeDefaultValue) && safeDefaultValue.length) ||\n    1\n\n  return (\n    <SliderPrimitive.Root\n      ref={ref}\n      value={safeValue}\n      defaultValue={safeDefaultValue}\n      className={cn(sliderRootVariants({ size }), fieldReadonly && 'pointer-events-none', className)}\n      {...props}\n      disabled={(props as { disabled?: boolean }).disabled || fieldDisabled}\n      // <Field mode=\"readonly\"> cascade(2026-06-12 補):鎖互動、保留正常視覺(readonly\n      // 不降色;值仍可讀)。pointer-events-none 擋滑鼠,thumb tabIndex=-1 擋鍵盤。\n      data-readonly={fieldReadonly || undefined}\n    >\n      {/*\n        Track — rest 用 bg-secondary(n-3,「微淡可辨」),disabled 用 bg-muted(n-2,退化)。\n        跟 Tag neutral / Badge low 同家族。\n      */}\n      <SliderPrimitive.Track className={cn(\n        'relative grow overflow-hidden rounded-full h-1',\n        // Rest:bg-secondary(n-3,「微淡可辨」的 subtle fill,跟 Tag neutral / Badge low 同級)\n        // Disabled:bg-muted(n-2,「disabled-like 退化」底色)\n        'bg-secondary data-[disabled]:bg-muted',\n      )}>\n        {/*\n          Range — 填滿段。\n\n          ── Range 色 = Thumb border 色(語意一致) ──\n          Rest 兩者都是 `primary`,disabled 兩者都是 `border`(n-5)。為什麼要一致?\n          Range 是「填充視覺」,Thumb border 是「thumb 的輪廓線」——視覺上 thumb\n          的 border 剛好是 range 的延續(thumb 坐落在 range 的端點上,border 跟\n          range 在色彩上融為一體,看起來像「range 包住 thumb」而不是「thumb 浮在\n          range 上」)。兩個 token 綁在一起 —— **同色綁定 scope = rest 與 disabled 兩態**;\n          互動態(hover/active/focus)只動 thumb border 色階,range 填色恆 primary\n          (詳下方 Thumb 註解 2026-07-06 retract)。\n        */}\n        <SliderPrimitive.Range\n          className={cn(\n            'absolute h-full bg-primary',\n            'data-[disabled]:bg-border',\n          )}\n        />\n      </SliderPrimitive.Track>\n\n      {/*\n        Thumb — N 個(由 thumbCount 決定)。\n        白底 + 2px 邊框,邊框色 = Range 色(**一致綁定**):\n          - Rest: `border-primary` ↔ Range `bg-primary`\n          - Disabled: `border-border` ↔ Range `bg-border`\n        這個一致性讓 thumb border 跟 range 融為一體,看起來像「range 包住 thumb」\n        的連續視覺。**同色綁定 scope = rest 與 disabled 兩態**;互動態(hover/active/focus)\n        只動 thumb border 色階(+ elevation),range 填色恆定 —— 2026-07-06 修正原\n        「不論 state 永遠同色」過度宣稱(hover/active 一直都只動 thumb,claim 與 code 不符)。\n\n        **Thumb bg 兩態(2026-06-12 user 拍板,深色模式破洞修正)**:\n          - Rest/hover/active:`bg-on-emphasis`(固定白、深淺主題不反轉)— 對齊自家\n            Switch thumb(switch.tsx bg-on-emphasis)+ Radix Themes(thumb 字面 white\n            無 dark override)+ Apple iOS(深色模式旋鈕仍白)。原 `bg-surface` 在深色\n            = 8% 白半透明 → thumb 變深色破洞且 track 穿透。\n          - Disabled:`bg-canvas`(不透明頁面背景色)— 沉回背景表達「不可動」,\n            = Radix disabled thumb 用 gray-1(app background)同款;不透明故 track\n            不穿透。不可用 bg-muted(曾踩 thumb 跟 track 同色融合 bug;canvas 與\n            track 的 muted 隔 n-5 邊框 + 不同值,不融)。\n      */}\n      {Array.from({ length: thumbCount }).map((_, i) => (\n        <SliderPrimitive.Thumb\n          key={i}\n          tabIndex={fieldReadonly ? -1 : undefined}\n          aria-readonly={fieldReadonly || undefined}\n          className={cn(\n            'block h-4 w-4 shrink-0 rounded-full cursor-grab',\n            'bg-on-emphasis border-2 border-primary',\n            'transition-all duration-150 motion-reduce:duration-0',\n            // Hover:border 升 hover 階(light mode 淺一階 lift,= Button primary hover 變色邏輯)\n            // + elevation 陰影。2026-07-06 修語:原註解寫「加深」但 primary-hover 比 base 淺,\n            // 措辭與 token 相反 — token 不遷就錯註解,註解修正。\n            'hover:border-primary-hover hover:[box-shadow:var(--elevation-100)]',\n            // Active(按壓拖曳):深一階 primary-active(= Button active 邏輯 button.tsx active:*-active\n            // 對照組;原誤用 hover 階 = 全 DS 唯一 active-用-hover 偏移,2026-07-06 雙向全掃修正)\n            'active:cursor-grabbing active:border-primary-active active:[box-shadow:var(--elevation-200)]',\n            // Focus:跟 hover 同視覺(hover 階),不加 ring 或 halo\n            'outline-none focus-visible:border-primary-hover',\n            // Disabled:border 跟 Range 一起退成 border(n-5),bg 沉回 canvas(不透明背景色)\n            'data-[disabled]:cursor-not-allowed data-[disabled]:border-border data-[disabled]:bg-canvas',\n            'data-[disabled]:hover:[box-shadow:none]',\n          )}\n          // aria-label 策略(對齊 WAI-ARIA APG multi-thumb slider + Radix 原生語意標籤):\n          //   - consumer 傳 ariaLabel:單 thumb → 原樣;多 thumb → `{label} (N)` 區分\n          //   - 沒傳 ariaLabel:回傳 undefined,讓 Radix getLabel 提供語意標籤\n          //     (2 thumb → Minimum/Maximum;>2 thumb → Value N of M;單 thumb → 無)\n          //     比硬寫 `Thumb N` 更語意化,且讓「繼承 Radix a11y 預設」名實相符\n          aria-label={\n            ariaLabel\n              ? thumbCount > 1\n                ? `${ariaLabel} (${i + 1})`\n                : ariaLabel\n              : undefined\n          }\n          aria-labelledby={!ariaLabel && fieldLabelId ? fieldLabelId : undefined}\n        />\n      ))}\n    </SliderPrimitive.Root>\n  )\n})\nSlider.displayName = 'Slider'\n\n// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)\n// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs\nexport const sliderMeta = {\n  component: 'Slider',\n  family: null, // self-contained(對齊 spec;同 rating.tsx 慣例),\n  variants: {},\n  // size 只控容器外高,對齊 Field family h-field-*(md density:28/32/36px,uiSize.css)。\n  // track 厚度 / thumb 直徑固定不隨 size 變,故無 iconSize / typography。\n  // fieldHeight key 對齊 compile-stories.mjs 消費 schema(同 Button/Checkbox/Switch)。\n  sizes: {\n    sm: { fieldHeight: 28, when: 'Toolbar / inline 編輯' },\n    md: { fieldHeight: 32, when: '預設 — Form / cell inline edit' },\n    lg: { fieldHeight: 36, when: 'Marketing / 高 touch 區' },\n  },\n  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],\n  tokens: {\n    bg: ['bg-muted', 'bg-primary', 'bg-secondary', 'bg-on-emphasis', 'bg-canvas'],\n    fg: [],\n    ring: [],\n  },\n} as const\n\nexport { Slider, sliderRootVariants }\n"],"names":[],"mappings":"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"}

package/dist/components/Steps/index.d.ts

@@ -0,0 +1,2 @@
+export * from './steps';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/Steps/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/Steps/index.ts"],"names":[],"mappings":"AAIA,cAAc,SAAS,CAAA"}

package/dist/components/Steps/index.js

@@ -0,0 +1,12 @@
+import { StepContent, StepDescription, StepItem, StepLabel, Steps, stepItemVariants, stepsMeta, stepsRootVariants } from "./steps.js";
+export {
+  StepContent,
+  StepDescription,
+  StepItem,
+  StepLabel,
+  Steps,
+  stepItemVariants,
+  stepsMeta,
+  stepsRootVariants
+};
+//# sourceMappingURL=index.js.map

package/dist/components/Steps/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/components/Steps/steps.d.ts

@@ -18,12 +18,14 @@ export interface StepsProps extends Omit<React.HTMLAttributes<HTMLOListElement>,
     orientation?: StepsOrientation;
     expansion?: StepsExpansion;
     defaultExpanded?: 'all' | 'none' | string[];
+    /** Controlled 展開集合(2026-07-18 user 拍板補完整雙向控制,對齊 TreeView expandedIds + Radix/MUI/Ant Accordion)。
+     *  傳入則由 consumer 掌控展開狀態(與 `defaultExpanded` 二選一);toggle 時經 `onExpandedChange` 回寫。 */
+    expanded?: string[];
+    /** Controlled 展開變更回呼(展開/收合 step 時觸發,回傳新的展開值陣列)。 */
+    onExpandedChange?: (expanded: string[]) => void;
 }
 declare const Steps: React.ForwardRefExoticComponent<StepsProps & React.RefAttributes<HTMLOListElement>>;
-interface StepItemInjectedProps {
-    __isLast?: boolean;
-}
-export interface StepItemProps extends Omit<React.HTMLAttributes<HTMLLIElement>, 'value'>, StepItemInjectedProps {
+export interface StepItemProps extends Omit<React.HTMLAttributes<HTMLLIElement>, 'value'> {
     value: string;
     state?: 'error';
     disabled?: boolean;
@@ -60,9 +62,9 @@ export declare const stepsMeta: {
             readonly when: "Marketing 流程展示 / 重要 onboarding;indicator 32px circle";
         };
     };
-    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly states: readonly ["upcoming", "reachable", "current", "completed", "error"];
     readonly tokens: {
-        readonly bg: readonly ["bg-primary"];
+        readonly bg: readonly ["bg-info"];
         readonly fg: readonly ["--fg-disabled", "--foreground", "--on-emphasis", "text-error-text", "text-fg-disabled", "text-fg-muted", "text-fg-secondary", "text-foreground"];
         readonly ring: readonly [];
     };

package/dist/components/Steps/steps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../../../src/components/Steps/steps.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,EAAO,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAKjE,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAE1C,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,YAAY,CAAA;AACxD,MAAM,MAAM,cAAc,GAAG,eAAe,GAAG,UAAU,CAAA;AACzD,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,OAAO,CAAA;AA2I3F,QAAA,MAAM,iBAAiB;;8EAQrB,CAAA;AAEF,MAAM,WAAW,UACf,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC,EAAE,UAAU,GAAG,cAAc,CAAC,EAC/E,YAAY,CAAC,OAAO,iBAAiB,CAAC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;IAC1B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,WAAW,CAAC,EAAE,gBAAgB,CAAA;IAC9B,SAAS,CAAC,EAAE,cAAc,CAAA;IAC1B,eAAe,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,EAAE,CAAA;CAC5C;AAGD,QAAA,MAAM,KAAK,qFAsHV,CAAA;AAKD,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,aACf,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,EACxD,qBAAqB;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,QAAA,MAAM,gBAAgB;;;8EAgBpB,CAAA;AAGF,QAAA,MAAM,QAAQ,qFA8Db,CAAA;AA2VD,MAAM,WAAW,cAAe,SAAQ,KAAK,CAAC,cAAc,CAAC,eAAe,CAAC;CAAG;AAGhF,QAAA,MAAM,SAAS,wFA0Bd,CAAA;AAKD,MAAM,WAAW,oBAAqB,SAAQ,KAAK,CAAC,cAAc,CAAC,eAAe,CAAC;CAAG;AAEtF,QAAA,MAAM,eAAe,8FA2BpB,CAAA;AAKD,MAAM,WAAW,gBAAiB,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;CAAG;AAEjF,QAAA,MAAM,WAAW,yFAchB,CAAA;AAOD,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;CAeZ,CAAA;AAEV,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,CAAA"}
+{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../../../src/components/Steps/steps.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,EAAO,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAMjE,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAE1C,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,YAAY,CAAA;AACxD,MAAM,MAAM,cAAc,GAAG,eAAe,GAAG,UAAU,CAAA;AACzD,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,GAAG,WAAW,GAAG,OAAO,CAAA;AA4I3F,QAAA,MAAM,iBAAiB;;8EAQrB,CAAA;AAEF,MAAM,WAAW,UACf,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,gBAAgB,CAAC,EAAE,UAAU,GAAG,cAAc,CAAC,EAC/E,YAAY,CAAC,OAAO,iBAAiB,CAAC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;IAC1B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,WAAW,CAAC,EAAE,gBAAgB,CAAA;IAC9B,SAAS,CAAC,EAAE,cAAc,CAAA;IAC1B,eAAe,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,EAAE,CAAA;IAC3C;yFACqF;IACrF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,IAAI,CAAA;CAChD;AAGD,QAAA,MAAM,KAAK,qFAuIV,CAAA;AAYD,MAAM,WAAW,aACf,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAC1D,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,QAAA,MAAM,gBAAgB;;;8EAgBpB,CAAA;AAGF,QAAA,MAAM,QAAQ,qFAiEb,CAAA;AA0XD,MAAM,WAAW,cAAe,SAAQ,KAAK,CAAC,cAAc,CAAC,eAAe,CAAC;CAAG;AAGhF,QAAA,MAAM,SAAS,wFA4Bd,CAAA;AAKD,MAAM,WAAW,oBAAqB,SAAQ,KAAK,CAAC,cAAc,CAAC,eAAe,CAAC;CAAG;AAEtF,QAAA,MAAM,eAAe,8FA2BpB,CAAA;AAKD,MAAM,WAAW,gBAAiB,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;CAAG;AAEjF,QAAA,MAAM,WAAW,yFAchB,CAAA;AAOD,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;CAeZ,CAAA;AAEV,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,CAAA"}

package/dist/components/Steps/steps.js

@@ -3,6 +3,7 @@ import * as React from "react";
 import { ChevronDown, Check, X } from "lucide-react";
 import { cva } from "class-variance-authority";
 import { cn } from "../../lib/utils.js";
+import { ItemPrefix, ItemSuffix } from "../../patterns/element-anatomy/item-anatomy.js";
 const INDICATOR_SIZE = {
   sm: 8,
   md: 24,
@@ -27,7 +28,7 @@ function getOuterRingShadow(ringColor) {
 function resolveRingColor(state, linear) {
   if (state === "error") return "var(--error-hover)";
   if (state === "current" && !linear) return "var(--border-hover)";
-  return "var(--primary-hover)";
+  return "var(--info-hover)";
 }
 const StepsContext = React.createContext(null);
 function useStepsContext() {
@@ -92,6 +93,8 @@ const Steps = React.forwardRef(
     orientation = "vertical",
     expansion = "follow-active",
     defaultExpanded,
+    expanded: expandedProp,
+    onExpandedChange,
     className,
     children,
     ...props
@@ -119,17 +122,29 @@ const Steps = React.forwardRef(
       () => computeReachableValues(childValues, completedValues),
       [childValues, completedValues]
     );
-    const [expandedSet, setExpandedSet] = React.useState(
+    const isExpandedControlled = expandedProp !== void 0;
+    const [expandedInternal, setExpandedInternal] = React.useState(
       () => normalizeExpanded(defaultExpanded, childValues)
     );
+    const expandedSet = isExpandedControlled ? new Set(expandedProp) : expandedInternal;
     const toggleExpanded = React.useCallback((itemValue) => {
-      setExpandedSet((prev) => {
+      const compute = (prev) => {
         const next = new Set(prev);
         if (next.has(itemValue)) next.delete(itemValue);
         else next.add(itemValue);
         return next;
-      });
-    }, []);
+      };
+      if (isExpandedControlled) {
+        onExpandedChange == null ? void 0 : onExpandedChange([...compute(new Set(expandedProp))]);
+      } else {
+        setExpandedInternal((prev) => {
+          const next = compute(prev);
+          onExpandedChange == null ? void 0 : onExpandedChange([...next]);
+          return next;
+        });
+      }
+    }, [isExpandedControlled, expandedProp, onExpandedChange]);
+    const stepCount = React.Children.count(children);
     const ctxValue = React.useMemo(
       () => ({
         value,
@@ -142,11 +157,12 @@ const Steps = React.forwardRef(
         expansion,
         expandedSet,
         setValue,
-        toggleExpanded
+        toggleExpanded,
+        total: stepCount
       }),
-      [value, completedValues, errorValues, reachableValues, linear, size, orientation, expansion, expandedSet, setValue, toggleExpanded]
+      [value, completedValues, errorValues, reachableValues, linear, size, orientation, expansion, expandedSet, setValue, toggleExpanded, stepCount]
     );
-    const count = React.Children.count(children);
+    const count = stepCount;
     const itemsWithIndex = [];
     React.Children.forEach(children, (child, index) => {
       if (!React.isValidElement(child)) {
@@ -194,7 +210,8 @@ const stepItemVariants = cva("group/step-item outline-none", {
   defaultVariants: { orientation: "vertical", size: "md" }
 });
 const StepItem = React.forwardRef(
-  ({ value, state: stateOverride, disabled = false, children, className, __isLast = false, ...props }, ref) => {
+  ({ value, state: stateOverride, disabled = false, children, className, ...restProps }, ref) => {
+    const { __isLast = false, ...props } = restProps;
     const steps = useStepsContext();
     const state = computeState(
       value,
@@ -266,8 +283,17 @@ function StepItemLayout({ children }) {
   }
   return /* @__PURE__ */ jsx(VerticalLayout, { label: labelNode, description: descNode, content: contentNode, isLast: item.isLast });
 }
-function StepItemHeader({ children, className, style }) {
+const STEP_STATUS_TEXT = {
+  completed: "已完成",
+  current: "進行中",
+  error: "錯誤",
+  reachable: "未開始",
+  upcoming: "未開始"
+};
+function StepItemHeader({ children, className, style, contentId }) {
   const item = useStepItemContext();
+  const steps = useStepsContext();
+  const index = React.useContext(StepIndexContext);
   const onKeyDown = (e) => {
     if (!item.clickable) return;
     if (e.key === "Enter" || e.key === " ") {
@@ -275,7 +301,7 @@ function StepItemHeader({ children, className, style }) {
       item.activate();
     }
   };
-  return /* @__PURE__ */ jsx(
+  return /* @__PURE__ */ jsxs(
     "div",
     {
       role: item.clickable ? "button" : void 0,
@@ -283,13 +309,22 @@ function StepItemHeader({ children, className, style }) {
       onClick: item.clickable ? item.activate : void 0,
       onKeyDown: item.clickable ? onKeyDown : void 0,
       "aria-disabled": item.disabled || void 0,
+      "aria-expanded": item.clickable && contentId ? item.expanded : void 0,
+      "aria-controls": item.clickable && contentId && item.expanded ? contentId : void 0,
       className: cn(
-        "outline-none",
+        // leading-compact:scanning-family header 行高 = 1.3(item-anatomy.spec.md:776 掃描模式 label 行高)。
+        // 設在 header 而非 li 根 → prefix h-[1lh] + 水平 connector h-[1lh] + label(StepLabel 亦 leading-compact)
+        // 全用 1.3 對齊;li 根 text-body(1.5,steps.tsx:329-331)留給展開 content 的 reading 行高,不被
+        // scanning 波及(避免 改A壞B)。對齊 MenuItem 把 leading-compact 放 row 容器之原則(item-anatomy.tsx:144-146)。
+        "outline-none leading-compact",
         item.clickable ? "cursor-pointer rounded-md focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring" : "cursor-not-allowed",
         className
       ),
       style,
-      children
+      children: [
+        /* @__PURE__ */ jsx("span", { className: "sr-only", children: `第 ${index} 步,共 ${steps.total} 步,${STEP_STATUS_TEXT[item.state]}` }),
+        children
+      ]
     }
   );
 }
@@ -303,27 +338,28 @@ function VerticalLayout({
   const item = useStepItemContext();
   const showContent = !!content && item.expanded;
   const indicatorBox = INDICATOR_BOX_WIDTH[steps.size];
+  const contentId = React.useId();
   return /* @__PURE__ */ jsxs(Fragment, { children: [
-    /* @__PURE__ */ jsxs(StepItemHeader, { className: "flex items-start gap-3", children: [
-      /* @__PURE__ */ jsx("div", { className: "shrink-0", style: { width: indicatorBox }, children: /* @__PURE__ */ jsx("div", { className: "h-[1lh] flex items-center justify-center", children: /* @__PURE__ */ jsx(StepIndicator, {}) }) }),
-      /* @__PURE__ */ jsxs("div", { className: "flex-1 min-w-0 flex items-start", children: [
+    /* @__PURE__ */ jsxs(StepItemHeader, { className: "flex items-start gap-3", contentId: content ? contentId : void 0, children: [
+      /* @__PURE__ */ jsx(ItemPrefix, { style: { width: indicatorBox }, children: /* @__PURE__ */ jsx(StepIndicator, {}) }),
+      /* @__PURE__ */ jsxs("div", { className: "flex-1 min-w-0 flex items-start gap-2", children: [
         /* @__PURE__ */ jsxs("div", { className: "flex-1 min-w-0 flex flex-col", children: [
           label,
           description
         ] }),
-        steps.expansion === "multiple" && !!content && /* @__PURE__ */ jsx("span", { "aria-hidden": true, className: "h-[1lh] flex items-center shrink-0 ml-2", children: /* @__PURE__ */ jsx(
+        steps.expansion === "multiple" && !!content && /* @__PURE__ */ jsx(ItemSuffix, { "aria-hidden": true, children: /* @__PURE__ */ jsx(
           ChevronDown,
           {
             size: 16,
             className: cn(
-              "text-fg-muted transition-transform duration-150",
+              "text-fg-muted transition-transform duration-150 motion-reduce:duration-0",
               item.expanded && "rotate-180"
             )
           }
         ) })
       ] })
     ] }),
-    showContent && /* @__PURE__ */ jsxs("div", { className: "flex items-start gap-3 mt-3", children: [
+    showContent && /* @__PURE__ */ jsxs("div", { id: contentId, className: "flex items-start gap-3 mt-3", children: [
       /* @__PURE__ */ jsx("div", { className: "shrink-0", style: { width: indicatorBox } }),
       /* @__PURE__ */ jsx("div", { className: "flex-1 min-w-0", children: content })
     ] }),
@@ -341,8 +377,10 @@ function VerticalConnectorLine() {
     {
       "aria-hidden": true,
       className: cn(
-        "absolute w-px",
-        isBlue ? "bg-primary" : "bg-border"
+        // leading-compact:connector 的 0.5lh 須跟 scanning label 同行高(1.3)→ 起點對齊 circle 中心
+        // (circle 對齊 label 第一行;label 已 leading-compact)。否則 connector 繼承 li 根 1.5 → 0.5lh 偏大 → 起點偏低。
+        "absolute w-px leading-compact",
+        isBlue ? "bg-info" : "bg-border"
       ),
       style: {
         left: INDICATOR_BOX_WIDTH[steps.size] / 2,
@@ -362,9 +400,9 @@ function HorizontalLayout({
   const indicatorBox = INDICATOR_BOX_WIDTH[steps.size];
   return /* @__PURE__ */ jsxs(Fragment, { children: [
     /* @__PURE__ */ jsxs(StepItemHeader, { className: "flex items-start gap-3", children: [
-      /* @__PURE__ */ jsx("div", { className: "h-[1lh] flex items-center shrink-0", children: /* @__PURE__ */ jsx(StepIndicator, {}) }),
+      /* @__PURE__ */ jsx(ItemPrefix, { children: /* @__PURE__ */ jsx(StepIndicator, {}) }),
       /* @__PURE__ */ jsx("div", { className: "shrink-0 min-w-0", children: label }),
-      !item.isLast && /* @__PURE__ */ jsx("div", { className: "h-[1lh] flex-1 flex items-center min-w-4", "aria-hidden": true, children: /* @__PURE__ */ jsx("div", { className: cn("h-px w-full", isBlue ? "bg-primary" : "bg-border") }) })
+      !item.isLast && /* @__PURE__ */ jsx("div", { className: "h-[1lh] flex-1 flex items-center min-w-4", "aria-hidden": true, children: /* @__PURE__ */ jsx("div", { className: cn("h-px w-full", isBlue ? "bg-info" : "bg-border") }) })
     ] }),
     description && /* @__PURE__ */ jsx("div", { className: "min-w-0", style: { paddingLeft: indicatorBox + 12 }, children: description })
   ] });
@@ -390,11 +428,11 @@ function SmIndicator({
       width: INDICATOR_SIZE.sm,
       height: INDICATOR_SIZE.sm,
       background: "transparent",
-      border: "2px solid var(--primary-hover)",
+      border: "2px solid var(--info-hover)",
       boxShadow: focused ? getOuterRingShadow(resolveRingColor(state, linear)) : void 0
     };
   } else {
-    const dotBg = state === "completed" ? "var(--primary)" : state === "error" ? "var(--error)" : state === "current" && !linear ? "var(--fg-disabled)" : "var(--fg-disabled)";
+    const dotBg = state === "completed" ? "var(--info)" : state === "error" ? "var(--error)" : state === "current" && !linear ? "var(--fg-disabled)" : "var(--fg-disabled)";
     dotStyle = {
       width: INDICATOR_SIZE.sm,
       height: INDICATOR_SIZE.sm,
@@ -435,12 +473,12 @@ function MdLgIndicator({
       contentColor = "var(--on-emphasis)";
       break;
     case "completed":
-      fillBg = "var(--primary)";
+      fillBg = "var(--info)";
       contentColor = "var(--on-emphasis)";
       break;
     case "current":
       if (linear) {
-        fillBg = "var(--primary)";
+        fillBg = "var(--info)";
         contentColor = "var(--on-emphasis)";
       } else {
         fillBg = "var(--secondary)";
@@ -448,7 +486,7 @@ function MdLgIndicator({
       }
       break;
     case "reachable":
-      fillBg = "var(--primary)";
+      fillBg = "var(--info)";
       contentColor = "var(--on-emphasis)";
       break;
     default:
@@ -475,7 +513,8 @@ function MdLgIndicator({
         height: diameter,
         background: fillBg,
         color: contentColor,
-        fontSize: size === "lg" ? "var(--font-body-size)" : "var(--font-caption-size)",
+        // 2026-06-11 R2:對齊 spec canonical「indicator 數字與 label 同級」(steps.spec.md 狀態表 md=14/lg=16;spec 明文「之前寫小一號(md=12,lg=14)是錯的」)
+        fontSize: size === "lg" ? "var(--font-body-lg-size)" : "var(--font-body-size)",
         boxShadow: focused ? getOuterRingShadow(resolveRingColor(state, linear)) : void 0
       },
       children: /* @__PURE__ */ jsx(IndicatorContent, { state, iconPx })
@@ -500,7 +539,9 @@ const StepLabel = React.forwardRef(
       {
         ref,
         className: cn(
-          "font-medium break-words",
+          // leading-compact:scanning-family label 行高 = 1.3(item-anatomy.spec.md:776);text-body utility
+          // 自帶 lh:1.5,須顯式 leading-compact 蓋回 1.3,跟 MenuItem label(實測 14px/18px=1.3)一致。
+          "font-medium break-words leading-compact",
           size === "lg" ? "text-body-lg" : "text-body",
           disabled ? "text-fg-disabled" : state === "error" ? "text-error-text" : focused ? "text-foreground" : "text-fg-secondary",
           className
@@ -563,9 +604,10 @@ const stepsMeta = {
     md: { px: 24, when: "預設 — wizard / checkout / 註冊主流程;indicator 24px circle" },
     lg: { px: 32, when: "Marketing 流程展示 / 重要 onboarding;indicator 32px circle" }
   },
-  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  states: ["upcoming", "reachable", "current", "completed", "error"],
+  // 2026-06-11 R2:content-state 模型(spec 狀態表),非 Phase-1 boilerplate 互動 states,
   tokens: {
-    bg: ["bg-primary"],
+    bg: ["bg-info"],
     fg: ["--fg-disabled", "--foreground", "--on-emphasis", "text-error-text", "text-fg-disabled", "text-fg-muted", "text-fg-secondary", "text-foreground"],
     ring: []
   }