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

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

@@ -0,0 +1,306 @@
+// @story-history: AllSizes retired 2026-05-15(anatomy SizeMatrix own size matrix);
+//   AllStates retired 2026-05-17 per audit Dim 46(anatomy StateBehavior own state matrix,
+//   manual trait grid 違 story-rules.md 三層定位「展示層 = 典型使用情境,不是 trait grid」)。
+import * as React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { expect, within } from '@storybook/test'
+import { Check } from 'lucide-react'
+import {
+  Steps,
+  StepItem,
+  StepLabel,
+  StepDescription,
+  StepContent,
+} from './steps'
+import { Button } from '@/design-system/components/Button/button'
+
+const meta: Meta<typeof Steps> = {
+  title: 'Design System/Components/Steps/展示',
+  tags: ['autodocs'],
+  component: Steps,
+  parameters: {
+    layout: 'padded',
+    docs: { description: { component: '呈現有固定順序的多步驟流程、目前位置與完成狀態，可搭配逐步內容。使用者必須依序完成設定、申請或結帳時使用；平行內容切換改用 Tabs。' } },
+  },
+}
+export default meta
+
+type Story = StoryObj<typeof Steps>
+
+// ── 典型 wizard ──────────────────────────────────────────────────────────
+
+export const Default: Story = {
+  name: '預設',
+  render: () => {
+    const [value, setValue] = React.useState('info')
+    const [completed, setCompleted] = React.useState<string[]>([])
+    const [submitted, setSubmitted] = React.useState(false)
+
+    const advance = () => {
+      const nextMap: Record<string, string> = { info: 'account', account: 'review' }
+      setCompleted(prev => Array.from(new Set([...prev, value])))
+      const next = nextMap[value]
+      if (next) setValue(next)
+    }
+    const back = () => {
+      const prevMap: Record<string, string> = { account: 'info', review: 'account' }
+      const prev = prevMap[value]
+      if (prev) setValue(prev)
+    }
+    const submit = () => {
+      setCompleted(prev => Array.from(new Set([...prev, 'review'])))
+      setSubmitted(true)
+    }
+    const reset = () => {
+      setValue('info')
+      setCompleted([])
+      setSubmitted(false)
+    }
+
+    // ── Pattern A:submit 在最後一步,送出後整個 wizard 替換成 success banner ──
+    // Pattern A:最後一步 submit 按下後 stepper 不再顯示,整個 wizard 替換成
+    // success card;「再填一份申請」是成功頁的真實產品 action(Google Forms
+    // 「Submit another response」同款,https://support.google.com/docs/answer/2839588),
+    // 非 demo 治具。
+    if (submitted) {
+      return (
+        <div className="w-[480px] flex flex-col gap-4 p-6 bg-muted rounded-md border border-border">
+          <div className="flex items-center gap-3">
+            <span className="h-8 w-8 rounded-full bg-info flex items-center justify-center shrink-0">
+              <Check className="text-white" size={20} strokeWidth={2.5} aria-hidden />
+            </span>
+            <span className="text-body-lg font-medium text-foreground">
+              已成功送出申請
+            </span>
+          </div>
+          <p className="text-body text-fg-secondary">
+            我們會盡快處理,結果將寄送至您的電子信箱。
+          </p>
+          <div>
+            <Button variant="secondary" onClick={reset}>
+              再填一份申請
+            </Button>
+          </div>
+        </div>
+      )
+    }
+
+    return (
+      <div className="w-[480px]">
+        <Steps
+          value={value}
+          onValueChange={setValue}
+          completedValues={completed}
+        >
+          <StepItem value="info">
+            <StepLabel>基本資料</StepLabel>
+            <StepDescription>填寫姓名與聯絡方式</StepDescription>
+            <StepContent>
+              <div className="flex flex-col gap-3">
+                <p className="text-body text-fg-secondary">
+                  請輸入你的姓名、電子郵件與電話。
+                </p>
+                <div className="flex gap-2">
+                  <Button variant="primary" onClick={advance}>下一步</Button>
+                </div>
+              </div>
+            </StepContent>
+          </StepItem>
+
+          <StepItem value="account">
+            <StepLabel>帳號設定</StepLabel>
+            <StepDescription>選擇使用者名稱與密碼</StepDescription>
+            <StepContent>
+              <div className="flex flex-col gap-3">
+                <p className="text-body text-fg-secondary">
+                  設定登入帳號。使用者名稱至少 3 個字元。
+                </p>
+                <div className="flex gap-2">
+                  <Button variant="primary" onClick={advance}>下一步</Button>
+                  <Button variant="secondary" onClick={back}>
+                    上一步
+                  </Button>
+                </div>
+              </div>
+            </StepContent>
+          </StepItem>
+
+          <StepItem value="review">
+            <StepLabel>確認並送出</StepLabel>
+            <StepDescription>送出前最後檢查</StepDescription>
+            <StepContent>
+              <div className="flex flex-col gap-3">
+                <p className="text-body text-fg-secondary">
+                  請確認所有欄位正確,按下送出後系統會建立您的帳號。
+                </p>
+                <div className="flex gap-2">
+                  <Button variant="primary" onClick={submit}>送出</Button>
+                  <Button variant="secondary" onClick={back}>
+                    上一步
+                  </Button>
+                </div>
+              </div>
+            </StepContent>
+          </StepItem>
+        </Steps>
+      </div>
+    )
+  },
+}
+
+// @story-history: AllSizes + AllStates retired per F migration 2026-05-17 —
+//   AllSizes retired 2026-05-15(anatomy SizeMatrix own);AllStates retired 2026-05-17
+//   per Dim 46 audit(anatomy StateBehavior 已 own state matrix,manual trait grid 違反
+//   story-rules.md 三層定位「展示層應為典型使用情境,不是 trait grid」)。
+//   FocusRingCombinations retired 2026-07-17 per Dim 24 audit — ring⊥state 正交規則已由
+//   principles「規則:環是聚焦標記,不是選取」live own(completed+ring / error+ring 兩例);
+//   互動式聚焦移動於「預設」「非線性」既有 clickable steps 已可見,展示層不重複原則 grid。
+
+// ── Non-linear ──────────────────────────────────────────────────────────
+
+export const NonLinear: Story = {
+  name: '非線性',
+  render: () => {
+    const [value, setValue] = React.useState('overview')
+    return (
+      <div className="w-[360px]">
+        <Steps
+          value={value}
+          onValueChange={setValue}
+          completedValues={['overview']}
+          linear={false}
+        >
+          <StepItem value="overview">
+            <StepLabel>總覽</StepLabel>
+            <StepDescription>可隨時回看</StepDescription>
+          </StepItem>
+          <StepItem value="members">
+            <StepLabel>成員管理</StepLabel>
+            <StepDescription>新增 / 移除團隊成員</StepDescription>
+          </StepItem>
+          <StepItem value="billing">
+            <StepLabel>計費設定</StepLabel>
+            <StepDescription>付款方式</StepDescription>
+          </StepItem>
+          <StepItem value="integrations">
+            <StepLabel>整合</StepLabel>
+            <StepDescription>連接第三方服務</StepDescription>
+          </StepItem>
+        </Steps>
+      </div>
+    )
+  },
+}
+
+// ── Horizontal ──────────────────────────────────────────────────────────
+
+export const Horizontal: Story = {
+  name: '水平',
+  render: () => {
+    const [value, setValue] = React.useState('shipping')
+    return (
+      <div className="w-full max-w-3xl">
+        <Steps
+          value={value}
+          onValueChange={setValue}
+          completedValues={['cart', 'address']}
+          orientation="horizontal"
+        >
+          <StepItem value="cart">
+            <StepLabel>購物車</StepLabel>
+            <StepDescription>已確認</StepDescription>
+          </StepItem>
+          <StepItem value="address">
+            <StepLabel>寄送地址</StepLabel>
+            <StepDescription>已填寫</StepDescription>
+          </StepItem>
+          <StepItem value="shipping">
+            <StepLabel>運送方式</StepLabel>
+            <StepDescription>選擇配送</StepDescription>
+          </StepItem>
+          <StepItem value="payment">
+            <StepLabel>付款</StepLabel>
+            <StepDescription>信用卡 / Apple Pay</StepDescription>
+          </StepItem>
+          <StepItem value="done">
+            <StepLabel>完成</StepLabel>
+          </StepItem>
+        </Steps>
+      </div>
+    )
+  },
+}
+
+// ── Multiple expansion ─────────────────────────────────────────────────
+
+export const MultipleExpansion: Story = {
+  name: '多重展開模式',
+  render: () => (
+    <div className="w-[480px]">
+      <p className="text-caption text-fg-secondary mb-4">
+        點 step header 切換展開(並更新 value)。本例顯式傳 `defaultExpanded="all"` 全部展開起手(預設 `"none"`)。
+      </p>
+      <Steps
+        defaultValue="b"
+        completedValues={['a']}
+        expansion="multiple"
+        defaultExpanded="all"
+        linear={false}
+      >
+        <StepItem value="a">
+          <StepLabel>安裝套件</StepLabel>
+          <StepDescription>執行 npm install</StepDescription>
+          <StepContent>
+            <div className="max-w-full overflow-x-auto rounded-md bg-muted">
+              <pre className="text-caption p-3 whitespace-pre w-max">
+              npm install @qijenchen/design-system
+            </pre>
+            </div>
+          </StepContent>
+        </StepItem>
+        <StepItem value="b">
+          <StepLabel>匯入元件</StepLabel>
+          <StepDescription>從 design-system 引入</StepDescription>
+          <StepContent>
+            <div
+              tabIndex={0}
+              role="region"
+              aria-label="Steps 元件匯入範例程式碼"
+              className="max-w-full overflow-x-auto rounded-md bg-muted focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring"
+            >
+              <pre className="text-caption p-3 whitespace-pre w-max">
+              {"import { Steps } from '@/design-system/components/Steps/steps'"}
+            </pre>
+            </div>
+          </StepContent>
+        </StepItem>
+        <StepItem value="c">
+          <StepLabel>設定 provider</StepLabel>
+          <StepDescription>包在 App 最外層</StepDescription>
+          <StepContent>
+            <div className="max-w-full overflow-x-auto rounded-md bg-muted">
+              <pre className="text-caption p-3 whitespace-pre w-max">
+              {"<TooltipProvider>{children}</TooltipProvider>"}
+            </pre>
+            </div>
+          </StepContent>
+        </StepItem>
+      </Steps>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const scrollRegion = canvas.getByRole('region', {
+      name: 'Steps 元件匯入範例程式碼',
+    })
+
+    await expect(scrollRegion.scrollWidth).toBeGreaterThan(scrollRegion.clientWidth)
+    await expect(scrollRegion).toHaveAttribute('tabindex', '0')
+    scrollRegion.focus()
+    await expect(scrollRegion).toHaveFocus()
+  },
+}
+
+// @story-history: MixedDescription(欄節奏驗證 grid)retired 2026-06-11 per audit
+//   EXAMPLE_REDUNDANT — indicator 對齊 label 第一行的 column rhythm 已由 anatomy「欄位節奏」+
+//   principles「規則:指示欄節奏一致」雙層 own;展示層不重複 trait 驗證 grid。

