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

package/src/components/CircularProgress/circular-progress.principles.stories.tsx

@@ -0,0 +1,265 @@
+// @principles-rationale: Merged WhenNotToUse + CircularVsSkeletonRule into a single
+// `UsageGuidance` story (3 sections — 何時用 / 何時不用 / vs 近親) per 2026-04-26 user
+// mandate. IndeterminateVsDeterminateRule / ConsumptionScenarioRule / SizeMatchContextRule
+// kept as separate principles.
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Search, Check } from 'lucide-react'
+import { CircularProgress } from './circular-progress'
+import { Button } from '@/design-system/components/Button/button'
+import { Skeleton } from '@/design-system/components/Skeleton/skeleton'
+import { Empty } from '@/design-system/components/Empty/empty'
+import { Input } from '@/design-system/components/Input/input'
+
+const meta: Meta = {
+  title: 'Design System/Components/CircularProgress/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-body-lg font-semibold text-foreground mb-3 pb-1 border-b border-divider">{title}</h2>
+    <div>{children}</div>
+  </section>
+)
+
+const Rule = ({
+  title, note, children,
+}: {
+  title: string; note?: string; children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-muted mb-5 max-w-[720px] leading-relaxed">{note}</p>}
+    <div className="flex flex-wrap gap-6 items-start">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <p className="text-caption text-fg-muted max-w-[720px] leading-relaxed mb-6">
+          CircularProgress 用於「使用者觸發 async 動作後的即時回饋」與「全頁 / 浮層的 loading 訊號」。
+          詳細情境 → 「常見消費場景」story(Button loading / Inline 表單驗證 / Empty 全頁 overlay)。
+        </p>
+      </Section>
+
+      <Section title="何時不用 + 替代">
+        <Rule
+          title="❌ 不用 CircularProgress 當常駐視覺裝飾"
+          note="語意鎖「正在載入、正在處理」。永遠旋轉的裝飾會讓 a11y 使用者(螢幕閱讀器)持續收到 loading 通知,也讓視覺使用者無法判斷何時結束"
+        >
+          <div className="flex items-center gap-2 border border-border rounded-lg p-3 w-72">
+            <CircularProgress aria-label="載入中（裝飾誤用示範）" />
+            <span className="text-body">歡迎使用本系統</span>
+          </div>
+          <Label warn>Welcome banner 裡無限轉的 CircularProgress → 使用者以為系統卡住</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不要多個 CircularProgress 同時旋轉"
+          note="同一畫面多個 indeterminate 會讓使用者不知道注意力該放哪。通常是結構問題:應該用父層單一 overlay,或改用 Skeleton 描述整個佈局"
+        >
+          <div className="flex flex-col gap-2 w-72">
+            {Array.from({ length: 4 }).map((_, i) => (
+              <div key={i} className="flex items-center gap-2 border border-border rounded-md px-3 py-2">
+                {/* size=16 = field-inline canonical;此例為反例(不該多個一起轉)。 */}
+                <CircularProgress size={16} aria-label={`載入項目 ${i + 1}`} />
+                <span className="text-body text-fg-muted">載入項目 {i + 1}</span>
+              </div>
+            ))}
+          </div>
+          <Label warn>四個同時轉 → 改用 Skeleton 做整個列表佔位</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不要在本元件外包 overlay 容器做全頁遮罩"
+          note="CircularProgress 是純 primitive,不管 overlay / centering / 背景。全頁 loading 一律走 <Empty icon={<CircularProgress/>}/> compose,不要手刻 absolute inset-0 + flex center"
+        >
+          <Label warn>不要加 color / variant / speed / thickness prop — 本元件單一職責</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不要 inline copy Loader2"
+          note={'設計系統裡任何 loading 視覺都從 CircularProgress import。自己寫 `<Loader2 className="animate-spin" />` 會造成 icon / animation / a11y 漂移'}
+        >
+          <Label warn>所有 loading 都走 CircularProgress,不要 inline Loader2</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 達 100% 不 swap,留在 value=100"
+          note="CircularProgress 語義是「進行中」,停在 100% 跟「完成」語義衝突,使用者看到「滿的 circle」會困惑「還在跑嗎?」。世界級慣例(Gmail / Dropbox / Google Drive):上傳完成即消失,swap 為 ✓ icon / 實際內容 / Empty。本 DS 不提供 success / error variant——consumer 端替換整個元件,不在 CircularProgress 內做狀態 morph"
+        >
+          <div className="flex items-center gap-6">
+            <div className="flex flex-col items-center gap-2">
+              <CircularProgress value={100} size={24} aria-label="進度 100%（穩態誤用）" />
+              <Label warn>❌ 穩態停留 100% → 使用者困惑</Label>
+            </div>
+            <div className="flex flex-col items-center gap-2">
+              <div className="inline-flex items-center gap-2 text-success">
+                <Check size={16} aria-hidden />
+                <span className="text-body">已完成</span>
+              </div>
+              <Label>✅ Swap 為 Check icon + label / 直接呈現該呈現的內容</Label>
+            </div>
+          </div>
+        </Rule>
+      </Section>
+
+      <Section title="vs 近親 — CircularProgress vs Skeleton">
+        <Rule
+          title="CircularProgress — 行為回饋(不可預期時長、不知佈局)"
+          note="Button 送出中、API 等待、upload 進行中——沒有「資料形狀」可以佔位,只是告訴使用者「正在處理,請稍候」"
+        >
+          <Button variant="primary" loading>處理付款中</Button>
+          <Label>Stripe 結帳:只需要「在做事」的訊號,不需要佔位</Label>
+        </Rule>
+
+        <Rule
+          title="Skeleton — 內容佔位(佈局已知、等資料填入)"
+          note="List / table / card grid 初次載入——佈局結構確定,只差資料。用 Skeleton 讓版面先定型,避免資料回來時跳動"
+        >
+          <div className="flex items-center gap-3 w-72 border border-border rounded-lg p-3">
+            <Skeleton className="h-10 w-10 rounded-full" />
+            <div className="flex flex-col gap-2 flex-1">
+              <Skeleton className="h-4 w-3/5" />
+              <Skeleton className="h-3 w-1/3" />
+            </div>
+          </div>
+          <Label>Linear 成員列表:佈局已定,等資料填入</Label>
+        </Rule>
+
+        <Rule
+          title="判準"
+          note="要描述「佈局」還是「行為」?描述佈局 → Skeleton;描述行為 → CircularProgress"
+        >
+          <Label>能畫出最終樣貌 → Skeleton</Label>
+          <Label>只知道「在進行」 → CircularProgress(indeterminate)</Label>
+        </Rule>
+      </Section>
+    </div>
+  ),
+}
+
+export const IndeterminateVsDeterminateRule: Story = {
+  name: '不確定 vs 確定進度',
+  render: () => (
+    <div>
+      <Rule
+        title="不知道時長 → 不傳 value(indeterminate);能量化進度 → 傳 value(determinate)"
+        note="CircularProgress 兩態合一(Material / Chakra 流派)。判斷法:consumer 能告訴使用者「完成了 X%」嗎?能 → determinate、不能 → indeterminate。選錯會讓使用者一直盯著 0% 以為壞掉,或看著旋轉以為是裝飾。"
+      >
+        <div className="flex flex-col items-center gap-2">
+          <CircularProgress aria-label="等待第三方驗證" />
+          <Label>✅ 第三方金流驗證:不知道要多久 → 不傳 value</Label>
+        </div>
+        <div className="flex flex-col items-center gap-2">
+          <CircularProgress value={65} affix="value" aria-label="檔案上傳進度 65%" />
+          <Label>✅ 檔案上傳:bytes 已知 → 傳 value={'{N}'}</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="Determinate 若無法量化會變假進度"
+        note="value 永遠停在 0% 或隨機亂跳會讓使用者懷疑 app 壞掉。若操作本質不可量化,維持 indeterminate 到底,不要硬傳 value 假裝。"
+      >
+        <div className="flex flex-col items-center gap-2">
+          <CircularProgress value={0} aria-label="報表產生進度 0%（假進度誤用）" />
+          <Label warn>❌ 生成報表中卻永遠卡 0% → 改用 indeterminate(不傳 value)</Label>
+        </div>
+      </Rule>
+    </div>
+  ),
+}
+
+// 2026-07-14 rename per audit Dim 14:原 name「使用情境」與同檔 UsageGuidance「使用指引」/
+// SizeMatchContextRule「尺寸對應使用情境」語意撞名,讀者難分。本 story 教的是「CircularProgress
+// 內嵌於 Button / Input / Empty 的常見消費場景」,name 改為可區辨的人話。
+export const ConsumptionScenarioRule: Story = {
+  name: '常見消費場景（內嵌於 Button / Input / Empty）',
+  render: () => (
+    <div>
+      <Rule
+        title="✅ Button loading — 使用者觸發動作後的即時回饋"
+        note="表單送出、API 呼叫、執行動作中,Button 的 loading prop 內部自動渲染 CircularProgress。是最常見的消費場景"
+      >
+        <Button variant="primary" loading>送出訂單</Button>
+        <Button variant="secondary" loading>儲存變更</Button>
+        <Label>按鈕按下後的即時回饋,告訴使用者「已收到,在處理」</Label>
+      </Rule>
+
+      <Rule
+        title="✅ Inline 表單驗證 / async search"
+        note="輸入後等待伺服器驗證或搜尋結果時,Input 的 loading prop 內部自動在 endAction 塞 16px CircularProgress。視覺干擾最小,使用者可繼續輸入"
+      >
+        <Input
+          startIcon={Search}
+          loading
+          defaultValue="cq@"
+          placeholder="驗證 email 唯一性..."
+          aria-label="Email"
+          className="w-72"
+        />
+        <Label>驗證 email 唯一性(GitHub 註冊場景)</Label>
+      </Rule>
+
+      <Rule
+        title="✅ 延遲加載浮層 / 全頁 overlay — 用 Empty compose"
+        note="切換 workspace / 載入 dashboard 等需要阻擋互動的場景,走 Empty compose:<Empty icon={<CircularProgress size={48} />} title=... description=... />。不要自己手刻 absolute overlay"
+      >
+        {/* 2026-07-04 audit:改消費 <Empty> compose(原手刻垂直堆疊與本則自教規則+spec Do 矛盾) */}
+        <div className="border border-border rounded-lg w-96 h-40 flex items-center justify-center bg-muted/40">
+          <Empty
+            icon={<CircularProgress size={48} aria-label="載入 dashboard" />}
+            title="載入 dashboard 中"
+            description="Notion workspace 切換、Stripe dashboard 初載"
+          />
+        </div>
+      </Rule>
+    </div>
+  ),
+}
+
+export const SizeMatchContextRule: Story = {
+  name: '尺寸對應使用情境',
+  render: () => (
+    <div>
+      <Rule
+        title="16px — Button 內、Field endAction、Tag 內(inline 小空間)"
+        note="inline 元素內部,尺寸對齊旁邊的 text / icon。不能更大,會撐破容器。多數情境由 Button / Input 內部程式化決定(consumer 不需手傳)"
+      >
+        <Button variant="tertiary" loading>送出</Button>
+        <Input
+          loading
+          defaultValue="驗證中..."
+          placeholder="驗證 email..."
+          aria-label="Email"
+          className="w-60"
+        />
+      </Rule>
+
+      <Rule
+        title="24px(預設)— row primitive 的 loading footer、card 內 inline loading"
+        note="中等尺寸,放在 row / card 內容區,視覺重量足夠吸引注意但不喧賓奪主"
+      >
+        <div className="flex items-center justify-center gap-2 border border-border rounded-lg p-4 w-72">
+          <CircularProgress size={24} aria-label="載入更多留言" />
+          <span className="text-body text-fg-muted">載入更多留言...</span>
+        </div>
+        <Label>Slack channel 載入更多訊息的 footer</Label>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/CircularProgress/circular-progress.spec.md

@@ -10,7 +10,6 @@ benchmark:
   - Ant Design Progress: github.com/ant-design/ant-design/tree/master/components/progress
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
 
 # CircularProgress 設計原則
 
@@ -55,7 +54,7 @@ benchmark:
 ## 何時用
 
 - **Button / Inline Action 的 loading 狀態**:Button `loading` prop 內部渲染(無 value = indeterminate)
-- **Field loading 狀態**(Input / NumberInput / Combobox / Select):consumer 傳 `loading={true}` → 元件內部 readonly + endAction slot 自動塞 `<CircularProgress>`(見 `field-controls.spec.md`「Loading state」)
+- **Field loading 狀態**(Input / NumberInput / Combobox / Select):consumer 傳 `loading={true}` → 元件內部**保持可編輯**(Ant Input.Search 派,UX「邊改邊讀」,非 Material readonly 派),自動在尾端渲染 `<CircularProgress>` + `aria-busy="true"` 標示處理中(與 `endAction` 互斥;見 `input.tsx` loading 分支與 `field-controls.spec.md`「Loading state」)
 - **Cell / row 局部進度**(cell 上傳中、cell async fetch 中):size 16-20 inline
 - **inline 可量化小進度**(如 file uploader list row 的上傳 % / 倒數計時):有 value
 - **全頁 / empty surface 載入**:`<Empty icon={<CircularProgress size={48}/>}/>` compose(Empty canonical 垂直堆疊,無需另造)
@@ -65,7 +64,7 @@ benchmark:
 | 場景 | 改用 | 原因 |
 |------|------|------|
 | 頁面級 / 表單級大區塊進度 | `ProgressBar`(linear) | CircularProgress 在大尺寸視覺比例不如 linear bar |
-| 骨架載入(list / card 初次 render) | `Skeleton` | Skeleton 保留內容形狀 |
+| 骨架載入(list / card 初次 render) | `Skeleton` | Skeleton 保留內容形狀;完整分界 SSOT 見 `skeleton.spec.md`「Skeleton vs CircularProgress」 |
 | 全頁 loading 版面 | `<Empty icon={<CircularProgress/>}/>` | 版面繼承 Empty 垂直堆疊 canonical |
 | 通知計數 / 狀態紅點 | `Badge`(dot 模式) | 語義完全不同 |
 
@@ -79,17 +78,17 @@ export interface CircularProgressProps extends React.HTMLAttributes<HTMLSpanElem
   value?: number
   /** 直徑 px,預設 24,≤ 64 建議 */
   size?: number
-  /** 狀態色(與 ProgressBar 一致) */
-  status?: 'inProgress' | 'success' | 'error'
   /** 視覺 label(inline,font-size inherit,color text-fg-muted) */
   label?: string
   /** Determinate 模式的 affix(indeterminate 忽略) */
-  affix?: 'value' | 'status-icon' | React.ReactNode
+  affix?: 'value' | React.ReactNode
   /** A11y label(指定後 shouldAnnounce=true) */
   'aria-label'?: string
 }
 ```
 
+**無 `status` prop**:本元件不提供 `status`(success / error 等)狀態色——完成 / 失敗由 consumer 端 swap 整個元件(見下方「不設 `status` prop」)。`affix` 也不提供 `'status-icon'` 選項。
+
 ### 尺寸策略:自由 `number`,跟 Avatar 同一套
 
 不用 `sm | md | lg` enum(跨度 16 → 64 太大)。
@@ -122,13 +121,13 @@ export interface CircularProgressProps extends React.HTMLAttributes<HTMLSpanElem
 | 切到 `<Empty>` 或其他 state component | 全頁 overlay → 內容出現;或 empty state |
 | CircularProgress 直接消失 | 非同步操作完成,UI 回到預設態 |
 
-**世界級慣例**:Gmail / Dropbox / Google Drive 上傳完成即消失;iOS Activity Indicator 完成隱藏;Figma / Notion async fetch 完成切到實際內容。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+進度完成後必把 indicator 替換為實際內容或完成結果；已完成的工作不再呈現「仍在處理」的動態訊號。
 
 **為什麼不留 100%**:`CircularProgress` 語義是「進行中」,停在 100% 跟「完成」的語義衝突,使用者看到「滿的 circle」會困惑「還在跑嗎?」。
 
 ### 不設 `status` prop — 完成 / 失敗由 consumer 端 swap
 
-世界級 DS(Material / Chakra / Ant / Polaris)**沒有**「success / error CircularProgress」variant——完成與失敗的語義應由 consumer 在業務邏輯上**替換 CircularProgress 為實際內容**(Check icon + label / 結果 / 錯誤訊息等),不讓 progress 指示器本身做狀態 morph(綠底空心 circle + check icon 並排是 anti-pattern)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+CircularProgress **沒有**「success / error」variant。完成與失敗的語義由 consumer 在業務邏輯上**替換 CircularProgress 為實際內容**(Check icon + label / 結果 / 錯誤訊息等),不讓 progress 指示器本身做狀態 morph(綠底空心 circle + check icon 並排是 anti-pattern)。
 
 ```tsx
 // ✅ canonical — consumer 端 swap
@@ -152,29 +151,29 @@ export interface CircularProgressProps extends React.HTMLAttributes<HTMLSpanElem
 | 情境 | 建議 size | 為什麼 |
 |------|----------|--------|
 | field-height 相關容器(Button loading / Input loading / DataTable cell / Field control loading 等) | 對齊容器的 iconSize(本 DS 全部是 `sm/md = 16 / lg = 20`) | 與容器內其他 icon 視覺同刻度,避免 row 內 icon 跳高低 |
-| 獨立使用 / 全頁 / Empty overlay / Coachmark media 等無 field-height 約束 | 預設 24(傳統 Material 標準)— 需要更大(例如 Empty 大圖)可 32 / 48 | 無參考尺寸時走 DS 預設,不憑感覺挑 | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| 獨立使用 / 全頁 / Empty overlay / Coachmark media 等無 field-height 約束 | 預設 24；需要更大(例如 Empty 大圖)可 32 / 48 | 無參考尺寸時走 DS 預設,不憑感覺挑 |
 
 **實作保證**:
 - Button / Input / Field 等 **元件內部自動傳對的 size**(consumer 不用傳)— 來源:這些元件本來就知道自己的 `iconSize`(`field-controls.spec.md` 中 `sm/md=16, lg=20`)
-- DataTable cell 由 consumer 手寫 render,**consumer 傳 `16`(sm/md table) / `20`(lg table)** — 規則在 `data-table.spec.md` 十一之一
+- DataTable **cell 內 inline 指示器**由 consumer 手寫 render,size 對齊 cell icon 刻度 **`16`(sm/md table) / `20`(lg table)** — 對齊 `data-table.spec.md` 十一之一(cell icon size canonical,非 CircularProgress 專屬規則)。**整表 refresh loading** 則走 `data-table.spec.md` 十三:容器疊 `<CircularProgress/>` 24px center + table `opacity-disabled`(DataTable 禁內建 loading prop)
 - 獨立使用 CircularProgress 的元件 **預設走 24** — 已是 `<CircularProgress />` default
 
-世界級對照:Material / Ant / Carbon 的 inline loading 全部 16dp;Material 獨立使用標準 = 40dp(desktop)/ 24dp(compact)。本 DS 收斂成「inline 跟 context 走 16 或 20,獨立走 24」兩檔,不暴露更多 size 階。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+本 DS 收斂成「inline 跟 field context 走 16 或 20，獨立使用走 24」兩類；32 / 48 只供有明確大型 host 的 composition，不再暴露其他 size 階。
 
-### 顏色策略:固定 `text-primary` + consumer 覆寫
+### 顏色策略:固定 `text-info` + consumer 覆寫
 
-固定 `text-primary`(品牌語義色「正在處理」)。不隨狀態變色。
+固定 `text-info`(品牌語義色「正在處理」)。不隨狀態變色。
 
 | Consumer | className | 實際色彩 |
 |----------|-----------|---------|
-| 獨立 / 全頁 / Empty overlay / Input loading | 無(走預設) | `text-primary` |
+| 獨立 / 全頁 / Empty overlay / Input loading | 無(走預設) | `text-info` |
 | Button `loading` 各 variant | `className="text-current"` | 繼承 button `text-on-emphasis` / `text-foreground` |
 
 Track 色鎖 `var(--secondary)`(= neutral-3,與 ProgressBar track 一致)。
 
 ### Label 策略:font-size 繼承 + 色鎖 neutral-7
 
-- `label` 有值 → render `<span className="text-fg-muted">`,font-size **繼承 parent**(不設 text-size class,CSS inherit 天然處理)
+- `label` 有值 → render `<span className="text-fg-muted">`,font-size **繼承 parent**(不設 text-size class,CSS inherit 天然處理);label 渲染於 circle **右側**(inline sibling),不在圈內——小 size(16)也不會文字疊圈
 - 塞在元件內(Button / Field)時不用 label(元件本身已有文字);全頁 / Empty overlay 場景可開
 
 ### A11y 策略
@@ -182,20 +181,18 @@ Track 色鎖 `var(--secondary)`(= neutral-3,與 ProgressBar track 一致)。
 | 模式 | role | aria 屬性 |
 |------|------|----------|
 | Determinate(`value` 有值) | `progressbar` | `aria-valuenow / aria-valuemin=0 / aria-valuemax=100` + optional `aria-label` |
-| Indeterminate + 有 aria-label / label | `status` | `aria-label={label ?? aria-label}` |
+| Indeterminate + 有 aria-label / label | `status` | `aria-label={aria-label ?? label}`(顯式 aria-label 優先,label 為 fallback) |
 | Indeterminate + 無 label | `aria-hidden=true` | 由父層 `aria-busy` 管理(Button 模式) |
 
+**動畫 × `prefers-reduced-motion`**:indeterminate 旋轉對 reduce 使用者**不停止**(loading 回饋仍需可見,停轉會像卡住),改放慢至 3s/圈(預設 1s;`circular-progress.tsx` 的 `motion-reduce:[animation-duration:3s]`,Material 流派)——保留「進行中」訊號、降低前庭刺激。對照 Skeleton 的 `motion-reduce:animate-none`(完全停止):占位塊靜止後仍是有效的靜態內容,語意不失,故兩元件策略不同。
+
 ---
 
 ## 視覺與幾何鐵律
 
-- **正方形不可妥協**:`style={{ width: size, height: size }}` 強制。本體絕不加 margin / padding
+- **正方形**:外層 span `style={{ width: size, height: size }}` + 內層 `<svg width height>` 雙重鎖尺寸——svg 顯式 width / height 兜底,即使 consumer 傳 `style` 覆寫外層 span,圓形圖形仍維持正方比例。本體絕不加 margin / padding
 - **SVG 雙 circle**:track(`var(--secondary)`) + arc(`currentColor`),stroke-linecap round,rotate -90deg 從 12 點起始
-- **strokeWidth 動態 scale**:`Math.max(2, Math.round(size / 10))` 維持跨尺寸視覺比例
-  - size 24 → stroke 2
-  - size 32 → stroke 3
-  - size 48 → stroke 5
-  - size 64 → stroke 6
+- **strokeWidth 動態 scale**:`Math.max(2, Math.round(size / 10))` 維持跨尺寸視覺比例(逐值結果由公式推導,不另列舉)
 - **Indeterminate arc**:固定 25%(`INDETERMINATE_ARC_RATIO=0.25`),外層 `animate-spin` 旋轉整個 span(Material 流派)
 - **旋轉規則單純**:indeterminate → 轉;determinate → 不轉;沒有 status 條件分支,因為沒有 status。完成時 consumer 把整個 CircularProgress swap 成其他內容(Check icon / 結果 / Empty),不靠元件本身做 spin-stop 動畫
 - **`align-middle` 鎖死**(SVG 對齊 adjacent text x-height 中線):外層 span 本體帶 `align-middle`,避免在 inline-flex 容器內出現基線錯位。consumer 若在文字旁放 CircularProgress,**不需**自己加 `align-middle` 或 `leading-none`
@@ -219,26 +216,27 @@ Track 色鎖 `var(--secondary)`(= neutral-3,與 ProgressBar track 一致)。
 
 ---
 
-## 為何僅保留 Overview + 兩 consumer context stories
+## 為何僅保留 Overview + 兩 consumer context + Accessibility stories
 
 CircularProgress 是**最薄的 circular progress primitive**,刻意避免多維度變體:
 
-- **無 Inspector**:variant 只有 value 有無 + status 三狀態(lifecycle),互動切換式 Inspector 可展的決策點少。`UsageInButton` / `UsageInline` 已覆蓋真實 consumer context
-- **ColorMatrix N/A(只繼承 Progress color token)**:本元件 color 完全來自 `text-current`(繼承 host)+ Progress token(track / fill),無 own variant × state 色彩組合可 matrix 對照。status(running/success/error)已在 `UsageInButton` / `UsageInline` 真實 context 演示,獨立 ColorMatrix story 會是冗餘
-- **SizeMatrix 透過 Inspector 即可展示 — 無 separate SizeMatrix story**:size 是自由 number(非 sm/md/lg tier),Inspector 的 size slider 即可展示 16 / 24 / 32 / 48 等常用值的行為差異,比靜態 matrix 更貼近消費情境
-- **無 StateBehavior**:無 hover / focus / active,唯一「狀態」是 value 變化(已在 Determinate story 動態演示)
+- **無 Inspector**:variant 只有 value 有無(indeterminate / determinate 兩態),互動切換式 Inspector 可展的決策點少。`UsageInButton` / `UsageInline` 已覆蓋真實 consumer context
+- **ColorMatrix N/A**:arc 預設固定 `text-info`(consumer 傳 `className="text-current"` 才繼承 host,見上方「顏色策略」),track 固定 `var(--secondary)`,無 own variant × state 色彩組合可 matrix 對照。色彩不隨狀態變色(完成 / 失敗由 consumer swap 整個元件),`UsageInButton` / `UsageInline` 真實 context 已示範,獨立 ColorMatrix story 會是冗餘
+- **SizeMatrix N/A — 無 separate SizeMatrix story**:size 是自由 number(非 sm/md/lg tier),由 Button / Input 等 consumer 容器內部依規則程式化縮放,`UsageInButton` / `UsageInline` 真實 context 已涵蓋 16(cell / upload row)/ 20(Input lg)/ 24(inline 預設)等常用值的行為差異,比靜態 matrix 更貼近消費情境(48 的全頁 overlay 尺寸見展示層 `FullScreenOverlay`)
+- **無 StateBehavior**:無 hover / focus / active,唯一「狀態」是 value 變化(determinate 靜態值示範於 `UsageInline`「Determinate inline」段;元件不含 timer / RAF 動態演示,進度值由 consumer 傳入驅動)
 
-對應 anatomy story:`Overview` + `UsageInButton` + `UsageInline`。缺 canonical 5 多數項的 rationale 即本段。
+對應 anatomy story:`Overview` + `UsageInButton` + `UsageInline` + `Accessibility`(2026-05-17 per story-rules 6-canonical)。缺 canonical 5 多數項的 rationale 即本段。
 
 ---
 
 ## 邊界案例
 
-- **Disabled(consumer host)**:CircularProgress 本身**不擁有 disabled state**(色彩繼承 host 的 `text-current`)。當消費 host 為 Button loading + disabled 組合時,spinner 顏色自動跟 Button text color 弱化為 `text-fg-disabled`;不需 CircularProgress 端 prop。
+- **Disabled(consumer host)**:CircularProgress 本身**不擁有 disabled state**,也不含任何弱化色邏輯。arc 固定用 `currentColor`,顏色完全跟著 host 的文字色走;若 consumer 傳 `className="text-current"`(如 Button loading),host 把文字色設成什麼,spinner 就是什麼色——由 host CSS 決定,非 CircularProgress 端 prop 或內建保證。
 - **Loading(本即元件本質)**:本元件本質是 loading indicator;無需另外的 loading prop。indeterminate(無 `value`)= 旋轉動畫,determinate(有 `value`)= 弧長對應 0–100%。
-- **Empty / 0 progress**:`value=0` 在 determinate mode 渲空 track,符合「尚未開始」語意;若 0 + lifecycle status `success`,自動切 success token(`UsageInline` story 演示)。
+- **Empty / 0 progress**:`value=0` 在 determinate mode 渲空 track(arc 長度 0),符合「尚未開始」語意。本元件沒有 success / error 等狀態色切換——arc 永遠是 `currentColor`(預設 `text-info`),不會因進度值自動變色。
 - **Dark mode**:走 Progress token + `text-current` 繼承,自動 adapt。
-- **Size 極端值**:size 為自由 number(非 sm/md/lg tier);size < 12 不建議(stroke width / icon overlap 失調),size > 96 建議改 ProgressBar(linear 在大尺寸更易讀)。
+- **Size 極端值**:size 為自由 number(非 sm/md/lg tier);size < 12 不建議(stroke width / icon overlap 失調),size > 96 建議改 ProgressBar(linear 在大尺寸更易讀)。建議值非強制——元件不 clamp size,照傳入值渲染。
+- **Value 越界 / 快速更新**:`value` 超出 0–100 自動 clamp(`Math.max(0, Math.min(100, value))`);快速連續更新由 CSS transition(300ms)自動朝最新值收斂,不堆疊不排隊。
 
 ---
 
@@ -258,11 +256,13 @@ CircularProgress 是**最薄的 circular progress primitive**,刻意避免多維
 - `<Spinner size={N} aria-label="..."/>` → `<CircularProgress size={N} aria-label="..."/>`
 - 新增能力:`<CircularProgress value={N}/>` 支援 determinate
 
-遷移理由:世界級命名對齊 Material / Chakra,支援 determinate 需求(user 2026-04-20 提出),元件數減少(廢除重複的 Spinner 名稱)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+遷移理由:`CircularProgress` 同時涵蓋 indeterminate 與 determinate contract，廢除只描述單一動畫形態的重複 `Spinner` 名稱，減少元件與 import 分歧。
 
 ## 被引用(auto-maintained,Dim 3 reciprocal audit)
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `badge.spec.md`
+- `empty.spec.md`
+- `progress-bar.spec.md`
 - `skeleton.spec.md`

package/src/components/CircularProgress/circular-progress.stories.tsx

@@ -0,0 +1,149 @@
+// @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#WithBulkActions
+// (per .claude/references/story-baseline-registry.json#DataTable)
+import type { Meta, StoryObj } from '@storybook/react'
+import { Search, Upload } from 'lucide-react'
+import type { ColumnDef } from '@tanstack/react-table'
+import { CircularProgress } from './circular-progress'
+import { Input } from '@/design-system/components/Input/input'
+import { Empty } from '@/design-system/components/Empty/empty'
+import { DataTable } from '@/design-system/components/DataTable/data-table'
+
+/**
+ * CircularProgress 展示——整個設計系統 circular 形式進度的 SSOT。
+ *
+ * - 無 value → indeterminate 旋轉(取代舊 Spinner 用法)
+ * - 有 value → determinate arc + track(可量化進度,如 inline 上傳 %)
+ *
+ * 範例均對標世界級產品的真實使用場景(GitHub 儲存庫搜尋、檔案上傳佇列、
+ * 雲端同步狀態表格、workspace 切換載入)。
+ * 設計規則詳見 `circular-progress.spec.md`。
+ */
+
+const meta: Meta = {
+  title: 'Design System/Components/CircularProgress/展示',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { description: { component: '圓形進度指示，可呈現未知進度的持續載入或已知百分比的 determinate 狀態。適用 inline 小空間；頁面級已知進度改用 ProgressBar。' } },
+  },
+}
+export default meta
+type Story = StoryObj
+
+export const Default: Story = {
+  name: '預設',
+  render: () => (
+    <div className="flex items-center gap-6">
+      {/* CircularProgress 只提供一種預設尺寸(24);其他尺寸由 consumer context 自動縮放
+          (Button loading = iconSize / Input loading = iconSize / Empty = iconSize)。
+          不 parallel 展示多 sizes 因為 DS 不「提供各種 sizes」讓 consumer 挑,而是透過原則
+          在 consumer 端自動決定(見 spec.md「Size canonical」)。 */}
+      <CircularProgress aria-label="載入中" />
+      <CircularProgress value={60} aria-label="進度 60%" />
+      <CircularProgress value={90} affix="value" aria-label="進度 90%" />
+    </div>
+  ),
+}
+
+// Retired 2026-07-04 audit Dim 24:`ButtonLoading` 全程只 demo `<Button loading>`(0 個直接 `<CircularProgress>`),
+// 跟 button.stories.tsx「載入中」重複且較弱(那邊有 原始→loading 對照 + iconOnly + startIcon 替換)。
+// Button loading 消費 CircularProgress 的關係由 spec「何時用」+ Size canonical 段記載,story home 在 Button。
+
+export const InlineAction: Story = {
+  name: '行內操作',
+  render: () => {
+    // 多檔上傳列(Google Drive / Dropbox 慣例):上傳中的檔案 determinate(value + affix
+    // 顯示 %),尚在準備(壓縮 / 掃描)的檔案 indeterminate + label——兩態在同一真實佇列
+    // 中對照。容器 text-body(14px)→ CircularProgress label 天然 inherit,無須
+    // hand-craft label span。
+    const uploads = [
+      { file: 'Q3-revenue-report.xlsx', value: 28 },
+      { file: 'product-roadmap.pdf', value: 64 },
+      { file: 'presentation.pdf', value: undefined },
+    ]
+    return (
+      <div className="flex flex-col gap-4 max-w-sm">
+        <Input
+          startIcon={Search}
+          loading
+          defaultValue="react-"
+          placeholder="搜尋 GitHub repositories..."
+          aria-label="搜尋 GitHub repositories"
+        />
+
+        <div className="flex flex-col gap-2">
+          {uploads.map((u) => (
+            <div
+              key={u.file}
+              className="flex items-center gap-3 border border-border rounded-md px-3 py-2 text-body"
+            >
+              <Upload size={16} className="text-fg-muted" />
+              <span className="flex-1 truncate">{u.file}</span>
+              {u.value != null ? (
+                <CircularProgress size={16} value={u.value} affix="value" aria-label={`${u.file} 上傳 ${u.value}%`} />
+              ) : (
+                <CircularProgress size={16} label="準備中" />
+              )}
+            </div>
+          ))}
+        </div>
+      </div>
+    )
+  },
+}
+
+type SyncRow = { file: string; modified: string; sync: 'syncing' | 'synced' }
+
+const syncColumns: ColumnDef<SyncRow>[] = [
+  { accessorKey: 'file', header: '檔案' },
+  {
+    accessorKey: 'modified',
+    header: '最後修改',
+    cell: ({ row }) => <span className="text-fg-muted">{row.original.modified}</span>,
+  },
+  {
+    accessorKey: 'sync',
+    header: '同步狀態',
+    cell: ({ row }) =>
+      row.original.sync === 'syncing' ? (
+        // DataTable cell vertical 對齊規則:cell 本體 `flex items-center` 已把內容垂直
+        // 置中,consumer 的 inline 指示器外層也走 inline-flex items-center 即可,不要
+        // 再加 leading-none 嘗試「壓縮行高」——那會讓 svg(16px) 與 text line box 互搶
+        // 基線,反而歪掉。
+        <span className="inline-flex items-center gap-2 text-fg-muted">
+          <CircularProgress size={16} aria-label="同步中" />
+          同步中
+        </span>
+      ) : (
+        <span className="text-fg-muted">已同步</span>
+      ),
+  },
+]
+
+const syncData: SyncRow[] = [
+  { file: 'Design System v2', modified: '2 分鐘前', sync: 'syncing' },
+  { file: 'Onboarding Flow', modified: '1 小時前', sync: 'synced' },
+]
+
+export const InlineCellLoading: Story = {
+  name: '儲存格局部載入',
+  render: () => (
+    <div className="max-w-2xl">
+      <DataTable columns={syncColumns} data={syncData} />
+    </div>
+  ),
+}
+
+export const FullScreenOverlay: Story = {
+  name: '全頁浮層',
+  render: () => (
+    <div className="relative border border-border rounded-lg w-full h-80 overflow-hidden flex items-center justify-center">
+      <Empty
+        icon={<CircularProgress size={48} aria-label="切換 workspace 中" />}
+        title="正在切換 workspace"
+        description="切換到 Acme Inc. workspace,請稍候"
+      />
+    </div>
+  ),
+}

