@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

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

@@ -0,0 +1,145 @@
+// @anatomy-rationale:
+//   Inspector / ColorMatrix / SizeMatrix / StateBehavior N/A — Skeleton 是極簡
+//   animation primitive(單一 div + pulse animation),刻意沒有 size / color /
+//   variant prop。形狀 / 尺寸完全由 consumer 的 className 決定;色彩透過
+//   bg-muted 從 theme 繼承(2026-05-20 修 drift,實際 skeleton.tsx:10 用 bg-muted);
+//   loading 是唯一狀態(無 hover / focus / active)。
+//   本檔保留 Overview + CommonShapes + DesignPrinciple + Accessibility 四個 story。
+import type { Meta, StoryObj } from '@storybook/react'
+import { Skeleton } from './skeleton'
+import { H3, Desc } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+/**
+ * Skeleton 是極簡 animation primitive——單一 div + pulse animation,
+ * **刻意沒有 size / color / variant**。形狀 / 尺寸完全由 consumer 的 className
+ * (Tailwind utilities)決定。底色固定用 `bg-muted`,深淺模式由主題色自動切換。
+ *
+ * 因此本 spec 只有 Overview + 常見形狀 + 設計原則 + 無障礙四個 story,沒有 SizeMatrix /
+ * ColorMatrix / StateMatrix——這些概念對 Skeleton 不適用。
+ */
+
+const meta: Meta = {
+  title: 'Design System/Components/Skeleton/設計規格',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>Anatomy</H3>
+        <Desc>Skeleton 用帶有脈動動畫的灰色色塊,模擬真實內容的形狀與排版,讓使用者預期即將出現的佈局。底色採用系統的中性色,深淺模式會自動切換。</Desc>
+        <div className="flex flex-col gap-2 max-w-md">
+          <Skeleton className="h-4 w-full" />
+          <Skeleton className="h-4 w-3/4" />
+          <Skeleton className="h-4 w-1/2" />
+        </div>
+      </div>
+
+      <div>
+        <H3>Props 速查</H3>
+        <Desc>Skeleton 只是 styled div——尺寸 / 形狀完全由 className(Tailwind utilities)決定。</Desc>
+      </div>
+    </div>
+  ),
+}
+
+export const CommonShapes: Story = {
+  name: '常見形狀',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>單行文字</H3>
+        <Skeleton className="h-4 w-48" />
+      </div>
+
+      <div>
+        <H3>多行段落(寬度遞減模擬自然換行)</H3>
+        <div className="flex flex-col gap-2 max-w-md">
+          <Skeleton className="h-4 w-full" />
+          <Skeleton className="h-4 w-full" />
+          <Skeleton className="h-4 w-3/4" />
+        </div>
+      </div>
+
+      <div>
+        <H3>標題 + 描述</H3>
+        <div className="flex flex-col gap-2 max-w-sm">
+          <Skeleton className="h-5 w-40" />
+          <Skeleton className="h-4 w-64" />
+        </div>
+      </div>
+
+      <div>
+        <H3>Avatar(圓形)+ name</H3>
+        <div className="flex items-center gap-3 max-w-sm">
+          <Skeleton className="h-10 w-10 rounded-full" />
+          <div className="flex flex-col gap-2 flex-1">
+            <Skeleton className="h-4 w-24" />
+            <Skeleton className="h-3 w-32" />
+          </div>
+        </div>
+      </div>
+
+      <div>
+        <H3>Card 載入</H3>
+        <div className="border border-border rounded-lg p-4 max-w-sm flex flex-col gap-3">
+          <Skeleton className="h-40 w-full rounded-md" />
+          <Skeleton className="h-5 w-3/4" />
+          <div className="flex flex-col gap-1">
+            <Skeleton className="h-3 w-full" />
+            <Skeleton className="h-3 w-full" />
+            <Skeleton className="h-3 w-2/3" />
+          </div>
+        </div>
+      </div>
+
+      <div>
+        <H3>List 載入(多 row 同形狀)</H3>
+        <div className="flex flex-col gap-3 max-w-md">
+          {Array.from({ length: 4 }).map((_, i) => (
+            <div key={i} className="flex items-center gap-3">
+              <Skeleton className="h-10 w-10 rounded-full" />
+              <div className="flex flex-col gap-1.5 flex-1">
+                <Skeleton className="h-4 w-3/5" />
+                <Skeleton className="h-3 w-1/3" />
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const DesignPrinciple: Story = {
+  name: '設計原則',
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div>
+        <H3>形狀貼合真實內容</H3>
+        <Desc>Skeleton 的形狀應該**貼近真實內容的排版**——使用者看到 skeleton 後資料載入,佈局不應大幅跳動。形狀嚴重偏離真實內容會讓使用者預期被打破、體感更慢。</Desc>
+      </div>
+
+      <div>
+        <H3>長時間 loading 不適合 Skeleton</H3>
+        <Desc>Skeleton 暗示「佈局已就位,資料很快會來」——長時間(&gt; 10s)持續顯示會讓使用者懷疑是否卡住。此時改用 progress indicator 或說明文字。</Desc>
+      </div>
+    </div>
+  ),
+}
+
+// ── Accessibility ─────────────────────────────────────────────────────────
+// 2026-05-17 ship per audit Dim 13(story-rules.md 6-canonical 含 Accessibility)
+export const Accessibility = {
+  name: '無障礙',
+  render: () => (
+    <div className="max-w-3xl text-body text-fg-secondary">
+      <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
+      <p className="whitespace-pre-line">{"本元件為純視覺呈現,無 keyboard / ARIA role / focus state 需求。Consumer 包 Skeleton 進互動容器(Button / Card / Link)時 a11y 由容器決定。"}</p>
+    </div>
+  ),
+}

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

@@ -0,0 +1,234 @@
+// @principles-rationale: UsageGuidance merges WhenToUse + WhenNotToUse + Vs*Rule into single 使用指引 story per refactor task (2026-04-26)
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Skeleton } from './skeleton'
+import { CircularProgress } from '@/design-system/components/CircularProgress/circular-progress'
+
+const meta: Meta = {
+  title: 'Design System/Components/Skeleton/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+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>
+)
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-heading-3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
+    {children}
+  </section>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <div className="prose prose-sm max-w-prose mb-8">
+          <p>適合 Skeleton 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+          <ul className="space-y-1">
+            <li><LinkTo kind="Design System/Components/Skeleton/展示" name="個人資料卡載入"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">個人資料卡載入</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/Skeleton/展示" name="任務列表載入"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">任務列表載入</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/Skeleton/展示" name="表格列載入"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">表格列載入</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/Skeleton/展示" name="文件載入"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">文件載入</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/Skeleton/展示" name="卡片網格載入"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">卡片網格載入</span></LinkTo></li>
+          </ul>
+          <p className="text-fg-muted mt-3">判斷不確定時:先確認資料回來後的佈局是否已知;若不符合載入佔位的情境,改用近親元件(見下方「vs 近親元件」段)。</p>
+        </div>
+      </Section>
+
+      <Section title="何時不用 + 替代方案">
+        <Rule
+          title="❌ 不用 Skeleton 做裝飾"
+          note="Skeleton 是 loading 語意,不是視覺裝飾元件。把它當灰色色塊用會混淆使用者對「載入中」的認知"
+        >
+          <div className="flex items-center gap-3 border border-border rounded-lg p-3 w-72">
+            <Skeleton className="h-8 w-8 rounded-full" />
+            <span className="text-body">分隔用的灰色圓點</span>
+          </div>
+          <Label warn>Skeleton 不是 decoration — 裝飾用 bg-muted div,不要用 Skeleton</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不要 nested skeleton"
+          note="Skeleton 裡包 Skeleton 視覺上會疊加 animation,造成閃爍感。如果需要複合結構,用多個並列 Skeleton 各自模擬一塊"
+        >
+          <div className="border border-border rounded-lg p-3 w-72">
+            <Skeleton className="h-20 w-full p-3">
+              <Skeleton className="h-4 w-1/2" />
+            </Skeleton>
+          </div>
+          <Label warn>外層 Skeleton 包內層 Skeleton → 動畫疊加閃爍</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不要 mix 資料跟 skeleton 在同一 row"
+          note="同一個 row 裡一半顯示真實資料、一半顯示 skeleton,視覺上會像「半載入」狀態,使用者不知道這筆資料到底算不算讀完。Row 是原子單位,要嘛全 skeleton 要嘛全真實"
+        >
+          <div className="flex items-center gap-3 border border-border rounded-lg p-3 w-72">
+            <div className="flex items-center justify-center h-10 w-10 rounded-full bg-primary text-on-emphasis text-body font-medium">陳</div>
+            <div className="flex flex-col gap-2 flex-1">
+              <span className="text-body">陳小明</span>
+              <Skeleton className="h-3 w-24" />
+            </div>
+          </div>
+          <Label warn>Avatar + name 已載,email 還在 skeleton → 使用者困惑「這筆好了沒」</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不用 Skeleton 取代 Empty 或 Error"
+          note="確定沒有資料 → Empty;載入失敗 → Alert + 重試按鈕。Skeleton 的語意是「還沒來」,不是「沒有」也不是「壞了」"
+        >
+          <Label warn>Skeleton 無錯誤語意 → 使用者會一直等,不會重試</Label>
+        </Rule>
+      </Section>
+
+      <Section title="vs 近親元件">
+        <Rule
+          title="Skeleton — 佈局已知,等資料填入即成最終樣貌"
+          note="初次載入 list / table / card grid 時使用。Skeleton 的形狀貼近真實內容,資料回來後版面不跳動,使用者預期不被打破"
+        >
+          <div className="flex flex-col gap-2 w-72 border border-border rounded-lg p-3">
+            <div className="flex items-center gap-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>
+          </div>
+          <Label>Linear 專案成員列表:佈局固定,只等資料填入</Label>
+        </Rule>
+
+        <Rule
+          title="CircularProgress — 不可預期時長 / 不知佈局的操作"
+          note="Button loading、form submitting、小區塊 inline 等待——當「會出現什麼」不確定,或根本不是內容佔位而是行為回饋時,用 CircularProgress(indeterminate)"
+        >
+          <div className="flex items-center gap-2 border border-border rounded-md px-3 py-2 w-72">
+            <CircularProgress />
+            <span className="text-body text-fg-muted">正在送出訂單...</span>
+          </div>
+          <Label>Stripe 結帳送出中:沒有「佈局」可佔位,只是行為回饋</Label>
+        </Rule>
+
+        <Rule
+          title="判準——先問「佈局已知嗎?」"
+          note="能描述「資料回來後會是什麼樣」→ Skeleton;只知道「有事情在進行」→ CircularProgress"
+        >
+          <Label>佈局已知 → Skeleton(內容佔位)</Label>
+          <Label>佈局未知 → CircularProgress(行為回饋)</Label>
+        </Rule>
+      </Section>
+    </div>
+  ),
+}
+
+export const ShapeMatchRule: Story = {
+  name: '形狀貼合真實內容',
+  render: () => (
+    <div>
+      <Rule
+        title="✅ 形狀模擬最終內容"
+        note="avatar 圓形對應圓形頭像、text 行寬度對應真實文字長度、title 高度對應標題字級。資料回來後使用者不會感到「跳版」"
+      >
+        {/* 2026-06-11:改為「載入中 vs 載入完成」對照(原單卡 demo 與使用指引「vs 近親元件」段重複)。 */}
+        <div className="flex flex-col gap-2">
+          <div className="flex items-center gap-3 border border-border rounded-lg p-3 w-72">
+            <Skeleton className="h-10 w-10 rounded-full" />
+            <div className="flex flex-col gap-2 flex-1">
+              <Skeleton className="h-4 w-32" />
+              <Skeleton className="h-3 w-48" />
+            </div>
+          </div>
+          <Label>載入中 — 圓形對應頭像、兩行對應名字 + 最新訊息</Label>
+        </div>
+        <div className="flex flex-col gap-2">
+          <div className="flex items-center gap-3 border border-border rounded-lg p-3 w-72">
+            <div className="flex items-center justify-center h-10 w-10 rounded-full bg-primary text-on-emphasis text-body font-medium shrink-0">林</div>
+            <div className="flex flex-col gap-0.5 flex-1 min-w-0">
+              <span className="text-body font-medium">林雅婷</span>
+              <span className="text-caption text-fg-secondary truncate">已傳送設計稿連結,請查收</span>
+            </div>
+          </div>
+          <Label>載入完成 — 形狀一一對應,版面不跳動(Slack DM 列表)</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ 過度代表——塞太多 skeleton 讓畫面看起來「很重」"
+        note="skeleton 密度超過真實內容會讓使用者以為「資料很多」,實際回來卻很少,體感是畫面縮水"
+      >
+        <div className="flex flex-col gap-2 border border-border rounded-lg p-3 w-72">
+          <Skeleton className="h-4 w-full" />
+          <Skeleton className="h-4 w-full" />
+          <Skeleton className="h-4 w-full" />
+          <Skeleton className="h-4 w-full" />
+          <Skeleton className="h-4 w-full" />
+          <Skeleton className="h-4 w-full" />
+          <Skeleton className="h-4 w-full" />
+        </div>
+        <Label warn>七行等寬色塊 → 真實內容只有兩行,資料回來版面縮水</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 不代表——形狀完全不對應真實內容"
+        note="拿方形佔位代表圓形 avatar、拿短色塊代表段落,資料回來後版面大幅跳動"
+      >
+        <div className="flex items-center gap-3 border border-border rounded-lg p-3 w-72">
+          <Skeleton className="h-10 w-10" />
+          <Skeleton className="h-4 w-8" />
+        </div>
+        <Label warn>方形色塊無法代表圓形頭像,短色塊無法代表姓名欄位</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const DurationRule: Story = {
+  name: '顯示時間短暫',
+  render: () => (
+    <div>
+      <Rule
+        title="✅ 短暫顯示(1–3s)——初次載入完成即替換為真實內容"
+        note="Skeleton 的語意是「資料很快會來」。短時間出現後被真實內容取代,是它設計上最順暢的樣子"
+      >
+        <div className="flex flex-col gap-2 border border-border rounded-lg p-3 w-72">
+          <Skeleton className="h-4 w-1/2" />
+          <Skeleton className="h-3 w-3/4" />
+        </div>
+        <Label>Notion 頁面載入:&lt; 2s 完成,Skeleton 合理</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 長時間(&gt; 10s)一直 Skeleton——使用者懷疑卡住"
+        note="長時間靜態 skeleton 會讓使用者以為網路斷線或系統卡住。此時改用 CircularProgress + 進度文案(「處理中,大約 10 秒」),或 ProgressBar"
+      >
+        <div className="flex items-center gap-2 border border-border rounded-md px-3 py-2 w-72">
+          <CircularProgress />
+          <span className="text-body text-fg-muted">分析中,這可能需要一分鐘...</span>
+        </div>
+        <Label>&gt; 10s 的長工作 → 改用 CircularProgress + 進度文字,告知使用者仍在處理</Label>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/Skeleton/skeleton.spec.md

@@ -0,0 +1,106 @@
+---
+component: Skeleton
+family: self-contained
+variants: {}
+sizes: {}
+traits:
+  - isMatrixHeavy
+benchmark:
+  - Ant Design Skeleton: github.com/ant-design/ant-design/tree/master/components/skeleton
+  - MUI Skeleton: github.com/mui/material-ui/tree/master/packages/mui-material/src/Skeleton
+  - Polaris SkeletonBodyText: github.com/Shopify/polaris/tree/main/polaris-react/src/components/SkeletonBodyText
+---
+
+# Skeleton 設計原則
+
+## 定位
+
+Skeleton 是**載入中的內容佔位符**——在資料載入完成前，用灰色色塊模擬真實內容的形狀與排版，讓使用者預期即將出現的佈局。
+
+**Layout Family**：非上述 family — self-contained primitive（獨立視覺，無 slot 結構）。
+
+**實作基礎**：shadcn passthrough——純 CSS opacity-pulse div（`animate-pulse`，不透明度脈動，非掃光/漸層動畫）。本 DS 保留 shadcn 原結構 + 橋接 DS token。
+
+---
+
+## 何時用
+
+- **初次載入資料的 list / table / card grid**：保留內容形狀讓使用者預期佈局
+- **非同步載入的 dashboard widget / chart**：資料來之前填滿空間避免跳動
+- **內容切換後的短暫載入**：router 切換、tab 切換後的過渡狀態
+- **已知佈局結構的等待**：佈局固定 + 資料動態的場景
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 小區塊 / 按鈕內的 loading | `CircularProgress` | CircularProgress(indeterminate)適合不佔空間的小 inline loading |
+| 整頁 / overlay loading | `<Empty icon={<CircularProgress/>}/>` compose | Skeleton 是內容佔位,不是頁面遮罩 |
+| 確認「沒有資料」的空狀態 | `Empty` | Empty 是「確定沒有」,Skeleton 是「還沒來」 |
+| 錯誤 / 失敗狀態 | `Alert` + 重試 | Skeleton 無錯誤語意 |
+| 進度有具體百分比 | `ProgressBar` / `CircularProgress`(有 value) | Skeleton 是不定進度占位,有 % 用 determinate progress |
+
+---
+
+## Skeleton vs CircularProgress
+
+| | Skeleton | CircularProgress(indeterminate) |
+|---|---|---|
+| 視覺 | 內容形狀占位(灰色色塊) | 旋轉圓弧 |
+| 尺寸 | 隨內容(list row / card / text line) | 自由 size(常用 16 / 20 / 24 / 48) |
+| 訊號強度 | 弱(暗示「佈局已就位」) | 強(暗示「正在處理」) |
+| 典型用途 | 初次載入 list / grid | Button loading、cell 載入、inline 等待 |
+
+**判準**:
+- **有已知佈局結構需保留 → Skeleton**(佔位、防跳動)
+- **小區塊 / inline 等待 → CircularProgress**(無 value,indeterminate)
+- **長載入換手**(先 Skeleton、超時換 progress):> 3s 的 fallback 規則見「A11y 預設」「替代文字」段
+
+---
+
+## 禁止事項
+
+- ❌ 用 Skeleton 取代 Empty（確定沒有資料的空狀態）——語意不同
+- ❌ 用 Skeleton 取代 error state——錯誤需要明確提示 + 解決路徑
+- ❌ Skeleton 形狀嚴重偏離真實內容——會讓使用者預期被打破、體感更慢
+- ❌ 長時間（> 10s）的 loading 一直用 Skeleton——使用者會懷疑是否卡住，需改用 progress indicator 或說明文字（10s = 硬性上限；> 3s 起即建議換手，見「A11y 預設」「替代文字」段）
+
+---
+
+## 為何無 Inspector / ColorMatrix / SizeMatrix / StateBehavior
+
+Skeleton 是 pure passive primitive(占位用的 opacity-pulse div),刻意無變體:
+
+- **無 Inspector**:Skeleton 唯一變因是「形狀」(w / h / rounded),由 consumer 透過 className 決定。互動 Inspector 無 prop 可調——該討論的是「怎麼畫出符合實際內容的形狀」,由 `CommonShapes` story 覆蓋。
+- **無 ColorMatrix**:Skeleton 底色固定為 `bg-muted`(對齊 `color.spec.md`「Static Subtle」段「placeholder / 退化」原則;2026-05-20 修正歷史 drift `bg-secondary`)。Dark mode 自動由 semantic token 處理,加 color variant 會誤導成狀態變化(Skeleton 是 loading 中,不該有語意色)。
+- **無 SizeMatrix**:Skeleton 無 size prop,尺寸完全由 consumer className(`w-32 h-4`)或 parent 決定——因為它要精確模擬內容形狀,不能限制成 sm/md/lg tier。
+- **無 StateBehavior**:Skeleton 只有「顯示 / 不顯示」兩態(consumer unmount 即消失),無 hover / focus / active / selected / disabled——非互動元件。
+
+對應 anatomy story:保留 `Overview` + 元件特有 `CommonShapes`(避免漂移的標準形狀庫)+ `DesignPrinciple`(與 CircularProgress 的分界)+ `Accessibility`(2026-05-17 加)。
+
+---
+
+## A11y 預設
+
+Skeleton 是**純視覺 loading placeholder**,預設 ARIA 行為:
+
+- **無內建 ARIA**:Skeleton 實作只是一個套用 pulse 動畫的 div(`{...props}` 原樣傳遞),不會自動設任何 ARIA 屬性。SR 不該朗讀 N 條 placeholder shape,因此 consumer 若需要對 SR 隱藏這些佔位塊,應自行在容器設 `aria-hidden="true"`
+- **`aria-busy="true"` 由 consumer 容器 own**:loading region 的容器(如 DataTable / Card / Sidebar group)應設 `aria-busy="true"`,告知 SR「該區域 loading 中」;data ready 後 consumer 移除 `aria-busy` 同時 unmount Skeleton
+- **不取得 focus**:Skeleton 永遠 non-interactive,無鍵盤行為
+- **動畫**:`prefers-reduced-motion: reduce` 用戶自動 stop pulse 動畫(`skeleton.tsx:10` 的 `motion-reduce:animate-none`)。pulse 是自動播放的循環動畫,歸 WCAG 2.2.2 Pause, Stop, Hide(Level A);honor `prefers-reduced-motion` 即滿足。注意非 2.3.3 Animation from Interactions(該 SC 是 Level AAA,僅涵蓋由互動 / 捲動觸發的位移動畫,不適用 auto-play loop)
+- **替代文字**:長時間 loading(>3s)consumer 應 fallback 為 `<Empty icon={<CircularProgress/>} description="載入中..." />`(SR-friendly text)— Skeleton 適合 < 3s 短暫 placeholder(3s 為建議換手值;> 10s 仍用 Skeleton 屬「禁止事項」硬性違規)
+- **驗證**:Storybook a11y addon panel 0 critical violation。Skeleton 本身無文字內容、無互動角色,axe 不會要求 label;若 consumer 把 Skeleton 包進有語意的容器,label 由該容器負責
+
+## 相關
+
+- `../CircularProgress/circular-progress.spec.md` — 小區塊 / inline loading 的對應元件(取代 Spinner)
+- `../Empty/empty.spec.md` — 確定沒有資料的空狀態
+- `../Alert/alert.spec.md` — 錯誤 / 失敗狀態
+- `../../tokens/color/color.spec.md` — Skeleton 底色 token（`bg-muted` 靜態底色 + `animate-pulse` opacity 脈動,2026-05-20 修 drift）
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `circular-progress.spec.md`
+- `progress-bar.spec.md`

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

@@ -0,0 +1,137 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+// @story-baseline: packages/design-system/src/components/DataTable/data-table.stories.tsx#NumberAlignment
+import type { Meta, StoryObj } from '@storybook/react'
+import type { ColumnDef } from '@tanstack/react-table'
+import { Skeleton } from './skeleton'
+import { DataTable } from '@/design-system/components/DataTable/data-table'
+import '@/design-system/components/DataTable/column-types' // ColumnMeta declaration merging
+
+/**
+ * Skeleton 展示——在資料載入完成前，用灰色色塊模擬真實內容的形狀與排版。
+ * 何時用、何時改用近親元件，見「設計原則」頁；各種形狀與屬性，見「設計規格」頁。
+ *
+ * 展示範例均對標世界級產品的真實載入情境（Linear task detail、Stripe dashboard、
+ * Notion sidebar、GitHub PR list），讓讀者能直接類推到自己產品的佈局。
+ */
+
+const meta: Meta = {
+  title: 'Design System/Components/Skeleton/展示',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+export const Default: Story = {
+  name: '預設',
+  render: () => (
+    <div className="flex flex-col gap-2 max-w-md">
+      <Skeleton className="h-4 w-full" />
+      <Skeleton className="h-4 w-full" />
+      <Skeleton className="h-4 w-3/4" />
+    </div>
+  ),
+}
+
+export const UserProfileCard: Story = {
+  name: '個人資料卡載入',
+  render: () => (
+    <div className="border border-border rounded-lg p-4 max-w-sm flex items-center gap-3">
+      <Skeleton className="h-12 w-12 rounded-full" />
+      <div className="flex flex-col gap-2 flex-1">
+        <Skeleton className="h-4 w-32" />
+        <Skeleton className="h-3 w-48" />
+      </div>
+    </div>
+  ),
+}
+
+export const TaskListLoading: Story = {
+  name: '任務列表載入',
+  render: () => (
+    <div className="flex flex-col gap-1 max-w-2xl border border-border rounded-lg divide-y divide-border">
+      {Array.from({ length: 5 }).map((_, i) => (
+        <div key={i} className="flex items-center gap-3 px-4 py-3">
+          <Skeleton className="h-4 w-4 rounded-full" />
+          <Skeleton className="h-4 w-16" />
+          <Skeleton className="h-4 flex-1" />
+          <Skeleton className="h-6 w-16 rounded-full" />
+          <Skeleton className="h-6 w-6 rounded-full" />
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+/* ── 表格列載入 ──
+   消費真 <DataTable>(per data-table.spec.md「狀態處理職責邊界」:DataTable 禁內建 loading prop,
+   無資料載入由 consumer 渲 Skeleton placeholder rows;對齊 MUI X `noRowsVariant=skeleton` /
+   Carbon DataTableSkeleton「header 可見 + body cell skeleton」派)。
+   Columns 不設 meta.type → 走 consumer 自訂 cell 渲 Skeleton(meta.type 命中 registry 會繞過自訂 cell)。 */
+interface LoadingRow {
+  id: string
+}
+
+const LOADING_ROWS: LoadingRow[] = Array.from({ length: 4 }, (_, i) => ({ id: `loading-${i + 1}` }))
+
+const loadingColumns: ColumnDef<LoadingRow>[] = [
+  { id: 'txn', header: '交易編號', meta: { width: 160 }, cell: () => <Skeleton className="h-4 w-28" /> },
+  { id: 'amount', header: '金額', meta: { width: 110, align: 'right' }, cell: () => <Skeleton className="h-4 w-16" /> },
+  {
+    id: 'customer',
+    header: '客戶',
+    meta: { width: 200 },
+    cell: () => (
+      <div className="flex items-center gap-2">
+        <Skeleton className="h-6 w-6 rounded-full" />
+        <Skeleton className="h-4 w-24" />
+      </div>
+    ),
+  },
+  { id: 'date', header: '日期', meta: { width: 130 }, cell: () => <Skeleton className="h-4 w-20" /> },
+]
+
+export const TableRowLoading: Story = {
+  name: '表格列載入',
+  render: () => (
+    <div aria-busy="true" className="max-w-3xl">
+      <DataTable columns={loadingColumns} data={LOADING_ROWS} getRowId={(r) => r.id} height="auto" />
+    </div>
+  ),
+}
+
+export const DocumentLoading: Story = {
+  name: '文件載入',
+  render: () => (
+    <div className="flex flex-col gap-4 max-w-2xl">
+      <Skeleton className="h-8 w-1/2" />
+      <div className="flex items-center gap-2">
+        <Skeleton className="h-5 w-5 rounded-full" />
+        <Skeleton className="h-3 w-32" />
+      </div>
+      <div className="flex flex-col gap-2 mt-2">
+        <Skeleton className="h-4 w-full" />
+        <Skeleton className="h-4 w-full" />
+        <Skeleton className="h-4 w-4/5" />
+      </div>
+      <div className="flex flex-col gap-2 mt-2">
+        <Skeleton className="h-4 w-full" />
+        <Skeleton className="h-4 w-3/4" />
+      </div>
+    </div>
+  ),
+}
+
+export const CardGridLoading: Story = {
+  name: '卡片網格載入',
+  render: () => (
+    <div className="grid grid-cols-3 gap-4 max-w-4xl">
+      {Array.from({ length: 6 }).map((_, i) => (
+        <div key={i} className="border border-border rounded-lg p-3 flex flex-col gap-3">
+          <Skeleton className="h-32 w-full rounded-md" />
+          <Skeleton className="h-4 w-3/4" />
+          <Skeleton className="h-3 w-1/2" />
+        </div>
+      ))}
+    </div>
+  ),
+}

package/src/components/Skeleton/skeleton.tsx

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

package/src/components/Slider/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 './slider'