package/src/components/Steps/steps.tsx

@@ -4,6 +4,7 @@ import * as React from 'react'
 import { Check, ChevronDown, X } from 'lucide-react'
 import { cva, type VariantProps } from 'class-variance-authority'
 import { cn } from '@/lib/utils'
+import { ItemPrefix, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
 
 // ── Types ─────────────────────────────────────────────────────────────────
 
@@ -47,7 +48,7 @@ function getOuterRingShadow(ringColor: string): string {
 function resolveRingColor(state: StepContentState, linear: boolean): string {
   if (state === 'error') return 'var(--error-hover)'
   if (state === 'current' && !linear) return 'var(--border-hover)'
-  return 'var(--primary-hover)'
+  return 'var(--info-hover)'
 }
 
 // ── Contexts ──────────────────────────────────────────────────────────────
@@ -64,6 +65,7 @@ interface StepsContextValue {
   expandedSet: Set<string>
   setValue: (value: string) => void
   toggleExpanded: (value: string) => void
+  total: number
 }
 
 const StepsContext = React.createContext<StepsContextValue | null>(null)
@@ -173,6 +175,11 @@ export interface StepsProps
   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
 }
 
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
@@ -189,6 +196,8 @@ const Steps = React.forwardRef<HTMLOListElement, StepsProps>(
       orientation = 'vertical',
       expansion = 'follow-active',
       defaultExpanded,
+      expanded: expandedProp,
+      onExpandedChange,
       className,
       children,
       ...props
@@ -227,18 +236,32 @@ const Steps = React.forwardRef<HTMLOListElement, StepsProps>(
       [childValues, completedValues],
     )
 
-    const [expandedSet, setExpandedSet] = React.useState<Set<string>>(() =>
+    // Controlled(expandedProp 傳入)/ uncontrolled(defaultExpanded 初值)dual-mode(2026-07-18)。
+    const isExpandedControlled = expandedProp !== undefined
+    const [expandedInternal, setExpandedInternal] = React.useState<Set<string>>(() =>
       normalizeExpanded(defaultExpanded, childValues),
     )
+    const expandedSet = isExpandedControlled ? new Set(expandedProp) : expandedInternal
 
     const toggleExpanded = React.useCallback((itemValue: string) => {
-      setExpandedSet(prev => {
+      const compute = (prev: Set<string>) => {
         const next = new Set(prev)
         if (next.has(itemValue)) next.delete(itemValue)
         else next.add(itemValue)
         return next
-      })
-    }, [])
+      }
+      if (isExpandedControlled) {
+        onExpandedChange?.([...compute(new Set(expandedProp))])
+      } else {
+        setExpandedInternal(prev => {
+          const next = compute(prev)
+          onExpandedChange?.([...next])
+          return next
+        })
+      }
+    }, [isExpandedControlled, expandedProp, onExpandedChange])
+
+    const stepCount = React.Children.count(children)
 
     const ctxValue = React.useMemo<StepsContextValue>(
       () => ({
@@ -253,12 +276,13 @@ const Steps = React.forwardRef<HTMLOListElement, StepsProps>(
         expandedSet,
         setValue,
         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],
     )
 
     // Interleave horizontal connectors between items
-    const count = React.Children.count(children)
+    const count = stepCount
     const itemsWithIndex: React.ReactNode[] = []
 
     React.Children.forEach(children, (child, index) => {
@@ -299,13 +323,15 @@ Steps.displayName = 'Steps'
 
 // ── StepItem ──────────────────────────────────────────────────────────────
 
+// Steps 內部 cloneElement 注入用的私有 props — 刻意「不」併入公開 StepItemProps:
+// dunder 內部欄位不進 root API(consumer 無合法理由手動控制末項 connector / 間距),
+// 也就不會被 barrel 匯出成公開型別。StepItem render body 以 intersection cast 內部讀取。
 interface StepItemInjectedProps {
   __isLast?: boolean
 }
 
 export interface StepItemProps
-  extends Omit<React.HTMLAttributes<HTMLLIElement>, 'value'>,
-    StepItemInjectedProps {
+  extends Omit<React.HTMLAttributes<HTMLLIElement>, 'value'> {
   value: string
   state?: 'error'
   disabled?: boolean
@@ -331,7 +357,10 @@ const stepItemVariants = cva('group/step-item outline-none', {
 
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 const StepItem = React.forwardRef<HTMLLIElement, StepItemProps>(
-  ({ value, state: stateOverride, disabled = false, children, className, __isLast = false, ...props }, ref) => {
+  ({ value, state: stateOverride, disabled = false, children, className, ...restProps }, ref) => {
+    // __isLast 由 Steps root 經 cloneElement 私下注入(見 StepItemInjectedProps);以 intersection
+    // cast 從 rest 讀出後解構掉,確保 dunder 不落到 DOM li,也不必污染公開 StepItemProps。
+    const { __isLast = false, ...props } = restProps as typeof restProps & StepItemInjectedProps
     const steps = useStepsContext()
     const state = computeState(
       value,
@@ -421,8 +450,20 @@ function StepItemLayout({ children }: { children: React.ReactNode }) {
 
 // ── Clickable header ─────────────────────────────────────────────────────
 
-function StepItemHeader({ children, className, style }: { children: React.ReactNode; className?: string; style?: React.CSSProperties }) {
+// SR-only 狀態文字 map(2026-06-01 #25 a11y:indicator 是 aria-hidden 純視覺,故「第 N 步/共 M 步/狀態」
+// 需經 sr-only span 給螢幕報讀器。對齊 Carbon ProgressIndicator `--assistive-text`(已完成/進行中/未開始)慣例)
+const STEP_STATUS_TEXT: Record<StepContentState, string> = {
+  completed: '已完成',
+  current: '進行中',
+  error: '錯誤',
+  reachable: '未開始',
+  upcoming: '未開始',
+}
+
+function StepItemHeader({ children, className, style, contentId }: { children: React.ReactNode; className?: string; style?: React.CSSProperties; contentId?: string }) {
   const item = useStepItemContext()
+  const steps = useStepsContext()
+  const index = React.useContext(StepIndexContext)
   const onKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
     if (!item.clickable) return
     if (e.key === 'Enter' || e.key === ' ') {
@@ -437,8 +478,18 @@ function StepItemHeader({ children, className, style }: { children: React.ReactN
       onClick={item.clickable ? item.activate : undefined}
       onKeyDown={item.clickable ? onKeyDown : undefined}
       aria-disabled={item.disabled || undefined}
+      // 2026-07-05 D4 修:step 有 content 的可點 header(role=button)必帶 aria-expanded —
+      // WAI-ARIA disclosure pattern trigger 最低要求(multiple 模式 toggle;follow-active 亦
+      // 同步反映展開狀態)。aria-controls 只在 content 實際 render(展開)時輸出,避免
+      // dangling id reference(content 收合時不在 DOM)。
+      aria-expanded={item.clickable && contentId ? item.expanded : undefined}
+      aria-controls={item.clickable && contentId && item.expanded ? contentId : undefined}
       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',
@@ -446,6 +497,7 @@ function StepItemHeader({ children, className, style }: { children: React.ReactN
       )}
       style={style}
     >
+      <span className="sr-only">{`第 ${index} 步,共 ${steps.total} 步,${STEP_STATUS_TEXT[item.state]}`}</span>
       {children}
     </div>
   )
@@ -468,35 +520,39 @@ function VerticalLayout({
   const item = useStepItemContext()
   const showContent = !!content && item.expanded
   const indicatorBox = INDICATOR_BOX_WIDTH[steps.size]
+  // 2026-07-05 D4 修:content 區 id 供 header aria-controls 指向(disclosure 配線)
+  const contentId = React.useId()
 
   return (
     <>
-      <StepItemHeader className="flex items-start gap-3">
-        <div className="shrink-0" style={{ width: indicatorBox }}>
-          <div className="h-[1lh] flex items-center justify-center">
-            <StepIndicator />
-          </div>
-        </div>
-        <div className="flex-1 min-w-0 flex items-start">
+      <StepItemHeader className="flex items-start gap-3" contentId={content ? contentId : undefined}>
+        {/* Row prefix slot — 消費 item-anatomy <ItemPrefix>(h-[1lh] 對齊 label 第一行 SSOT);
+            width = INDICATOR_BOX_WIDTH 固定欄寬,base justify-center 讓 sm dot 在欄內置中 */}
+        <ItemPrefix style={{ width: indicatorBox }}>
+          <StepIndicator />
+        </ItemPrefix>
+        <div className="flex-1 min-w-0 flex items-start gap-2">
           <div className="flex-1 min-w-0 flex flex-col">
             {label}
             {description}
           </div>
+          {/* Row suffix slot — 消費 item-anatomy <ItemSuffix>(h-[1lh] 對齊 label 第一行);
+              text col 是 flex-1 → base ml-auto 惰性,8px 間距由父層 gap-2 提供(= MenuItem 父層 gap idiom)*/}
           {steps.expansion === 'multiple' && !!content && (
-            <span aria-hidden className="h-[1lh] flex items-center shrink-0 ml-2">
+            <ItemSuffix aria-hidden>
               <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',
                 )}
               />
-            </span>
+            </ItemSuffix>
           )}
         </div>
       </StepItemHeader>
       {showContent && (
-        <div className="flex items-start gap-3 mt-3">
+        <div id={contentId} className="flex items-start gap-3 mt-3">
           <div className="shrink-0" style={{ width: indicatorBox }} />
           <div className="flex-1 min-w-0">{content}</div>
         </div>
@@ -519,8 +575,10 @@ function VerticalConnectorLine() {
     <div
       aria-hidden
       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,
@@ -563,14 +621,15 @@ function HorizontalLayout({
     <>
       {/* Row 1: indicator + label + connector(在同一個 flex row) */}
       <StepItemHeader className="flex items-start gap-3">
-        <div className="h-[1lh] flex items-center shrink-0">
+        {/* Row prefix slot — 消費 item-anatomy <ItemPrefix>(h-[1lh] 對齊 label 第一行 SSOT)*/}
+        <ItemPrefix>
           <StepIndicator />
-        </div>
+        </ItemPrefix>
         <div className="shrink-0 min-w-0">{label}</div>
         {/* Connector 在 item 內部,flex-1 填滿剩餘寬度 */}
         {!item.isLast && (
           <div className="h-[1lh] flex-1 flex items-center min-w-4" aria-hidden>
-            <div className={cn('h-px w-full', isBlue ? 'bg-primary' : 'bg-border')} />
+            <div className={cn('h-px w-full', isBlue ? 'bg-info' : 'bg-border')} />
           </div>
         )}
       </StepItemHeader>
@@ -618,12 +677,12 @@ 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)) : undefined,
     }
   } else {
     const dotBg =
-      state === 'completed' ? 'var(--primary)'
+      state === 'completed' ? 'var(--info)'
         : state === 'error' ? 'var(--error)'
           : state === 'current' && !linear ? 'var(--fg-disabled)'
             : 'var(--fg-disabled)' // upcoming + non-linear fallback
@@ -677,12 +736,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)'
@@ -690,7 +749,7 @@ function MdLgIndicator({
       }
       break
     case 'reachable':
-      fillBg = 'var(--primary)'
+      fillBg = 'var(--info)'
       contentColor = 'var(--on-emphasis)'
       break
     default: // upcoming
@@ -717,7 +776,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)) : undefined,
       }}
     >
@@ -751,7 +811,9 @@ const StepLabel = React.forwardRef<HTMLSpanElement, StepLabelProps>(
       <span
         ref={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'
@@ -839,9 +901,9 @@ export 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: [],
   },

package/src/components/Switch/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './switch'