package/src/components/CircularProgress/circular-progress.tsx

@@ -21,7 +21,7 @@ import { cn } from '@/lib/utils'
  * affix:     (determinate only)'value' | ReactNode
  *
  * ── 視覺 ──
- * SVG 雙圓:底 track(`var(--secondary)`)+ 進度 arc(`text-primary`,不隨狀態變色)。
+ * SVG 雙圓:底 track(`var(--secondary)`)+ 進度 arc(`text-info`,status 進度色,不隨狀態變色)。
  * stroke-linecap round,rotate -90deg。
  * Indeterminate mode:arc 固定 25%,外層 `animate-spin` 旋轉,視覺同 Spinner。
  *
@@ -52,7 +52,6 @@ export interface CircularProgressProps extends React.HTMLAttributes<HTMLSpanElem
   value?: number
   /** 直徑(px)。預設 24,建議 ≤ 64。 */
   size?: number
-  /** 狀態色(lifecycle,與 ProgressBar 同契約)。 */
   /**
    * 視覺 label(inline 顯示於右側)。
    * - font-size 繼承 parent(不設 text-size class,CSS inherit)
@@ -133,7 +132,7 @@ const CircularProgress = React.forwardRef<HTMLSpanElement, CircularProgressProps
         className={cn(
           // align-middle:inline context 內讓 SVG 對齊 adjacent text 的 x-height 中線
           //(不加會按 baseline 對齊,在 inline-flex cell 裡視覺下沉 1-2px 看起來歪)
-          'inline-flex shrink-0 align-middle text-primary',
+          'inline-flex shrink-0 align-middle text-info',
           // motion-reduce:Material 流派 — prefers-reduced-motion 時不停止旋轉(loading 仍需可見回饋),
           // 而是放慢到 3s/cycle(預設 1s),保留資訊不刺激前庭。
           !isDeterminate && 'animate-spin motion-reduce:[animation-duration:3s]',
@@ -162,7 +161,7 @@ const CircularProgress = React.forwardRef<HTMLSpanElement, CircularProgressProps
             strokeDashoffset={dashOffset}
             strokeLinecap="round"
             transform={`rotate(-90 ${size / 2} ${size / 2})`}
-            className={isDeterminate ? 'transition-[stroke-dashoffset] duration-300' : undefined}
+            className={isDeterminate ? 'transition-[stroke-dashoffset] duration-300 motion-reduce:duration-0' : undefined}
           />
         </svg>
       </span>
@@ -193,10 +192,10 @@ export const circularProgressMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  states: ['default'], // 無 hover / focus / active(spec);disabled 屬 consumer host(spec「邊界案例」)
   tokens: {
     bg: [],
-    fg: ['text-fg-muted', 'text-foreground', 'text-primary'],
+    fg: ['text-fg-muted', 'text-foreground', 'text-info'],
     ring: [],
   },
 } as const