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

package/src/components/Carousel/carousel.principles.stories.tsx

@@ -0,0 +1,334 @@
+// @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.
+// @principles-rationale: UsageGuidance merges WhenToUse + WhenNotToUse + Vs*Rule into single 使用指引 story per refactor task (2026-04-26)
+import { ChevronLeft, ChevronRight } from 'lucide-react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import {
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  CarouselPrevious,
+  CarouselNext,
+  CarouselDots,
+} from './carousel'
+import { Button } from '@/design-system/components/Button/button'
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/design-system/components/Tabs/tabs'
+
+const meta: Meta = {
+  title: 'Design System/Components/Carousel/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers(對齊 button.principles.stories.tsx)─────────────────────────────
+
+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>
+)
+
+const Gradient = ({ label, gradient, height = 160 }: { label: string; gradient: string; height?: number }) => (
+  <div
+    className="rounded-lg overflow-hidden flex items-end p-5 text-white"
+    style={{ background: gradient, height }}
+  >
+    <div className="text-body-lg font-bold">{label}</div>
+  </div>
+)
+
+const cityGradients = [
+  { label: '京都',       g: 'linear-gradient(135deg, #c4452a 0%, #f28b3a 60%, #ffd37a 100%)' },
+  { label: '雷克雅維克', g: 'linear-gradient(135deg, #1b3b6f 0%, #3d7ea6 60%, #a8e0ff 100%)' },
+  { label: '里斯本',     g: 'linear-gradient(135deg, #e87d5a 0%, #f4c27a 50%, #f7e2b0 100%)' },
+  { label: '峇里島',     g: 'linear-gradient(135deg, #1d6a5a 0%, #4db893 60%, #c7ebd9 100%)' },
+]
+
+// ── Stories ──────────────────────────────────────────────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <div className="prose prose-sm max-w-prose mb-8">
+          <p>適合 Carousel 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+          <ul className="space-y-1">
+            <li><LinkTo kind="Design System/Components/Carousel/展示" name="首頁主視覺橫幅"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">首頁 Hero Banner</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/Carousel/展示" name="商品圖片輪播"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">商品圖片輪播</span></LinkTo></li>
+          </ul>
+          <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方 vs 近親 段)。</p>
+        </div>
+      </Section>
+
+      <Section title="何時不用 + 替代方案">
+        <Rule
+          title="❌ 不用 Carousel 做命名視圖切換"
+          note="『訂單 / 顧客 / 產品』每塊結構完全不同,該用 Tabs——Carousel 把它們壓成順序性的同類視覺,使用者會困惑為什麼要按順序看。"
+        >
+          <Label warn>
+            電商後台「訂單 / 顧客 / 產品」→ 應使用 Tabs;carousel 的順序性暗示錯誤
+          </Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不用 Carousel 做資料表格"
+          note="表格需要 columns / sorting / filtering / row selection——這些全是 DataTable 的 affordance,carousel 提供不了。把 rows 包進 CarouselItem 是結構性誤用。"
+        >
+          <Label warn>
+            訂單列表應該用 DataTable,不能用 carousel 讓使用者「一次看一筆」
+          </Label>
+        </Rule>
+
+        <Rule
+          title="❌ 不預設啟用 auto-play"
+          note="違反 WCAG 2.2.2 Pause, Stop, Hide——超過 5 秒自動變動的內容必須可暫停。使用者常需要時間閱讀 testimonial 文字、看清產品細節,自動跳過打斷閱讀。Polaris / Material 皆建議不使用 auto-playing carousel。"
+        >
+          <Label warn>
+            若專案必須 auto-play,consumer 自行引入 embla-autoplay 並同時提供暫停按鈕,spec 不預設處理
+          </Label>
+        </Rule>
+
+        <Rule
+          title="❌ Active dot 不要只靠顏色區分"
+          note="色弱使用者無法靠色相辨識。本 DS 的 active dot 加寬至 24px(4 倍 inactive 寬度),是 Ant Design / Swiper 的世界級慣例——寬度變化更容易被感知。"
+        >
+          <div className="flex items-center gap-6">
+            <div className="flex items-center gap-2">
+              <span className="text-caption text-fg-muted">✅</span>
+              <div className="bg-foreground px-4 py-3 rounded-md flex items-center gap-1.5">
+                <span className="w-1.5 h-1.5 rounded-full bg-white/60" />
+                <span className="w-6 h-1.5 rounded-full bg-white" />
+                <span className="w-1.5 h-1.5 rounded-full bg-white/60" />
+              </div>
+              <span className="text-footnote text-fg-muted">寬度變化</span>
+            </div>
+            <div className="flex items-center gap-2">
+              <span className="text-caption text-error">❌</span>
+              <div className="bg-foreground px-4 py-3 rounded-md flex items-center gap-1.5">
+                <span className="w-1.5 h-1.5 rounded-full bg-white/60" />
+                <span className="w-1.5 h-1.5 rounded-full bg-info" />
+                <span className="w-1.5 h-1.5 rounded-full bg-white/60" />
+              </div>
+              <Label warn>只靠顏色</Label>
+            </div>
+          </div>
+        </Rule>
+      </Section>
+
+      <Section title="vs 近親元件">
+        <Rule
+          title="✅ Carousel — 同類視覺的多張輪播"
+          note="每張 slide 是同類內容(同為旅遊推薦目的地圖),無需命名。使用者按順序推進或點 dot 跳張,視覺階層是 content 不是 navigation。"
+        >
+          <div className="w-[480px]">
+            <Carousel opts={{ loop: true }}>
+              <CarouselContent>
+                {cityGradients.map((c) => (
+                  <CarouselItem key={c.label}>
+                    <Gradient label={c.label} gradient={c.g} />
+                  </CarouselItem>
+                ))}
+              </CarouselContent>
+              <CarouselPrevious />
+              <CarouselNext />
+              <CarouselDots />
+            </Carousel>
+            <Label>4 張同類大圖 · 無個別命名 · 底部 dots 指示進度</Label>
+          </div>
+        </Rule>
+
+        <Rule
+          title="✅ Tabs — 互斥切換命名視圖"
+          note="每個 tab 有獨立名稱(總覽 / 成員 / 設定),內容結構不同,使用者依名稱直接跳。Tabs 是 section header 等級的 navigation anchor。"
+        >
+          <div className="w-[480px]">
+            <Tabs defaultValue="overview">
+              <TabsList>
+                <TabsTrigger value="overview">總覽</TabsTrigger>
+                <TabsTrigger value="members">成員</TabsTrigger>
+                <TabsTrigger value="settings">設定</TabsTrigger>
+              </TabsList>
+              <TabsContent value="overview" className="">
+                <p className="text-body">專案狀態、最近活動、關鍵指標</p>
+              </TabsContent>
+              <TabsContent value="members" className="">
+                <p className="text-body">團隊成員列表、角色權限</p>
+              </TabsContent>
+              <TabsContent value="settings" className="">
+                <p className="text-body">通知、整合、危險區</p>
+              </TabsContent>
+            </Tabs>
+            <Label>3 個獨立命名視圖 · 每個 tab 結構與內容不同</Label>
+          </div>
+        </Rule>
+
+        <Rule
+          title="✅ ScrollArea / 列表捲動 — 自由瀏覽多項"
+          note="使用者想同時看到多個項目、在任意位置停下、掃視後挑選——那是列表的 affordance。用水平 ScrollArea / flex + overflow-x-auto 更符合使用者直覺。"
+        >
+          <div
+            tabIndex={0}
+            aria-label="常用食物標籤列表"
+            className="w-[480px] flex gap-3 overflow-x-auto pb-2"
+          >
+            {['🍜 拉麵', '🍕 披薩', '🍔 漢堡', '🥗 沙拉', '🌮 墨西哥捲', '🍣 壽司', '🍛 咖哩'].map((t) => (
+              <div key={t} className="shrink-0 w-28 h-20 rounded-lg border border-border bg-surface-raised flex items-center justify-center text-body">
+                {t}
+              </div>
+            ))}
+          </div>
+          <Label>聊天室的「常用食物標籤」應用自由捲動,不用 carousel 逼使用者一次看一張</Label>
+        </Rule>
+
+        <Rule
+          title="判斷法"
+          note="每個項目都有獨立標題且內容結構不同 → Tabs;每個項目是同類視覺的多張 → Carousel;一眼要看到所有項目 → 都不是,用 Grid。"
+        >
+          <Label>
+            商品 4 張角度照 = Carousel(同類視覺)· 電商後台「訂單 / 顧客 / 產品」= Tabs(命名視圖)· 20 張商品列表 = Grid(總覽)
+          </Label>
+        </Rule>
+      </Section>
+    </div>
+  ),
+}
+
+export const ArrowHoverOnly: Story = {
+  name: '箭頭僅滑鼠移過時顯示',
+  render: () => (
+    <div>
+      <Rule
+        title="✅ 預設 hover-only,不干擾主視覺"
+        note="Carousel 內容(大圖 / 產品照)是主視覺,常駐箭頭會搶走讀者的視線焦點。Airbnb / Instagram / Netflix 皆採 hover-only——讓圖片自己說話。"
+      >
+        <div className="w-[480px]">
+          <Carousel opts={{ loop: true }}>
+            <CarouselContent>
+              {cityGradients.map((c) => (
+                <CarouselItem key={c.label}>
+                  <Gradient label={c.label} gradient={c.g} />
+                </CarouselItem>
+              ))}
+            </CarouselContent>
+            <CarouselPrevious />
+            <CarouselNext />
+            <CarouselDots />
+          </Carousel>
+          <Label>hover 圖片區域才顯示箭頭 · 不 hover 時視覺乾淨</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="✅ 鍵盤 focus 時強制顯示(a11y 例外)"
+        note="鍵盤使用者不 hover。若 focus-visible 時仍 opacity-0,將無法得知元素位置——違反焦點可見原則。arrow wrapper 用 focus-within:opacity-100——後代 arrow 取得 focus 即強制顯示(機制掛在 wrapper,非 button 的 :focus-visible)。"
+      >
+        <div className="w-[480px]">
+          <Carousel>
+            <CarouselContent>
+              {cityGradients.slice(0, 3).map((c) => (
+                <CarouselItem key={c.label}>
+                  <Gradient label={c.label} gradient={c.g} height={140} />
+                </CarouselItem>
+              ))}
+            </CarouselContent>
+            <CarouselPrevious />
+            <CarouselNext />
+          </Carousel>
+          <Label>用 Tab 鍵 focus 到 arrow 時,即使未 hover 也會顯示(試試:按 Tab)</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ 不要讓 arrow 永遠可見"
+        note="常駐 arrow 會把讀者的視覺重量往兩側分流,main content(圖片本身)的衝擊力被削弱。除非 carousel 內容是輔助性的(e.g., carousel 內都是抽象縮圖需要箭頭引導),否則應保留 hover-only。"
+      >
+        <div className="w-[480px]">
+          <div className="relative h-[160px] rounded-lg overflow-hidden" style={{ background: cityGradients[0].g }}>
+            <div className="absolute inset-0 flex items-end p-5 text-white">
+              <div className="text-body-lg font-bold">京都</div>
+            </div>
+            {/* 示範「永遠可見」anti-pattern 時,仍使用 DS Button 維持視覺規格一致;
+                關鍵差異在 wrapper 沒有 opacity-0 + group-hover 的 fade 邏輯 */}
+            <div className="absolute left-3 top-1/2 -translate-y-1/2">
+              <Button variant="tertiary" size="md" iconOnly startIcon={ChevronLeft} aria-label="上一張(永遠可見的範例)" />
+            </div>
+            <div className="absolute right-3 top-1/2 -translate-y-1/2">
+              <Button variant="tertiary" size="md" iconOnly startIcon={ChevronRight} aria-label="下一張(永遠可見的範例)" />
+            </div>
+          </div>
+          <Label warn>↑ 箭頭永遠可見 · 分散主視覺焦點 · 違反 hover-only 慣例</Label>
+        </div>
+      </Rule>
+    </div>
+  ),
+}
+
+export const ItemCountLimit: Story = {
+  name: '項目數量上限 ~7',
+  render: () => (
+    <div>
+      <Rule
+        title="✅ 3–5 張是 carousel 的甜蜜點"
+        note="世界級 SaaS 的 hero carousel 幾乎都 ≤ 5 張(Airbnb 4–5 / Netflix 3 / Stripe 3)。使用者能記住位置,能快速推進,dots 仍能清楚辨識。"
+      >
+        <div className="w-[480px]">
+          <Carousel opts={{ loop: true }}>
+            <CarouselContent>
+              {cityGradients.map((c) => (
+                <CarouselItem key={c.label}>
+                  <Gradient label={c.label} gradient={c.g} />
+                </CarouselItem>
+              ))}
+            </CarouselContent>
+            <CarouselPrevious />
+            <CarouselNext />
+            <CarouselDots />
+          </Carousel>
+          <Label>4 張推薦目的地 · 使用者記得住 · dots 清晰</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ 不要把 carousel 當 gallery 用"
+        note="超過 7 張,使用者『找不到特定項』——不記得想看的那張在第幾張,要按多次才到。dots 也變得過密難以點擊。應改用 Grid(一眼看全)或 thumbnail + preview pattern。"
+      >
+        <div className="w-[600px]">
+          <div className="grid grid-cols-4 gap-2">
+            {[
+              'linear-gradient(135deg,#c4452a,#f28b3a)',
+              'linear-gradient(135deg,#1b3b6f,#3d7ea6)',
+              'linear-gradient(135deg,#e87d5a,#f4c27a)',
+              'linear-gradient(135deg,#1d6a5a,#4db893)',
+              'linear-gradient(135deg,#a8367a,#e45b9a)',
+              'linear-gradient(135deg,#5a3e8f,#8a6cc2)',
+              'linear-gradient(135deg,#2a7a5a,#5ab892)',
+              'linear-gradient(135deg,#c27a1a,#e5b35a)',
+            ].map((g, i) => (
+              <div key={i} className="aspect-square rounded-md" style={{ background: g }} />
+            ))}
+          </div>
+          <Label>8 張商品總覽用 Grid · 一眼看全 · 可直接點任一項</Label>
+        </div>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/Carousel/carousel.spec.md

@@ -11,7 +11,6 @@ benchmark:
   - Ant Design Carousel: github.com/ant-design/ant-design/tree/master/components/carousel
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
 
 # Carousel 設計原則
 
@@ -27,7 +26,7 @@ Carousel 用於在**有限空間內輪播同類視覺內容**——單次只顯
 
 ## 世界級對照
 
-- **shadcn Carousel**(主要參考):API 結構與 Embla engine 選擇對齊 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- **Embla engine**:本元件只包裝已採用的 carousel engine，DS API 擁有結構、按鈕與內容規範
 - **Ant Design Carousel**:dots indicator 在底部中央的慣例來源
 - **Material / Polaris**:無獨立 Carousel 元件——Material 建議用 image list / hero module;Polaris 明確不支援 auto-playing carousel(a11y 疑慮)
 - **Swiper**:獨立 library,功能遠超 DS 需求(3D effects / virtualization / zoom 等);本 DS 刻意**不選 Swiper**,因為 Embla 更輕量、tree-shakable,且本 DS 的 carousel 用途單純(hero banner / product image / testimonial),Swiper 的 feature 90% 不會用到,屬過度工程
@@ -98,7 +97,7 @@ Tabs 和 Carousel 都能「按順序切換下方內容」,但**語意與視覺
     <CarouselItem />
     ...
   </CarouselContent>
-  <CarouselPrevious />           ← 左箭頭(hover-only, focus-visible 時強制顯示)
+  <CarouselPrevious />           ← 左箭頭(hover-only, focus-within 時強制顯示)
   <CarouselNext />               ← 右箭頭
   <CarouselDots />               ← 底部中央 dots(scrollSnaps > 1 才渲染)
 </Carousel>
@@ -113,29 +112,45 @@ Tabs 和 Carousel 都能「按順序切換下方內容」,但**語意與視覺
 預設 arrow **opacity-0**,父容器 `group-hover/carousel:opacity-100` 才浮現。
 
 - **為什麼不永遠可見**:carousel 內容(大圖 / 產品照)是主視覺,常駐箭頭會干擾閱讀;Airbnb / Instagram / Netflix hero 皆採 hover-only
-- **a11y 例外**:`focus-visible:opacity-100`——鍵盤 focus 時強制顯示,滿足**焦點可見原則**。鍵盤使用者不 hover,若仍 opacity-0 將無法得知元素位置
+- **a11y 例外**:wrapper `focus-within:opacity-100`——後代 arrow 取得 focus 時強制顯示,滿足**焦點可見原則**。鍵盤使用者不 hover,若仍 opacity-0 將無法得知元素位置
 - **邊界**:`canScrollPrev/Next === false` 時 `disabled + opacity-0 + pointer-events-none`——到邊界直接消失,不顯示 disabled 狀態,避免視覺噪音
 
 ### 箭頭覆蓋範圍(canonical)
 
-箭頭屬 **hover-only overlay**,可以**蓋在圖片 / media / 深色背景 canvas** 上(對齊 Airbnb / Instagram / Netflix hero carousel 的做法)。但**不得壓在文字資訊上面**—— title / description / testimonial / caption 等**文字內容** 是主訊息,被 overlay 遮蓋會破壞閱讀。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+箭頭屬 **hover-only overlay**,可以**蓋在圖片 / media / 深色背景 canvas** 上。但**不得壓在文字資訊上面**—— title / description / testimonial / caption 等**文字內容** 是主訊息,被 overlay 遮蓋會破壞閱讀。
 
 **判斷法**:
 - ✅ 箭頭疊在 image / video / gradient background / solid card bg —— OK(背景可辨識箭頭無資訊損失)
 - ❌ 箭頭疊在 title text / body paragraph / testimonial quote / product description —— 違反(user 看不完文字 + 被遮)
 
-**修法(若發生)**:(a) 把文字區域避開箭頭位置(左右內縮 `px-12` 以上);或 (b) 改把箭頭移到 carousel **外側**(stacked controls,對齊 Ant Carousel dotPosition=outside 思路)。world-class 對照:Notion Slider / Stripe testimonial section 皆用「箭頭外移 + 內容 center」當文字較長時。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**修法(若發生)**:(a) 把文字區域左右內縮、避開箭頭覆蓋區(具體內縮值屬 story / code 層決策);或 (b) 改把箭頭移到 carousel **外側**。選擇由內容是否仍有完整、不被 controls 覆蓋的閱讀區決定。
 
 ### 視覺規格
 
-- **基於 DS Button**:`<Button variant="tertiary" size="md" iconOnly />`——完全對齊 DS 規則,不自訂視覺
-- **形狀 documented 例外**:override `rounded-md` → **`rounded-full`**(圓形)。理由:media carousel 視覺取向,圓形箭頭減少方塊感、不壓迫媒體內容(對齊 **Instagram / Airbnb / Notion Gallery / Apple Photos / Google Photos lightbox 世界級慣例** — 媒體 overlay 控制器圓形)。本 DS 內 Button default 是 `rounded-md`,這裡是唯一文明 override,需維護記錄在 `.claude/references/cva-patterns.md` documented 例外清單。**不傳染**:其他元件的 Button 仍走 rounded-md <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-- 尺寸:`size="md"` 對應 `--field-height-md`(default 32px / loose 36px),iconOnly 正方形;形狀 `rounded-md`(**不破例走 rounded-full**,DS 內沒有 rounded-full Button,Carousel 不例外)
+- **基於 DS Button**:`<Button variant="tertiary" size="md" iconOnly />`(variant/size 為 **default,可覆寫**——見「Arrow Props」)——對齊 DS 規則,唯 shape 覆寫 `rounded-full`(media carousel documented 例外,見下一條「形狀 documented 例外」);其餘視覺全繼承 Button tertiary,不另自訂
+- **形狀 documented 例外**:override `rounded-md` → **`rounded-full`**(圓形)。理由:media carousel 的 overlay control 需要與矩形媒體 frame 清楚分層，圓形也讓 icon 在各方向保持相同 inset。本 DS 內 Button default 是 `rounded-md`,這裡是唯一文明 override,documented 例外記錄即為本段(同步 `carousel.tsx` Button `className="rounded-full"` 旁 inline 註解)。**不傳染**:其他元件的 Button 仍走 rounded-md。
+- 尺寸:`size="md"` 對應 `--field-height-md`(default/md 32px / lg 36px),iconOnly 正方形;形狀 **`rounded-full`**(documented 例外,見上一條)
 - 為什麼 tertiary:`bg-surface` + `border-border`,hover 僅改 text/border 為 `primary-hover`——無 bg-hover tint,視覺最輕,不搶 media 權重;secondary 有 neutral 邊框+hover 較重,primary 有底色更搶焦點,均不合適
 - 背景 / 邊框 / hover / focus-visible:全部繼承 Button tertiary variant 的 token,不自訂
 - 圖標:`startIcon={ChevronLeft}` / `startIcon={ChevronRight}`,尺寸由 Button 內部程式化決定
 - **絕對定位 wrapper**:Button 外層 `<div>` 負責 `absolute` 定位 + hover-only opacity(`group-hover/carousel:opacity-100` / `focus-within:opacity-100`);Button 本身不做任何定位或可見性邏輯(職責分離)
 
+### Arrow Props(API 契約,2026-07-18 決策14)
+
+`CarouselPrevious` / `CarouselNext` 開放**完整 Button props**，因為兩者就是帶方向與定位預設的 DS Button wrapper。consumer 可換 `variant` / `size`、綁 analytics `onClick`、傳 `data-*` / `id`:
+
+| Prop | 指向 | 說明 |
+|------|------|------|
+| `className` | **箭頭按鈕本身** | 疊在 DS default(`rounded-full` 等)之後,可覆寫按鈕樣式(className 指按鈕,非 wrapper) |
+| `wrapperClassName` | **定位層 wrapper** | 絕對定位 + hover-only 顯示層的 className(換位置 / 顯示邏輯用) |
+| `variant` / `size` | 箭頭按鈕 | default `tertiary` / `md`,可覆寫 |
+| `startIcon` | 箭頭按鈕 | default `ChevronLeft` / `ChevronRight`,可覆寫圖標 |
+| `onClick` | 箭頭按鈕 | 與內部 `scrollPrev/Next` **compose**(先導覽再呼叫 consumer handler;analytics 用) |
+| `disabled` | 箭頭按鈕 | 與邊界態 **compose**(`!canScroll* \|\| disabled`;consumer 可強制 disable,不可強制在邊界 enable) |
+| `iconOnly` | — | 固定 `true`(箭頭恆 icon-only),不可覆寫 |
+
+**⚠️ BREAKING(決策14 遷移)**:`className` 語義由「定位 wrapper」改為「箭頭按鈕」。**原本用 `className` 做定位覆寫的 consumer → 改傳 `wrapperClassName`**。DS 內既有 consumer 全數 bare `<CarouselPrevious />`(無 className 傳入)= 0 遷移成本;fork consumer 若有覆寫定位,依本條遷移。
+
 ---
 
 ## Dots indicator
@@ -146,7 +161,7 @@ Tabs 和 Carousel 都能「按順序切換下方內容」,但**語意與視覺
 
 ### 位置與互動
 
-- 底部中央:`absolute bottom-3 left-1/2 -translate-x-1/2`
+- 底部中央:水平置中、貼齊媒體底緣疊於其上(定位 class 見 `.tsx`)
 - 間距:`gap-1.5`(6px)
 - 點擊:`scrollTo(i)` 直接跳該張
 - 鍵盤:每個 dot 是 `<button>`,`Tab` 可進入
@@ -182,7 +197,9 @@ Carousel 常疊在圖片上,沿用 Instagram / Airbnb / Ant Carousel 的「白
 - dots 排列過密、點擊區過小、失去 indicator 功能
 - **改用 Grid**(一眼看全)或 **Gallery with thumbnails**(縮圖列表 + 大圖預覽)
 
-世界級 SaaS 的 hero carousel 幾乎都 ≤ 5 張(Airbnb 4–5 / Netflix 3 / Stripe 3)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+Hero carousel 建議 ≤ 5 張；超過此數量時，使用者難以預期循環範圍，也不應以 carousel 隱藏大量可瀏覽內容。
+
+**8+ 項時元件行為**:dots 仍按標準尺寸全數渲染(無自動縮小 / 省略 / 停止渲染)——「≤ 7」是 UX 建議非元件強制,排列過密時應改 Grid,非期待 dots 自動降級。
 
 ---
 
@@ -191,8 +208,20 @@ Carousel 常疊在圖片上,沿用 Instagram / Airbnb / Ant Carousel 的「白
 - 根容器 `role="region" aria-roledescription="carousel"`
 - 每個 `CarouselItem` `role="group" aria-roledescription="slide"`
 - Arrow `aria-label="上一張"` / `"下一張"`
-- Dots 容器 `role="tablist"`,每個 dot `role="tab" aria-selected={...} aria-label="跳至第 N 張"`
-- 鍵盤:`ArrowLeft` / `ArrowRight` 切換(`onKeyDownCapture`);dots 可 `Tab` focus
+- Dots 容器 `role="group"` + `aria-label="輪播指示器"`;每個 dot 為原生 `<button>`,`aria-label="跳至第 N 張"`,**目前這張的 dot `aria-current="true"`**(向 SR 告知「你在這張」)— 對齊 DS FileViewer filmstrip canonical(`file-viewer.spec.md`「Filmstrip 規則」)+ Bootstrap 5 carousel indicators idiom
+- 鍵盤:按方向對應 orientation(`horizontal` 用 `ArrowLeft` / `ArrowRight`;`vertical` 用 `ArrowUp` / `ArrowDown`)切換(根容器 `onKeyDownCapture`);dots 可 `Tab` focus
+
+### 為何 dots 不用 tabs 模型(canonical,2026-06-12)
+
+W3C APG carousel pattern 有兩條合法路:**tabbed**(dot `role="tab"` + slide `role="tabpanel"` + 完整 tabs 鍵盤契約)或 **grouped**(slide `role="group" aria-roledescription="slide"` + dots 為 group 內原生 button、現張標記)。本 DS 採 **grouped**(<https://www.w3.org/WAI/ARIA/apg/patterns/carousel/>),對齊 Embla 官方 Accessibility plugin(plain button + label,無 tab roles,<https://www.embla-carousel.com/docs/plugins/accessibility>)與 bluecadet embla-carousel-a11y(follows APG)。理由:
+
+1. **Embla snap ≠ slide**:`basis-1/3` 多張並排時 1 dot 對應 1 個 snap(多張 slide),tab↔tabpanel 1:1 對應不成立
+2. **鍵盤契約衝突**:tabs pattern 要求方向鍵在 tablist 內移 focus(roving tabindex);本元件方向鍵 = 切張(根容器),兩者互斥
+3. **compound API**:`CarouselItem` 不知自己 index,`aria-controls` 接線需額外 registration 機制,複雜度不對價
+
+現張標記採 `aria-current="true"`(非 APG 原文的 `aria-disabled`)— M23 DS 既有 canonical 優先:FileViewer filmstrip(`file-viewer.spec.md`「Filmstrip 規則」,2026-06-01 source-verified)同類控件已 codify `group` + `<button>` + `aria-current`;Bootstrap 5 carousel indicators 同 idiom。兩者皆 APG 合法變體,DS 內一致性勝
+
+❌ **禁半套 tabs**(dot `role="tab"` + `aria-selected` 但無 `aria-controls`、slide 非 `tabpanel`)— 對 SR 宣告了不存在的 tabs 結構
 
 ### 不加 auto-play(重要)
 
@@ -208,7 +237,7 @@ Carousel 常疊在圖片上,沿用 Instagram / Airbnb / Ant Carousel 的「白
 
 ## 視覺規則
 
-- **Arrow**:浮層卡片視覺(surface-raised bg + border + elevation-200 shadow),hover-only 顯示,疊於照片 / media 上仍清晰可見——與 Popover / DropdownMenu trigger 慣例一致
+- **Arrow**:`<Button variant="tertiary">` 視覺(`bg-surface` + `border-border`,無 elevation shadow),`rounded-full` 圓形(documented 例外),hover-only 顯示,疊於照片 / media 上仍清晰可見
 - **Dots**:photo overlay convention(白點於照片上),active 加寬不變色(對色弱友善)
 - **Focus ring**:鍵盤 focus 走 ring token,滿足 a11y 焦點可見原則
 
@@ -216,6 +245,12 @@ Carousel 常疊在圖片上,沿用 Instagram / Airbnb / Ant Carousel 的「白
 
 ---
 
+## 常見誤解
+
+- 「Carousel 適合導覽 / 視圖切換」——錯。Carousel 適合**同類視覺的多張輪播**(圖片、產品照、評語卡);命名視圖切換用 Tabs(分界 SSOT 見上方「與 Tabs 的分界」)
+
+---
+
 ## 禁止事項
 
 - ❌ **不用於互斥切換命名視圖**(「總覽 / 成員 / 設定」)——改用 Tabs
@@ -233,8 +268,9 @@ Carousel 常疊在圖片上,沿用 Instagram / Airbnb / Ant Carousel 的「白
 
 - **單一 item**:dots 自動不渲染(`scrollSnaps.length > 1` gate)+ 箭頭因 `canScrollPrev/Next === false` 自動隱藏 → 純顯示單一 slide,consumer 不必手動判斷
 - **零 items**:consumer 應在 items 為空時不 render Carousel(改用 `<Empty>`),本元件不自帶 empty state UI
+- **Loading**:Carousel API 無 loading prop；slide 內容與其遠端資料生命週期由 consumer own。
 - **Autoplay 單 item**:autoplay 在 single item 時無作用(`canScrollNext=false`)— embla-carousel 自動處理,consumer 不用加特判
-- **Dark mode**:由 semantic token(arrow bg `--surface-raised` / border `--border`)自動切換,詳見 `../../tokens/color/color.spec.md`
+- **Dark mode**:由 semantic token(arrow bg `--surface` / border `--border`,繼承 Button tertiary)自動切換,詳見 `../../tokens/color/color.spec.md`
 
 ---
 

package/src/components/Carousel/carousel.stories.tsx

@@ -0,0 +1,125 @@
+// @story-history: Carousel 是 composite UX showcase(Hero banner + Product gallery 兩個 hero scenario)
+// 而非 prop-variant control;互動 state 由 embla 內建處理(arrow visibility hover-revealed / dots active state)
+// 在 hero story 內已 demonstrate。Trait gap pre-existing(非本 audit fix scope),allowlist for image-content fix。
+import type { Meta } from '@storybook/react'
+import {
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  CarouselPrevious,
+  CarouselNext,
+  CarouselDots,
+} from './carousel'
+import { Button } from '@/design-system/components/Button/button'
+import { AspectRatio } from '@/design-system/components/AspectRatio/aspect-ratio'
+
+const meta: Meta = {
+  title: 'Design System/Components/Carousel/展示',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { description: { component: '讓一組同類內容在有限區域中水平逐頁瀏覽，提供箭頭與頁面指示。適合圖片集、產品卡或宣傳內容；必須同時比較的資訊不可藏進 Carousel。' } },
+  },
+}
+export default meta
+
+// ── Real-content data ────────────────────────────────────────────────────────
+
+// 2026-05-16 audit codex Round 6:用真實 photo URL 取代 gradient color block — story 要教 carousel
+// 真實裁切 / 內容裁切 / 視覺層次,gradient 抽象 block 教不到(對齊 Polaris / Carbon stories 用 stock photo)。
+// Picsum.photos 提供 stable seeded photos(免登入 / 免 API key / 跨環境一致)。
+const heroBanners = [
+  { city: '京都', tagline: '秋日楓紅限定行程', image: 'https://picsum.photos/seed/kyoto/960/360' },
+  { city: '雷克雅維克', tagline: '極光季早鳥 8 折', image: 'https://picsum.photos/seed/reykjavik/960/360' },
+  { city: '里斯本', tagline: '歐洲西岸 7 日自由行', image: 'https://picsum.photos/seed/lisbon/960/360' },
+  { city: '峇里島', tagline: '熱帶度假村 · 含機加酒', image: 'https://picsum.photos/seed/bali/960/360' },
+]
+
+const productImages = [
+  { label: '正面', image: 'https://picsum.photos/seed/headphones-front/480/480' },
+  { label: '側面', image: 'https://picsum.photos/seed/headphones-side/480/480' },
+  { label: '背面', image: 'https://picsum.photos/seed/headphones-back/480/480' },
+  { label: '情境', image: 'https://picsum.photos/seed/headphones-lifestyle/480/480' },
+]
+
+
+// ── Stories ─────────────────────────────────────────────────────────────────
+
+export const HomepageHeroBanner = {
+  name: '首頁主視覺橫幅',
+  render: () => (
+    <div className="max-w-[960px]">
+      <p className="text-caption text-fg-muted mb-3">
+        Airbnb / Booking 首頁風格 · 4 張城市主題大圖 · hover 顯示箭頭 · 底部白點指示
+      </p>
+      <Carousel opts={{ loop: true }}>
+        <CarouselContent>
+          {heroBanners.map((b) => (
+            <CarouselItem key={b.city}>
+              <div
+                className="relative h-[360px] rounded-lg overflow-hidden flex items-end p-8 bg-cover bg-center"
+                style={{ backgroundImage: `linear-gradient(180deg, rgba(0,0,0,0.05) 50%, rgba(0,0,0,0.6) 100%), url(${b.image})` }}
+              >
+                <div className="text-white relative z-10">
+                  <div className="text-caption font-medium opacity-90 mb-1">推薦目的地</div>
+                  <div className="text-h2 font-bold mb-1">{b.city}</div>
+                  <div className="text-body-lg opacity-95">{b.tagline}</div>
+                </div>
+              </div>
+            </CarouselItem>
+          ))}
+        </CarouselContent>
+        <CarouselPrevious />
+        <CarouselNext />
+        <CarouselDots />
+      </Carousel>
+    </div>
+  ),
+}
+
+export const ProductImageGallery = {
+  name: '商品圖片輪播',
+  render: () => (
+    <div className="max-w-[480px]">
+      <p className="text-caption text-fg-muted mb-3">
+        單一商品 4 張角度照 · dots 顯示共有幾張 · 適合電商 / B2B SaaS marketing site
+      </p>
+      <Carousel>
+        <CarouselContent>
+          {productImages.map((img) => (
+            <CarouselItem key={img.label}>
+              <AspectRatio
+                ratio={1}
+                className="relative rounded-lg overflow-hidden bg-cover bg-center"
+                style={{ backgroundImage: `url(${img.image})` }}
+              >
+                <div className="absolute bottom-2 right-2 text-caption text-white px-2 py-0.5 rounded bg-black/40">{img.label}</div>
+              </AspectRatio>
+            </CarouselItem>
+          ))}
+        </CarouselContent>
+        <CarouselPrevious />
+        <CarouselNext />
+        <CarouselDots />
+      </Carousel>
+      <div className="mt-4 flex items-baseline justify-between">
+        <div>
+          <div className="text-body font-medium">無線降噪耳機 Pro</div>
+          <div className="text-caption text-fg-muted">NT$ 8,990</div>
+        </div>
+        <Button variant="primary" size="sm">加入購物車</Button>
+      </div>
+    </div>
+  ),
+}
+
+// TestimonialCarousel / VerticalOrientation 範例於 2026-04-20 移除:
+//   - TestimonialCarousel:箭頭直接覆蓋文字 card(text 佔滿卡片高度),
+//     違反「箭頭 overlay 只覆蓋圖 / 背景,不壓文字」原則(見 principles story)。
+//     純文字 carousel 若真要保留,應改為 arrows OUTSIDE the card(旁邊,非 overlay)
+//     — 但該 layout 較少見,DS 不主動 demo
+//   - VerticalOrientation:垂直輪播使用情境少見(story feed / 影片 feed 外難找),
+//     且 embla 垂直模式在 a11y / touch gesture 上都次等,不值得做為 DS canonical
+//     範例示範
+//
+// 如果 consumer 有這兩類需求,自己評估合適性 — DS 不 demo 等於不背書