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

package/src/components/AspectRatio/aspect-ratio.anatomy.stories.tsx

@@ -0,0 +1,208 @@
+// @anatomy-rationale:
+//   ColorMatrix N/A — AspectRatio 是 pure layout primitive,bg / radius 由
+//     consumer 透過 className 決定,本身無色彩 token。
+//   SizeMatrix N/A — 寬度由父層決定、高度由 ratio 算出;非離散 size tier。
+//     5 個 DS 標準 ratio 由 StandardRatios 涵蓋。
+//   StateBehavior N/A — 容器 primitive 無 hover / focus / active 狀態。
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { AspectRatio } from './aspect-ratio'
+import { H3, Desc, Td, Th } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+/**
+ * AspectRatio 設計規格——固定長寬比容器 primitive。
+ *
+ * 本元件極薄(Radix AspectRatio passthrough),無 variant / size / color token。
+ * 結構僅:container 鎖 ratio + children 填滿。因此 anatomy 保留 Overview + Inspector
+ * + 元件特有 StandardRatios(DS 慣用 5 ratio)+ Accessibility(2026-05-17 Dim 13)
+ * ——無 ColorMatrix / SizeMatrix / StateBehavior,rationale 詳見
+ * `aspect-ratio.spec.md`「為何無 ColorMatrix / SizeMatrix / StateBehavior」段。
+ */
+
+const meta: Meta = {
+  title: 'Design System/Components/AspectRatio/設計規格',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Overview ──────────────────────────────────────────────────────────────────
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>Anatomy</H3>
+        <Desc>AspectRatio 是 container 型 primitive:外層(container)鎖定 `ratio` 數值,內層 children 填滿。典型 consumer 傳 img + `className="w-full h-full object-cover"` 讓圖填滿不變形。</Desc>
+        <div className="flex gap-6 items-start">
+          <div className="w-[320px]">
+            <AspectRatio ratio={16 / 9} className="bg-muted rounded-md overflow-hidden ring-1 ring-dashed ring-border">
+              <div className="w-full h-full flex items-center justify-center text-caption text-fg-muted">
+                children(fills)
+              </div>
+            </AspectRatio>
+            <div className="text-footnote text-fg-muted mt-1 font-mono">
+              container: ratio={'{16/9}'}, width=100%, height=auto
+            </div>
+          </div>
+          <div className="text-caption text-fg-muted max-w-[320px] leading-relaxed">
+            <div className="mb-2"><span className="font-mono text-foreground">container</span> — 父層決定寬度(此處 320px),AspectRatio 依 ratio 自動算高(180px = 320 × 9/16)</div>
+            <div><span className="font-mono text-foreground">children</span> — 放在內層容器(絕對定位 inset:0 的視覺盒)的正常流中,需自行加 w-full h-full(+ object-cover)才會填滿;通常是 img / video / illustration</div>
+          </div>
+        </div>
+      </div>
+
+      <div>
+        <H3>Props 速查</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
+            <tbody>
+              <tr><Td mono>ratio</Td><Td mono>number</Td><Td mono>1</Td><Td>寬 / 高比值(如 16/9 = 1.777)。DS 標準 ratio 見下方對照</Td></tr>
+              <tr><Td mono>asChild</Td><Td mono>boolean</Td><Td mono>false</Td><Td>Radix Slot pattern——把 ratio 行為合併到 children 元素(不常用)</Td></tr>
+              <tr><Td mono>className</Td><Td mono>string</Td><Td mono>—</Td><Td>套在內層容器(絕對定位的視覺可見層,放 bg-muted / rounded-lg / overflow-hidden)</Td></tr>
+              <tr><Td mono>children</Td><Td mono>ReactNode</Td><Td mono>—</Td><Td>填滿容器的內容(通常是 img + object-cover)</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+// ── Inspector ─────────────────────────────────────────────────────────────────
+
+const RATIO_PRESETS = [
+  { label: '16/9', value: 16 / 9 },
+  { label: '4/3', value: 4 / 3 },
+  { label: '1/1', value: 1 },
+  { label: '3/4', value: 3 / 4 },
+  { label: '21/9', value: 21 / 9 },
+]
+
+const InspectorDemo = () => {
+  const [preset, setPreset] = React.useState('16/9')
+  const current = RATIO_PRESETS.find(r => r.label === preset) ?? RATIO_PRESETS[0]
+  return (
+    <div>
+      <div className="flex gap-2 mb-6">
+        {RATIO_PRESETS.map(r => (
+          <button
+            key={r.label}
+            type="button"
+            onClick={() => setPreset(r.label)}
+            className={`px-3 py-1.5 rounded-md text-caption font-mono border ${
+              preset === r.label
+                ? 'bg-foreground text-inverse-fg border-foreground'
+                : 'bg-canvas text-foreground border-border hover:bg-neutral-hover'
+            }`}
+          >
+            {r.label}
+          </button>
+        ))}
+      </div>
+
+      <div className="grid grid-cols-[1fr_320px] gap-8 items-start">
+        <div>
+          <div className="text-footnote text-fg-muted mb-2 font-mono">即時預覽(容器 width=420px)</div>
+          <div className="w-[420px]">
+            <AspectRatio ratio={current.value} className="bg-muted rounded-md overflow-hidden">
+              <img
+                src={`https://picsum.photos/seed/inspector-${current.label}/800/600`}
+                alt=""
+                className="w-full h-full object-cover"
+              />
+            </AspectRatio>
+            <div className="text-footnote text-fg-muted mt-2 font-mono">
+              ratio={'{'}{current.label}{'}'} → width 420px, height {Math.round(420 / current.value)}px
+            </div>
+          </div>
+        </div>
+
+        <div className="border border-border rounded-lg p-4 flex flex-col gap-3 bg-muted">
+          <div className="text-footnote text-fg-secondary font-bold">Inspect</div>
+          <div className="flex flex-col gap-2 text-caption">
+            <div><span className="text-fg-muted">ratio</span> <span className="font-mono ml-2">{current.label} ({current.value.toFixed(4)})</span></div>
+            <div><span className="text-fg-muted">width</span> <span className="font-mono ml-2">100% (parent 控制)</span></div>
+            <div><span className="text-fg-muted">height</span> <span className="font-mono ml-2">auto (padding-bottom 算出)</span></div>
+            <div><span className="text-fg-muted">padding-bottom</span> <span className="font-mono ml-2">{(100 / current.value).toFixed(2)}%</span></div>
+            <div><span className="text-fg-muted">bg</span> <span className="font-mono ml-2">bg-muted(consumer 套)</span></div>
+            <div><span className="text-fg-muted">radius</span> <span className="font-mono ml-2">rounded-md(consumer 套)</span></div>
+          </div>
+          <div className="text-footnote text-fg-muted leading-relaxed mt-2">
+            AspectRatio 本身無 token——bg / radius / overflow 全由 consumer 透過 className 決定。Radix 內部以 padding-bottom 技巧鎖比例(SSR-safe)。
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export const Inspector: Story = {
+  name: '元件檢閱器',
+  render: () => (
+    <div>
+      <H3>互動 ratio 切換</H3>
+      <Desc>點選常用 ratio,觀察容器高度變化與 Inspect 面板的 padding-bottom 計算。AspectRatio 是純佈局容器,無 color / size token,只有 ratio 一個決定性 prop。</Desc>
+      <InspectorDemo />
+    </div>
+  ),
+}
+
+// NOTE: 本元件無 ColorMatrix / SizeMatrix / StateBehavior——
+// rationale 詳見 aspect-ratio.spec.md「為何無 ColorMatrix / SizeMatrix / StateBehavior」段。
+// 僅保留 StandardRatios 作為元件特有的 DS ratio 視覺對照。
+
+// ── 標準 ratio 對照 ──────────────────────────────────────────────────────────
+
+const STD_RATIOS = [
+  { label: '16/9', value: 16 / 9, use: '寬螢幕 hero / 影片 embed / feature 截圖', seed: 'std-16-9' },
+  { label: '4/3', value: 4 / 3, use: '產品照 / screenshot / 老電視比例', seed: 'std-4-3' },
+  { label: '1/1', value: 1, use: 'Avatar / 方圖貼文 / icon preview', seed: 'std-1-1' },
+  { label: '3/4', value: 3 / 4, use: '直式 portrait / 手機截圖', seed: 'std-3-4' },
+  { label: '21/9', value: 21 / 9, use: 'Ultra-wide hero / movie poster', seed: 'std-21-9' },
+]
+
+export const StandardRatios: Story = {
+  name: '標準 比例 視覺對照',
+  render: () => (
+    <div>
+      <H3>DS 標準 ratio</H3>
+      <Desc>五個 DS 慣用 ratio 並列呈現(同一 consumer 容器寬度)。新需求優先選這五個,偏離 DS 標準需提出理由。</Desc>
+
+      <div className="flex flex-col gap-6">
+        {STD_RATIOS.map(r => (
+          <div key={r.label} className="grid grid-cols-[140px_1fr_1fr] gap-4 items-center">
+            <div>
+              <div className="text-body font-mono font-bold">{r.label}</div>
+              <div className="text-footnote text-fg-muted font-mono">{r.value.toFixed(4)}</div>
+            </div>
+            <div className="w-full max-w-[360px]">
+              <AspectRatio ratio={r.value} className="bg-muted rounded-md overflow-hidden">
+                <img
+                  src={`https://picsum.photos/seed/${r.seed}/720/540`}
+                  alt=""
+                  className="w-full h-full object-cover"
+                />
+              </AspectRatio>
+            </div>
+            <div className="text-caption text-fg-muted leading-relaxed">{r.use}</div>
+          </div>
+        ))}
+      </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 包 AspectRatio 進互動容器(Button / Card / Link)時 a11y 由容器決定。"}</p>
+    </div>
+  ),
+}

package/src/components/AspectRatio/aspect-ratio.principles.stories.tsx

@@ -0,0 +1,303 @@
+// @principles-rationale: Merged WhenToUse + WhenNotToUse into a single
+// `UsageGuidance` story (3 sections — 何時用 / 何時不用 + 替代 / vs 近親 N/A) per
+// 2026-04-26 user mandate. AspectRatio has no Vs*Rule (no near-sibling component).
+// RatioChoice / ChildrenFillRule / PlaceholderAndSkeleton kept as separate principles.
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import LinkTo from '@storybook/addon-links/react'
+import { AspectRatio } from './aspect-ratio'
+import { Skeleton } from '@/design-system/components/Skeleton/skeleton'
+
+/**
+ * AspectRatio 設計原則——何時用 / 不用 / 如何選 ratio / 與 Skeleton 分界。
+ * 完整規則見 `aspect-ratio.spec.md`。
+ */
+
+const meta: Meta = {
+  title: 'Design System/Components/AspectRatio/設計原則',
+  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-4 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 Img = ({ seed, ratio }: { seed: string; ratio: number }) => {
+  const h = Math.round(800 / ratio)
+  return (
+    <img
+      src={`https://picsum.photos/seed/${seed}/800/${h}`}
+      alt=""
+      className="w-full h-full object-cover"
+    />
+  )
+}
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <Rule
+          title="✅ 使用 — 防止圖片未載入時的 layout 坍塌(CLS)"
+          note="圖片 src 還沒 ready 時,若容器高度為 0,頁面 layout 會在載入後跳動(Cumulative Layout Shift 問題)。AspectRatio 鎖死比例 → 載入前後位置完全相同"
+        >
+          <div className="w-[320px]">
+            <AspectRatio ratio={16 / 9} className="bg-muted rounded-md overflow-hidden">
+              <Img seed="when-use-1" ratio={16 / 9} />
+            </AspectRatio>
+            <Label>↑ 載入後容器位置不跳動</Label>
+          </div>
+          <div className="w-[320px]">
+            <AspectRatio ratio={16 / 9} className="bg-muted rounded-md" />
+            <Label>↑ 未載入狀態仍佔滿 16/9 空間</Label>
+          </div>
+        </Rule>
+
+        <Rule
+          title="✅ 使用 — 多張圖片需要統一比例(carousel / product grid)"
+          note="輪播 / 產品列表各張圖原始比例不一,包 AspectRatio + object-cover 強制對齊,視覺整齊劃一"
+        >
+          <div className="grid grid-cols-3 gap-2 w-[480px]">
+            {['grid-a', 'grid-b', 'grid-c'].map(s => (
+              <AspectRatio key={s} ratio={1} className="bg-muted rounded-md overflow-hidden">
+                <Img seed={s} ratio={1} />
+              </AspectRatio>
+            ))}
+          </div>
+          <Label>↑ 原圖比例不同,AspectRatio + object-cover 強制對齊成 1/1</Label>
+        </Rule>
+      </Section>
+
+      <Section title="何時不用 + 替代">
+        <Rule
+          title="❌ content 高度本該隨內容變"
+          note="AspectRatio 鎖死比例,無法 hug content。文字 / 表單 / 按鈕等 content-driven 高度的區塊不包"
+        >
+          <div className="w-[320px] border border-dashed border-error rounded-md p-4">
+            <div className="text-body">標題文字</div>
+            <div className="text-caption text-fg-muted mt-2">
+              內容長度不固定的段落,包 AspectRatio 會強制裁切或留大片空白。
+            </div>
+          </div>
+          <Label warn>↑ 此類 content 不該鎖比例</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 圖片已固定 width + height 屬性"
+          note="AspectRatio 是給 responsive(width=100%)場景。若 img 已寫死 200×200,直接用 img 即可"
+        >
+          <div className="p-4 border border-dashed border-error rounded-md">
+            <img
+              src="https://picsum.photos/seed/fixed-size/160/160"
+              alt=""
+              width={160}
+              height={160}
+              className="rounded-md"
+            />
+          </div>
+          <Label warn>↑ 固定尺寸 img 不需要 AspectRatio 包裝</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不用於 flex / grid layout"
+          note="AspectRatio 是 container 鎖比例,不是佈局工具。多個元素並排用 flex / grid,不用 AspectRatio 排版"
+        >
+          <div className="w-[400px] border border-dashed border-error rounded-md p-4">
+            <AspectRatio ratio={4 / 1} className="bg-muted rounded-md flex items-center justify-around">
+              <div className="text-caption">Nike Pegasus 41</div>
+              <div className="text-caption">Adidas UltraBoost</div>
+              <div className="text-caption">New Balance 990</div>
+            </AspectRatio>
+          </div>
+          <Label warn>↑ 用 AspectRatio 當橫排容器是誤用 → 用 flex gap-2</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不放不該鎖比例的 content"
+          note="文字 / 表單 / 按鈕等隨內容高度的 content 放進 AspectRatio,會強制裁切或留大片空白,違背語意"
+        >
+          <div className="w-[320px] border border-dashed border-error rounded-md p-2">
+            <AspectRatio ratio={1} className="bg-muted rounded-md p-4">
+              <div className="text-body font-bold mb-1">表單標題</div>
+              <div className="text-caption text-fg-muted mb-2">這裡有一些說明文字,長度不固定。</div>
+              <input className="border border-border rounded-md px-2 py-1 w-full" placeholder="輸入內容" />
+            </AspectRatio>
+          </div>
+          <Label warn>↑ 表單內容不該鎖 1/1 比例</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不重疊多層 AspectRatio"
+          note="巢狀 AspectRatio 意義不明 — 外層比例與內層比例衝突時,結果無法預測"
+        >
+          <div className="w-[320px] border border-dashed border-error rounded-md p-2">
+            <AspectRatio ratio={16 / 9} className="bg-muted rounded-md overflow-hidden">
+              <AspectRatio ratio={1} className="bg-primary-subtle">
+                <div className="w-full h-full flex items-center justify-center text-caption">
+                  內層 1/1 被外層 16/9 壓縮
+                </div>
+              </AspectRatio>
+            </AspectRatio>
+          </div>
+          <Label warn>↑ 巢狀 AspectRatio 語意混亂,一律只包一層</Label>
+        </Rule>
+      </Section>
+
+      <Section title="vs 近親">
+        <p className="text-caption text-fg-muted max-w-[720px] leading-relaxed">
+          AspectRatio 無直接近親元件。語意「鎖死容器比例」是獨立 concern,不與其他 layout primitive 重疊
+          (Box / flex / grid 都不鎖比例)。與 Skeleton 是<strong>疊用</strong>關係(見「PlaceholderAndSkeleton」 story),不是替代關係。
+        </p>
+      </Section>
+    </div>
+  ),
+}
+
+// @story-history: 教「如何選 ratio」的決策邏輯(原則層),不是「5 個 ratio 長怎樣」
+//   的視覺對照——後者 SSOT 在 anatomy「標準 比例 視覺對照」(StandardRatios)。此處只給判斷準則
+//   + LinkTo,不重畫 5 張圖(per 2026-05-30 EXAMPLE_REDUNDANT prune,避免 3 file 各畫一次)。
+const RATIO_RULES = [
+  { label: '16/9', when: '橫向、寬螢幕,要「影片 / 電影」感但不到 ultra-wide', example: 'Airbnb listing hero、YouTube 縮圖、onboarding tour 截圖' },
+  { label: '4/3', when: '橫向但要更方,容納更多垂直內容', example: 'Stripe product listing、Notion gallery cover' },
+  { label: '1/1', when: 'feed grid 要對齊一致、無方向偏好', example: 'Instagram 貼文、Dribbble shot 縮圖' },
+  { label: '3/4', when: '直向,呈現「站立」視覺', example: '人物 portrait、iOS App Store screenshot' },
+  { label: '21/9', when: '極寬幅,強化 cinematic 視覺', example: 'Netflix 首頁 hero、電影海報' },
+]
+
+export const RatioChoice: Story = {
+  name: '如何選 ratio',
+  render: () => (
+    <div>
+      <p className="text-caption text-fg-muted max-w-[720px] leading-relaxed mb-8">
+        先看內容方向(橫 / 方 / 直),再對到下方的判斷準則即可選定。五個 ratio 的並排視覺對照見{' '}
+        <LinkTo kind="Design System/Components/AspectRatio/設計規格" name="標準 比例 視覺對照">
+          <span className="text-primary hover:text-primary-hover font-medium cursor-pointer">設計規格 → 標準 比例 視覺對照</span>
+        </LinkTo>
+        ,此處只講「怎麼選」的決策邏輯,不重畫圖。
+      </p>
+
+      <div className="flex flex-col gap-5 max-w-[720px]">
+        {RATIO_RULES.map(r => (
+          <div key={r.label} className="flex gap-4 items-baseline">
+            <div className="w-[60px] shrink-0 text-body font-mono font-bold text-foreground">{r.label}</div>
+            <div className="flex-1">
+              <div className="text-body text-foreground leading-relaxed">{r.when}</div>
+              <div className="text-caption text-fg-muted mt-0.5 leading-relaxed">{r.example}</div>
+            </div>
+          </div>
+        ))}
+      </div>
+
+      <p className="text-footnote text-fg-muted max-w-[720px] leading-relaxed mt-8">
+        偏離這五個標準 ratio 需提出理由——非標準比例會破壞 feed / grid 的視覺一致性。
+      </p>
+    </div>
+  ),
+}
+
+export const ChildrenFillRule: Story = {
+  name: 'children 要填滿容器',
+  render: () => (
+    <div>
+      <Rule
+        title="✅ 正確 — children 加 w-full h-full object-cover"
+        note="AspectRatio 本身不強制 children 尺寸;consumer 必須加 w-full h-full 讓 children 佔滿 + object-cover 防變形"
+      >
+        <div className="w-[320px]">
+          <AspectRatio ratio={16 / 9} className="bg-muted rounded-md overflow-hidden">
+            <img
+              src="https://picsum.photos/seed/fill-correct/800/450"
+              alt=""
+              className="w-full h-full object-cover"
+            />
+          </AspectRatio>
+          <Label>圖片填滿容器,裁切超出部分</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ 錯誤 — children 沒加 w-full h-full"
+        note="img 預設 inline-size,不會撐滿容器 → AspectRatio 鎖的空間內出現空白"
+      >
+        <div className="w-[320px]">
+          <AspectRatio ratio={16 / 9} className="bg-muted rounded-md overflow-hidden">
+            <img
+              src="https://picsum.photos/seed/fill-wrong/100/100"
+              alt=""
+            />
+          </AspectRatio>
+          <Label warn>↑ 左上角小圖 + 大片空白</Label>
+        </div>
+      </Rule>
+    </div>
+  ),
+}
+
+export const PlaceholderAndSkeleton: Story = {
+  name: '背景-muted 占位 與 Skeleton 的分界',
+  render: () => (
+    <div>
+      <Rule
+        title="bg-muted — 簡單 placeholder 色(載入前的「空間佔位」)"
+        note="AspectRatio 本身無色彩,consumer 慣例套 bg-muted 作為低成本 placeholder — 只表達「這裡會有圖」,無 loading 動態"
+      >
+        <div className="w-[320px]">
+          <AspectRatio ratio={16 / 9} className="bg-muted rounded-md" />
+          <Label>靜態灰底 — 圖片尚未載入的預設色</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="Skeleton — 明確的 loading state(脈動動畫)"
+        note="當需要明確告訴使用者「正在載入」,AspectRatio 疊 Skeleton:AspectRatio 負責鎖比例,Skeleton 負責表達 loading 狀態"
+      >
+        <div className="w-[320px]">
+          <AspectRatio ratio={16 / 9} className="rounded-md overflow-hidden">
+            <Skeleton className="w-full h-full" />
+          </AspectRatio>
+          <Label>AspectRatio(鎖比例)+ Skeleton(loading 動畫)</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="分界 — 兩者可疊用,職責不同"
+        note="AspectRatio = container 鎖比例(解決 CLS);Skeleton = loading state 視覺。「鎖比例」與「標示 loading」是兩個獨立問題,疊用是 慣用組合"
+      >
+        <div className="grid grid-cols-3 gap-3 w-[480px]">
+          {[1, 2, 3].map(i => (
+            <AspectRatio key={i} ratio={1} className="rounded-md overflow-hidden">
+              <Skeleton className="w-full h-full" />
+            </AspectRatio>
+          ))}
+        </div>
+        <Label>↑ Product grid loading state — 三格 1/1 + Skeleton</Label>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/AspectRatio/aspect-ratio.spec.md

@@ -3,13 +3,11 @@ component: AspectRatio
 family: self-contained
 variants: {}
 sizes: {}
-traits:
-  - isMatrixHeavy
+traits: []  # 2026-07-04 audit:移除幻影 isMatrixHeavy(spec body「為何無 Matrix」明文 rationale + 0 matrix stories,trait 與自家宣告矛盾)
 benchmark:
   - Radix AspectRatio primitive: github.com/radix-ui/primitives/tree/main/packages/react/aspect-ratio
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
 
 # AspectRatio 設計原則
 
@@ -22,7 +20,7 @@ AspectRatio 是**固定長寬比容器** primitive——確保內部 children(
 **Layout Family**:非上述 family — self-contained primitive(container 型 layout,無 slot 結構,只暴露 `ratio` 數值 + children)。
 
 **世界級對照**:
-- shadcn `AspectRatio`(本元件主要參考)— 同 Radix 薄包裝 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- 實作維持 Radix primitive 的薄包裝，不加入額外 sizing policy
 - Ant Design 無獨立元件(用 CSS aspect-ratio 或自訂 padding-bottom)
 - Material 無獨立元件(image/Card 元件內建 props)
 
@@ -30,7 +28,7 @@ AspectRatio 是**固定長寬比容器** primitive——確保內部 children(
 
 ## 何時用
 
-- **圖片容器未載入前防坍塌**:圖片 src 還沒 ready 時,容器高度若為 0 → 頁面 layout 跳動(CLS 問題)。AspectRatio 鎖死比例
+- **圖片載入前保留比例**:src 尚未 ready 時先保留已知 media geometry，降低 cumulative layout shift
 - **Coachmark / Tour media 區**:onboarding 截圖 / illustration 統一 ratio
 - **Carousel item 圖像**:輪播各張圖保持一致高度
 - **Card thumbnail**(未來):product card / blog post cover
@@ -52,7 +50,7 @@ AspectRatio 是**固定長寬比容器** primitive——確保內部 children(
 | **Skeleton** | Skeleton 是 loading placeholder + 預設尺寸;AspectRatio 是 ratio container | 內含 image / chart 等需保 ratio 的 ready content |
 | **Empty(image slot)** | Empty 是 page-state 元件;AspectRatio 是 layout primitive | 結構性 ratio 鎖,跟 content state 無關 |
 
-對齊 Radix AspectRatio / Material `<Box sx={{aspectRatio}}>` / Polaris MediaCard primitive 慣例:純結構 layout 元件。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+AspectRatio 是純結構 layout 元件：只建立比例 box，不擁有 media styling、loading state 或內容語意。
 
 ---
 
@@ -92,6 +90,20 @@ children 通常要 `className="w-full h-full object-cover"` 讓圖填滿容器;
 
 ---
 
+## 邊界案例
+
+- **極端 ratio**:`ratio` 接受任意正數,元件不驗證、不設上下限(`1/10` 極窄高 / `10/1` 極扁都照算);是否合理由 consumer 把關
+- **容器 resize**:高度恆 = 寬度 ÷ ratio(padding-bottom 百分比機制),父層寬度變化時高度自動跟隨,無需 JS
+- **children 超出**:元件不自動裁切 — 超出 ratio 容器的內容會溢出;裁切由 consumer 加 `overflow-hidden`(見 Consumer 範例)
+- **媒體原始比例 ≠ 容器 ratio**:呈現由 children 的 `object-cover`(裁滿)/ `object-contain`(留白)決定,元件不介入
+
+## 常見誤解
+
+- **AspectRatio 不是 responsive 佈局工具** — 只鎖比例;寬度仍由父層 / className 控制(見「為何無 SizeMatrix」)
+- **「直接寫 CSS `aspect-ratio` 就好?」** — DS 內一律消費本元件(既有 primitive 優先):Radix padding-bottom 方案 SSR-safe 且跨瀏覽器一致(見「定位」)
+
+---
+
 ## 為何無 ColorMatrix / SizeMatrix / StateBehavior
 
 AspectRatio 是 pure layout primitive(container 鎖比例),本身:
@@ -100,7 +112,7 @@ AspectRatio 是 pure layout primitive(container 鎖比例),本身:
 - **無 size prop**:寬度由 parent / className 控制,高度由 `ratio` 公式自動推導(`height = width / ratio`)。因此不提供 sm/md/lg size variant,不同尺寸透過外層容器寬度達成。故不建立 `SizeMatrix`——元件特有視覺對照改為 `StandardRatios`(DS 慣用 5 種 ratio)。
 - **無互動狀態**:無 hover / focus / active / selected / disabled(非互動元件,純 structural container)。故不建立 `StateBehavior`。
 
-對應 anatomy story:保留 `Overview` + `Inspector`(ratio 切換互動)+ 元件特有 `StandardRatios`。
+對應 anatomy story:保留 `Overview` + `Inspector`(ratio 切換互動)+ 元件特有 `StandardRatios` + `Accessibility`(2026-05-17 Dim 13)。
 
 ---
 
@@ -110,13 +122,13 @@ AspectRatio 是 pure layout primitive(container 鎖比例),本身:
 
 ---
 
-## shadcn passthrough 例外說明
+## shadcn 薄包裝說明
 
-AspectRatio export 為 `const AspectRatio = AspectRatioPrimitive.Root`(**直接 re-export Radix primitive,無額外 wrapper**),不套 `React.forwardRef` / `displayName` / `...props` spread / `asChild` 的 shadcn canonical 五件套。
+AspectRatio 是 Radix `AspectRatioPrimitive.Root` 的薄包裝:用 `React.forwardRef` 顯式轉發 ref、把 `...props` spread 到 Radix Root、並設定 `displayName = 'AspectRatio'`(對齊 shadcn canonical)。`ratio` / `asChild` 等 props 透過 spread 原封不動傳給 Radix。
 
-**為什麼豁免**:Radix `AspectRatioPrimitive.Root` 本身已實作這五件套(forwardRef-ed / displayName 為 `"AspectRatio"` / `...props` 內部 spread 至 inner `<div>` / asChild 透過 Slot 支援)。在我們自己 wrap 一層只會 indirection 不加值,且會 **break** Radix 內建的 displayName / Slot 支援。這是 shadcn-official 模式(shadcn 元件庫的 AspectRatio 也是直接 re-export),非 drift。
+**為什麼顯式 wrap 一層**:Radix primitive 本身雖已 forwardRef,但本 DS 慣例是每個對外 export 都顯式包一層,確保在 React DevTools / Storybook Inspector 顯示正確的 `displayName`,且 props passthrough 與 ref 行為在 code 層面明確可見。這層 wrapper 不加任何預設樣式,純粹保持命名與檢視一致。
 
-**何時需要自己 wrap**:若未來要加預設 className / 自訂 ratio 常數 / 內建 consumer 視覺 guard(如強制 border-radius),再 wrap。目前無此需求。
+**何時改寫這層**:若未來要加預設 className / 自訂 ratio 常數 / 內建 consumer 視覺 guard(如強制 border-radius),在這層 wrapper 內補即可。目前 wrapper 只做 passthrough。
 
 ---
 
@@ -125,7 +137,7 @@ AspectRatio export 為 `const AspectRatio = AspectRatioPrimitive.Root`(**直接
 - `../Coachmark/coachmark.spec.md` — **本元件 consumer**:media 區預設 `mediaRatio=16/9`
 - `../Carousel/carousel.spec.md` — 未來 consumer(item image 統一 ratio)
 - Radix AspectRatio — `@radix-ui/react-aspect-ratio`
-- shadcn AspectRatio — 參考實作 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- 本元件 source 與 Radix wrapper contract — production authority
 
 ## 被引用(auto-maintained,Dim 3 reciprocal audit)