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

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-h3 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

@@ -3,8 +3,7 @@ component: Skeleton
 family: self-contained
 variants: {}
 sizes: {}
-traits:
-  - isMatrixHeavy
+traits: []  # 2026-07-04 audit:移除幻影 isMatrixHeavy(spec body「為何無 Matrix」明文 rationale + 0 matrix stories,trait 與自家宣告矛盾)
 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
@@ -19,14 +18,14 @@ Skeleton 是**載入中的內容佔位符**——在資料載入完成前，用
 
 **Layout Family**：非上述 family — self-contained primitive（獨立視覺，無 slot 結構）。
 
-**實作基礎**：shadcn passthrough——純 CSS animated gradient div。本 DS 保留 shadcn 原結構 + 橋接 DS token。
+**實作基礎**：shadcn passthrough——純 CSS opacity-pulse div（`animate-pulse`，不透明度脈動，非掃光/漸層動畫）。本 DS 保留 shadcn 原結構 + 橋接 DS token。
 
 ---
 
 ## 何時用
 
 - **初次載入資料的 list / table / card grid**：保留內容形狀讓使用者預期佈局
-- **非同步載入的 dashboard widget / chart**：資料來之前填滿空間避免跳動
+- **非同步載入的 dashboard widget / chart**：資料抵達前保留既定版面區域，降低 cumulative layout shift
 - **內容切換後的短暫載入**：router 切換、tab 切換後的過渡狀態
 - **已知佈局結構的等待**：佈局固定 + 資料動態的場景
 
@@ -52,8 +51,9 @@ Skeleton 是**載入中的內容佔位符**——在資料載入完成前，用
 | 典型用途 | 初次載入 list / grid | Button loading、cell 載入、inline 等待 |
 
 **判準**:
-- **有已知佈局結構需保留 → Skeleton**(佔位、防跳動)
+- **有已知佈局結構需保留 → Skeleton**(預留結構與空間)
 - **小區塊 / inline 等待 → CircularProgress**(無 value,indeterminate)
+- **長載入換手**(先 Skeleton、超時換 progress):> 3s 的 fallback 規則見「A11y 預設」「替代文字」段
 
 ---
 
@@ -62,20 +62,20 @@ Skeleton 是**載入中的內容佔位符**——在資料載入完成前，用
 - ❌ 用 Skeleton 取代 Empty（確定沒有資料的空狀態）——語意不同
 - ❌ 用 Skeleton 取代 error state——錯誤需要明確提示 + 解決路徑
 - ❌ Skeleton 形狀嚴重偏離真實內容——會讓使用者預期被打破、體感更慢
-- ❌ 長時間（> 10s）的 loading 一直用 Skeleton——使用者會懷疑是否卡住，需改用 progress indicator 或說明文字
+- ❌ 長時間（> 10s）的 loading 一直用 Skeleton——使用者會懷疑是否卡住，需改用 progress indicator 或說明文字（10s = 硬性上限；> 3s 起即建議換手，見「A11y 預設」「替代文字」段）
 
 ---
 
 ## 為何無 Inspector / ColorMatrix / SizeMatrix / StateBehavior
 
-Skeleton 是 pure passive primitive(占位用的 animated gradient div),刻意無變體:
+Skeleton 是 pure passive primitive(占位用的 opacity-pulse div),刻意無變體:
 
 - **無 Inspector**:Skeleton 唯一變因是「形狀」(w / h / rounded),由 consumer 透過 className 決定。互動 Inspector 無 prop 可調——該討論的是「怎麼畫出符合實際內容的形狀」,由 `CommonShapes` story 覆蓋。
-- **無 ColorMatrix**:Skeleton 底色固定為 `bg-muted`(2026-05-20 修正歷史 drift `bg-secondary`,實際 `skeleton.tsx:10` 用 `bg-muted` — 對齊 `color.spec.md` 「Static Subtle」段「placeholder / 退化」原則)。Dark mode 自動由 semantic token 處理,加 color variant 會誤導成狀態變化(Skeleton 是 loading 中,不該有語意色)。
+- **無 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 的分界)。
+對應 anatomy story:保留 `Overview` + 元件特有 `CommonShapes`(避免漂移的標準形狀庫)+ `DesignPrinciple`(與 CircularProgress 的分界)+ `Accessibility`(2026-05-17 加)。
 
 ---
 
@@ -83,22 +83,23 @@ Skeleton 是 pure passive primitive(占位用的 animated gradient div),刻意
 
 Skeleton 是**純視覺 loading placeholder**,預設 ARIA 行為:
 
-- **`aria-hidden="true"`(預設,Skeleton 內部自動設)**:Skeleton 純視覺占位,SR 不朗讀 N 條 placeholder shape
+- **無內建 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 動畫(對齊 WCAG 2.3.3 Animation from Interactions)
-- **替代文字**:長時間 loading(>3s)consumer 應 fallback 為 `<Empty icon={<CircularProgress/>} description="載入中..." />`(SR-friendly text)— Skeleton 適合 < 3s 短暫 placeholder
-- **驗證**:Storybook a11y addon panel 0 critical violation;不該被 axe 警告「missing label」(因為 aria-hidden 排除)
+- **動畫**:`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` / animated gradient,2026-05-20 修 drift）
+- `../../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,134 @@
+// @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.anatomy.stories.tsx#AlignmentRule
+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/展示',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { description: { component: '在資料載入期間以接近最終內容的色塊保留版面，降低跳動並預告資訊結構。已知內容形狀且等待時間短時使用；未知進度工作改用進度指示。' } },
+  },
+}
+export default meta
+type Story = StoryObj
+
+// Default retired 2026-07-14 per audit Dim 24(story 重複性):「預設」的三行文字骨架
+// pattern 與 DocumentLoading 段落骨架完全同構,且抽象「預設」違「範例必真實業務場景」;
+// 由 UserProfileCard / TaskListLoading / DocumentLoading 等真實情境 story 覆蓋。
+
+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

@@ -17,14 +17,14 @@ Skeleton.displayName = "Skeleton"
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const skeletonMeta = {
   component: 'Skeleton',
-  family: null, // non-family composite / overlay / layout
+  family: 'self-contained', // 對齊 skeleton.spec.md frontmatter(SSOT;同 ScrollArea meta 寫法)
   variants: {
 
   },
   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'