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

package/src/components/Accordion/accordion.principles.stories.tsx

@@ -0,0 +1,365 @@
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from './accordion'
+import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/design-system/components/Tabs/tabs'
+import { Button } from '@/design-system/components/Button/button'
+import { Field, FieldLabel, FieldGroup } from '@/design-system/components/Field/field'
+import { Input } from '@/design-system/components/Input/input'
+
+const meta: Meta = {
+  title: 'Design System/Components/Accordion/設計原則',
+  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-col gap-3 max-w-[640px]">{children}</div>
+  </div>
+)
+
+const Label = ({
+  children,
+  warn,
+}: {
+  children: React.ReactNode
+  warn?: boolean
+}) => (
+  <p
+    className={`text-footnote leading-normal ${
+      warn ? 'text-error font-medium' : 'text-fg-muted'
+    }`}
+  >
+    {children}
+  </p>
+)
+
+// ── Stories ──────────────────────────────────────────────────────
+
+// ── UsageGuidance — 何時用 / 何時不用 / vs 近親元件(合併 WhenToUse + AccordionVsTabsRule) ──
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Rule
+        title="何時用 — 真實業務場景"
+        note="Accordion 適合「多個獨立主題、使用者依興趣或當下需要展開單一段」的內容(非互斥可同時展開,Radix Accordion type='multiple');每段內容 self-contained,不展開不影響上下脈絡。對齊 Material 3 Expansion panel / Polaris Disclosure 共識。"
+      >
+        <ul className="space-y-1">
+          <li>
+            <LinkTo kind="Design System/Components/Accordion/展示" name="FAQ 常見問題"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">FAQ 常見問題</span></LinkTo>
+          </li>
+          <li>
+            <LinkTo kind="Design System/Components/Accordion/展示" name="設定分組"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">設定分組</span></LinkTo>
+          </li>
+          <li>
+            <LinkTo kind="Design System/Components/Accordion/展示" name="進階選項可隱藏"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">進階選項可隱藏</span></LinkTo>
+          </li>
+        </ul>
+      </Rule>
+
+      <Rule
+        title="vs Tabs — Tabs 是互斥平行視圖(看 A 就不看 B)"
+        note='三個 tab 是「同一層級的平行視角」,使用者每次只需一個。切換等於「換視角」,兩個視角不會同時需要。'
+      >
+        <div className='border border-border rounded-lg p-4'>
+          <Tabs defaultValue='overview'>
+            <TabsList>
+              <TabsTrigger value='overview'>總覽</TabsTrigger>
+              <TabsTrigger value='members'>成員</TabsTrigger>
+              <TabsTrigger value='settings'>設定</TabsTrigger>
+            </TabsList>
+            <TabsContent value='overview'>
+              <p className='text-body text-fg-secondary'>專案總覽資訊</p>
+            </TabsContent>
+            <TabsContent value='members'>
+              <p className='text-body text-fg-secondary'>成員列表</p>
+            </TabsContent>
+            <TabsContent value='settings'>
+              <p className='text-body text-fg-secondary'>專案設定</p>
+            </TabsContent>
+          </Tabs>
+        </div>
+        <Label>✅ Tabs:視角切換,使用者「不會想同時看總覽和成員」</Label>
+      </Rule>
+
+      <Rule
+        title='Accordion — 獨立收合多段(每段各自是否展開)'
+        note='每個 item 是獨立主題,使用者依興趣選擇展開。不是互斥,而是「多段內容,多數時間只想看其中一段」。'
+      >
+        <Accordion type='multiple'>
+          <AccordionItem value='pricing'>
+            <AccordionTrigger>付款週期與折扣</AccordionTrigger>
+            <AccordionContent>年付享 20% 折扣。</AccordionContent>
+          </AccordionItem>
+          <AccordionItem value='refund'>
+            <AccordionTrigger>退款政策</AccordionTrigger>
+            <AccordionContent>14 天內可全額退款。</AccordionContent>
+          </AccordionItem>
+          <AccordionItem value='support'>
+            <AccordionTrigger>技術支援範圍</AccordionTrigger>
+            <AccordionContent>企業方案提供 24/7 專屬窗口。</AccordionContent>
+          </AccordionItem>
+        </Accordion>
+        <Label>✅ Accordion:各段主題獨立,使用者只想看其中 1-2 段</Label>
+      </Rule>
+
+      <Rule
+        title='❌ 錯誤 — 用 Accordion 做平行視圖切換'
+        note='三段內容結構相似、使用者只需其一——這是 Tabs 的情境。用 Accordion 會讓使用者困惑「為什麼要收合?」。'
+      >
+        <Accordion type='single' collapsible defaultValue='overview'>
+          <AccordionItem value='overview'>
+            <AccordionTrigger>總覽</AccordionTrigger>
+            <AccordionContent>專案總覽資訊</AccordionContent>
+          </AccordionItem>
+          <AccordionItem value='members'>
+            <AccordionTrigger>成員</AccordionTrigger>
+            <AccordionContent>成員列表</AccordionContent>
+          </AccordionItem>
+        </Accordion>
+        <Label warn>
+          ⚠️ 平行視圖應該用 Tabs——Accordion 是「多段獨立內容」,不是「多個視角」
+        </Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const TypeRule: Story = {
+  name: '單一展開 vs 多重展開',
+  render: () => (
+    <div>
+      <Rule
+        title='single + collapsible — FAQ / 使用教學'
+        note='讀者一段一段看,同時看多段反而混亂。collapsible 讓使用者可把展開的再收起,回到乾淨的「全部收合」狀態。'
+      >
+        <Accordion type='single' collapsible>
+          <AccordionItem value='q1'>
+            <AccordionTrigger>如何取消訂閱?</AccordionTrigger>
+            <AccordionContent>
+              於「設定 → 帳單」點選取消。取消後資料保留 90 天供復用。
+            </AccordionContent>
+          </AccordionItem>
+          <AccordionItem value='q2'>
+            <AccordionTrigger>資料可以匯出嗎?</AccordionTrigger>
+            <AccordionContent>
+              所有方案支援 CSV / JSON 匯出;企業方案另支援 API 批次匯出。
+            </AccordionContent>
+          </AccordionItem>
+        </Accordion>
+        <Label>參考:Stripe Pricing FAQ、Notion Help Center</Label>
+      </Rule>
+
+      <Rule
+        title='multiple — 設定頁 / 工作 context(需同時比對)'
+        note='使用者會同時打開「通知偏好」與「安全設定」對照;強制收合前一個反而阻礙工作。'
+      >
+        <Accordion type='multiple' defaultValue={['notifications']}>
+          <AccordionItem value='notifications'>
+            <AccordionTrigger>通知偏好</AccordionTrigger>
+            <AccordionContent>Email 每日摘要、@提及立即通知。</AccordionContent>
+          </AccordionItem>
+          <AccordionItem value='security'>
+            <AccordionTrigger>安全與登入</AccordionTrigger>
+            <AccordionContent>兩步驟驗證:已啟用。</AccordionContent>
+          </AccordionItem>
+        </Accordion>
+        <Label>參考:Jira Project Settings、Linear Workspace Settings</Label>
+      </Rule>
+
+      <Rule
+        title='判斷法 — 「使用者會不會想同時看兩段?」'
+        note='會 → multiple;不會 / 同時看反而混亂 → single。不確定時預設 single + collapsible(較保守,視覺負擔小)。'
+      >
+        <Label>single(推薦預設):FAQ、教學、說明文件</Label>
+        <Label>multiple:Settings、多段 form、工作 context panel</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const NoNestingRule: Story = {
+  name: '不可巢狀',
+  render: () => (
+    <div>
+      <Rule
+        title='❌ 不在 Accordion 內放另一個 Accordion'
+        note='巢狀收合會讓使用者迷失方向——「我剛才收起的是哪一層?」。多層結構應該改用 TreeView(明確的層級視覺)或拆成獨立頁面。'
+      >
+        <Accordion type='single' collapsible>
+          <AccordionItem value='outer'>
+            <AccordionTrigger>外層:一般設定</AccordionTrigger>
+            <AccordionContent>
+              <Accordion type='single' collapsible>
+                <AccordionItem value='inner-1'>
+                  <AccordionTrigger>內層:顯示偏好</AccordionTrigger>
+                  <AccordionContent>字級、主題⋯</AccordionContent>
+                </AccordionItem>
+                <AccordionItem value='inner-2'>
+                  <AccordionTrigger>內層:鍵盤快捷鍵</AccordionTrigger>
+                  <AccordionContent>快捷鍵列表⋯</AccordionContent>
+                </AccordionItem>
+              </Accordion>
+            </AccordionContent>
+          </AccordionItem>
+        </Accordion>
+        <Label warn>
+          ⚠️ 使用者收起「顯示偏好」後,外層仍在展開狀態——容易讓人失去位置感
+        </Label>
+      </Rule>
+
+      <Rule
+        title='✅ 改用扁平結構 — 多段平行 Accordion'
+        note='把所有分組拉到同一層。使用者看得到全部主題,依興趣展開,不會在層級中迷路。'
+      >
+        <Accordion type='multiple'>
+          <AccordionItem value='display'>
+            <AccordionTrigger>顯示偏好</AccordionTrigger>
+            <AccordionContent>字級、主題、密度⋯</AccordionContent>
+          </AccordionItem>
+          <AccordionItem value='keyboard'>
+            <AccordionTrigger>鍵盤快捷鍵</AccordionTrigger>
+            <AccordionContent>自訂快捷鍵列表⋯</AccordionContent>
+          </AccordionItem>
+          <AccordionItem value='accessibility'>
+            <AccordionTrigger>無障礙</AccordionTrigger>
+            <AccordionContent>螢幕閱讀器、動畫減少⋯</AccordionContent>
+          </AccordionItem>
+        </Accordion>
+      </Rule>
+
+      <Rule
+        title='✅ 真的有層級需求 — 改用 TreeView'
+        note='TreeView 提供明確的縮排與展開 icon,使用者從視覺就能判斷自己在第幾層。'
+      >
+        <Label>
+          檔案樹、Notion-style 工作區 sidebar、深度分類頁面 → `../TreeView`
+        </Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const ContentRule: Story = {
+  name: '內容限制',
+  render: () => (
+    <div>
+      <Rule
+        title='✅ 可放 — 文字說明、簡單表單欄位'
+        note='Accordion 適合承載閱讀性內容或輕量輸入(e.g. 進階選項的文字欄位)。多段獨立設定各自收合(type="multiple"),不是單一 item——單一區塊該用 details(見「單一項目不用 Accordion」)。'
+      >
+        <Accordion type='multiple'>
+          <AccordionItem value='deploy'>
+            <AccordionTrigger>進階部署設定</AccordionTrigger>
+            <AccordionContent>
+              <FieldGroup gap='compact'>
+                <Field>
+                  <FieldLabel>專案識別碼</FieldLabel>
+                  <Input placeholder='例:Q2-RELEASE' />
+                </Field>
+                <Field>
+                  <FieldLabel>自訂網域</FieldLabel>
+                  <Input placeholder='your-team.example.com' />
+                </Field>
+              </FieldGroup>
+            </AccordionContent>
+          </AccordionItem>
+          <AccordionItem value='seo'>
+            <AccordionTrigger>SEO 與中繼資料</AccordionTrigger>
+            <AccordionContent>
+              <Field>
+                <FieldLabel>頁面標題</FieldLabel>
+                <Input placeholder='顯示於瀏覽器分頁與搜尋結果' />
+              </Field>
+            </AccordionContent>
+          </AccordionItem>
+        </Accordion>
+      </Rule>
+
+      <Rule
+        title='❌ 不放 — 會開啟浮層的焦點重互動'
+        note='收合 Accordion 後,焦點會離開 content 內的元素——如果當下正在操作 Dialog / Popover / 複雜 form,使用者的操作流會斷。這類元素應該放在主頁面或獨立 section。'
+      >
+        <Accordion type='single' collapsible defaultValue='danger'>
+          <AccordionItem value='danger'>
+            <AccordionTrigger>危險操作區</AccordionTrigger>
+            <AccordionContent>
+              <Button variant='primary' danger>
+                永久刪除工作區
+              </Button>
+            </AccordionContent>
+          </AccordionItem>
+        </Accordion>
+        <Label warn>
+          ⚠️ 刪除確認這種不可逆操作應該有獨立區塊 + Dialog 確認,不該藏在可收合 Accordion 裡
+        </Label>
+      </Rule>
+
+      <Rule
+        title='判斷法 — 「收合時使用者會不會正在操作 content 內的元素?」'
+        note='會 → 不適合放 Accordion;不會(純閱讀 / 輕量輸入) → OK。'
+      >
+        <Label>✅ OK:FAQ 說明、設定欄位、進階選項 text input</Label>
+        <Label>❌ 不行:Dialog trigger、複雜多步驟 form、需要焦點持續的互動</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const SingleItemRule: Story = {
+  name: '單一 項目 不用 Accordion',
+  render: () => (
+    <div>
+      <Rule
+        title='❌ 只有一個區塊要收合 — 不該用 Accordion'
+        note='Accordion 是「多個 item 可獨立收合」的 pattern,單 item 變成「為什麼要包一層?」。視覺上也過重(多出整條 border-b 分隔線)。'
+      >
+        <Accordion type='single' collapsible>
+          <AccordionItem value='only'>
+            <AccordionTrigger>顯示更多資訊</AccordionTrigger>
+            <AccordionContent>單一可收合內容。</AccordionContent>
+          </AccordionItem>
+        </Accordion>
+        <Label warn>⚠️ 單 item Accordion = 過度使用元件</Label>
+      </Rule>
+
+      <Rule
+        title='✅ 改用 `<details>` 或自組 toggle 按鈕'
+        note='原生 `<details>` 是單區塊展開的 HTML 原語;若需要自訂視覺可做一個「顯示更多 ↓」按鈕。'
+      >
+        <details className='border-b border-divider pb-4'>
+          <summary className='py-4 text-body font-medium text-foreground cursor-pointer'>
+            顯示更多資訊
+          </summary>
+          <p className='text-body text-fg-secondary'>單一區塊用 details 即可。</p>
+        </details>
+        <Label>原生 HTML 簡潔,無須額外 JS</Label>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/Accordion/accordion.spec.md

@@ -19,7 +19,7 @@ benchmark:
 
 Accordion 是**垂直堆疊、可收合的多區塊容器**——每個 item 由 header（含 chevron）點擊切換展開 / 收合狀態。適合「多段內容,多數時間只想看其中一段」的情境。
 
-**實作基礎**：shadcn/ui 結構 + Radix Accordion primitive。本 DS 保留 shadcn 的 `Accordion / AccordionItem / AccordionTrigger / AccordionContent` API,視覺全改本 DS token,移除 shadcn 預設的 hover underline(web 早期 link style,與現代 SaaS 質感不符)。
+**實作基礎**：shadcn/ui 結構 + Radix Accordion primitive。本 DS 保留 shadcn 的 `Accordion / AccordionItem / AccordionTrigger / AccordionContent` API,視覺全改本 DS token(與 shadcn 預設的差異見「視覺規則」)。
 
 **Layout Family**：非上述 family — composite / multi-section（多個 AccordionItem 垂直堆疊，自 own layout）。
 
@@ -30,7 +30,8 @@ Accordion 是**垂直堆疊、可收合的多區塊容器**——每個 item 由
 - **FAQ / 說明**：常見問題、使用教學（預設全收合，使用者展開有興趣的）
 - **設定分組**：一般 / 通知 / 安全 / 付款等多節 settings 頁（長 form 拆段）
 - **進階選項可隱藏**：預設展示主要欄位，「進階選項」收合起來避免壓力
-- **單邊 sidebar 多分類**：檔案樹、notion-style 工作區 sidebar
+- **單邊 sidebar 多分類(淺層分組)**:notion-style 工作區 sidebar 的 section 收合;檔案樹 / 深度 tree 改用 `TreeView`(見「何時不用」)
+- **多段獨立收合（非互斥切換）**：各段內容垂直堆疊、可各自展開收合——若是「同一塊空間互斥切換視圖」改用 Tabs（見「何時不用」）
 
 ## 何時不用
 
@@ -72,7 +73,10 @@ Accordion 是**垂直堆疊、可收合的多區塊容器**——每個 item 由
 - **Content 文字**:次要閱讀色—— 主資訊在 trigger,展開內容是補充
 - **焦點環**:鍵盤 focus 用 ring token(非自訂 outline)
 
-**為什麼 hover 不用底線**:shadcn 預設 `hover:underline` 是 web 早期 link convention,現代 SaaS(Notion / Linear / Stripe / Vercel)皆不使用。改用文字色 tint 弱化維持統一質感,同時保留可點擊提示——不變色會讓使用者不確定是否能點擊,比起「被誤以為是 link」的風險,「失去可點擊提示」的風險更高。
+**為什麼 hover 不用底線**:
+- shadcn 預設 `hover:underline` 是 web 早期 link convention,現代 SaaS(Notion / Linear / Stripe / Vercel)皆不使用
+- 改用文字色 tint 弱化,維持 DS 統一質感
+- 仍保留可點擊提示——完全不變色會讓使用者不確定能否點擊;「失去可點擊提示」的風險大於「被誤以為是 link」
 
 完整 class / token 對照見 anatomy story(`ColorMatrix` + `SizeMatrix`)。
 
@@ -84,7 +88,7 @@ Accordion 是**垂直堆疊、可收合的多區塊容器**——每個 item 由
 - ❌ **不寫「全部展開 / 全部收合」按鈕**（違反 accordion 節省空間的設計意圖;若需要此功能,改用 TreeView 或 DescriptionList）
 - ❌ **單一 item 不用 Accordion**（用 `<details>` 或自組 toggle;見「何時不用」）
 - ❌ **不用 Accordion 做主要導航**（主導航用 Tabs / Sidebar,Accordion 是 content-level 收合）
-- ❌ **AccordionContent 不放互動重焦點元素**（例:complex form / Dialog trigger;收合後焦點消失,但如果只是輸入欄位可以）
+- ❌ **AccordionContent 不放重焦點互動元素**（例:complex form / Dialog trigger）——a11y 硬限制:item 被收合時(尤其 `single` 模式展開他段會自動收合本段)內部焦點隨 content 隱藏而消失,鍵盤使用者失去落點。少量輸入欄位可以(UX 建議層級:使用者通常完成填寫才切換)
 
 ---
 
@@ -99,9 +103,25 @@ Consumer 無需額外處理,保留 Radix `data-state` 屬性即可。
 
 ---
 
+## 常見誤解
+
+**誤解**:「Accordion 該提供全部展開 / 全部收合按鈕」。
+**事實**:期待「全展開一次讀完 / 全收合做導航」代表內容是參照型結構——那是 TreeView / DescriptionList 的場景。Accordion 的設計意圖是節省空間、一次聚焦一段(見「禁止事項」)。
+
+---
+
 ## 邊界狀態
 
-Empty state 由 consumer 處理(無 items 則不渲染);loading 狀態由 consumer 用 `<Skeleton />` 包;disabled state 詳 `../Field/field-controls.spec.md`;density 由 Radix 繼承。
+Empty state 由 consumer 處理(無 items 則不渲染);loading 狀態由 consumer 用 `<Skeleton />` 包;本元件無 density 概念,padding 固定為 `py-4 / pb-4`(不隨 density token 變動)。
+
+**Disabled**(Accordion 是 composite 家族,**非 Field 家族**——disabled 行為由 Radix Accordion 提供,不走 field-controls SSOT):
+
+- **Root `disabled`**:停用整個 accordion,所有 trigger 皆不可展開 / 聚焦。
+- **AccordionItem `disabled`**:停用單一 item——Radix 將 `disabled` 設在原生 `<button>` trigger 上,故該 trigger 鍵盤 Tab / ArrowUp/Down 會**略過**(原生 disabled 不可聚焦),點擊亦無反應;視覺上 trigger 文字 + chevron 切語義 `text-fg-disabled`(非降透明度,對齊 Button variant=text)。live 展示見 anatomy `StateBehavior` 的「disabled item」段。
+
+**固定 anatomy(不支援 `asChild`)**:`AccordionTrigger` 恆渲染 `children + ChevronDown` 兩個子節點,`AccordionContent` 恆以內層 `<div className="pb-4">` 包住 children——兩者的型別皆已 `Omit<..., 'asChild'>`,**不對外開放 `asChild`**。理由:傳入會讓 Radix Slot 觸發 `React.Children.only` runtime 錯(Trigger 多子節點),或 consumer 元素無法成為 Content host(只 clone 內層 div)。需替換 host 結構時改自組 Radix Accordion。
+
+**垂直留白世界級對照(2026-06-12 source-verified)**:shadcn trigger `py-4`=16px(本 DS 基底,一字不差;[ui.shadcn.com/docs/components/accordion](https://ui.shadcn.com/docs/components/accordion))/ Ant Collapse header 垂直 = paddingSM 12px([github.com/ant-design/ant-design](https://github.com/ant-design/ant-design/tree/master/components/collapse))/ MUI Accordion = minHeight 48 + content margin 12px(expanded 64/20 漸進式;[github.com/mui/material-ui](https://github.com/mui/material-ui/tree/master/packages/mui-material/src/Accordion))/ Carbon = min-height token 模型([github.com/carbon-design-system/carbon](https://github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Accordion))——業界垂直節奏值域 12-16px,16px 為舒適端上緣;item 數量無內建上限與虛擬捲動(全數 render),極長清單的收納(拆頁 / 搜尋)由 consumer 內容層處理。
 
 ---
 
@@ -112,3 +132,9 @@ Empty state 由 consumer 處理(無 items 則不渲染);loading 狀態由 consum
 - `../Sheet/sheet.spec.md` — 側邊抽屜
 - `../TreeView/tree-view.spec.md` — 具層級結構的收合（Accordion 的巢狀延伸）
 - Radix Accordion primitive — `@radix-ui/react-accordion`
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `tabs.spec.md`

package/src/components/Accordion/accordion.stories.tsx

@@ -0,0 +1,192 @@
+// @story-history: hasInteractiveStates 的 collapsed↔expanded / disabled item / keyboard 矩陣由 anatomy.stories.tsx StateBehavior owns(含 data-state 標註 + 鍵盤對照表 + token rationale);showcase 層只保留真實業務情境(FAQ / 設定分組 / 進階選項),不再平行重教同一組 state(earn-existence 2-test:showcase States 移除後 spec 理解不 degrade,2026-05-30 audit Dim 24)。
+import type { Meta, StoryObj } from '@storybook/react'
+import {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from './accordion'
+import { Field, FieldLabel } from '@/design-system/components/Field/field'
+import { Input } from '@/design-system/components/Input/input'
+
+const meta: Meta<typeof Accordion> = {
+  title: 'Design System/Components/Accordion/展示',
+  component: Accordion,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '垂直堆疊、可收合的多區塊容器——適合 FAQ、設定分組、進階選項可隱藏等情境。基於 Radix Accordion,視覺套用本 DS token。',
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof Accordion>
+
+// ── Default — minimal single + collapsible(真實退款 FAQ 雙 item)─────────
+
+export const Default: Story = {
+  name: '預設',
+  render: () => (
+    <div className="max-w-[480px]">
+      <Accordion type="single" collapsible defaultValue="refund-window">
+        <AccordionItem value="refund-window">
+          <AccordionTrigger>退款要多久才會入帳?</AccordionTrigger>
+          <AccordionContent>
+            信用卡退款於 5–10 個工作天內退回原付款帳戶,實際入帳時間依發卡銀行作業而定。
+          </AccordionContent>
+        </AccordionItem>
+        <AccordionItem value="refund-fee">
+          <AccordionTrigger>退款會扣手續費嗎?</AccordionTrigger>
+          <AccordionContent>
+            標準訂單退款不收手續費;若為跨境訂單,匯率價差由發卡機構認列,本平台不另收費。
+          </AccordionContent>
+        </AccordionItem>
+      </Accordion>
+    </div>
+  ),
+}
+
+// States(showcase)retired 2026-05-30 per audit Dim 24 —
+// closed / open / disabled 並列矩陣與 anatomy StateBehavior 完全重疊(後者另含 data-state
+// 標註 + 鍵盤對照表 + token rationale,教學更完整)。disabled item 的 live 情境改由
+// SettingsSections / AdvancedOptions 真實場景隱含覆蓋,interactive-states trait 由
+// anatomy StateBehavior owns(見檔首 @story-trait-rationale)。
+
+// ── FAQ(single + collapsible)——Stripe / Notion 類說明頁 ─────────
+
+export const FAQ: Story = {
+  name: 'FAQ 常見問題',
+  render: () => (
+    <div className="max-w-[640px]">
+      <Accordion type="single" collapsible>
+        <AccordionItem value="item-1">
+          <AccordionTrigger>如何更改我的訂閱方案?</AccordionTrigger>
+          <AccordionContent>
+            你可以在「設定 → 帳單」頁面升級或降級方案。升級立即生效,按比例計費;降級於下一個帳單週期生效,目前週期維持原方案。
+          </AccordionContent>
+        </AccordionItem>
+        <AccordionItem value="item-2">
+          <AccordionTrigger>企業方案支援 SSO 嗎?</AccordionTrigger>
+          <AccordionContent>
+            企業方案支援 SAML 2.0 單一登入,整合 Okta、Azure AD、Google Workspace 等主流 IdP。詳細設定步驟請參考企業管理員文件。
+          </AccordionContent>
+        </AccordionItem>
+        <AccordionItem value="item-3">
+          <AccordionTrigger>資料可以匯出嗎?</AccordionTrigger>
+          <AccordionContent>
+            可以。所有方案皆支援 CSV / JSON 匯出;企業方案另支援 API 批次匯出與 webhook 即時同步。
+          </AccordionContent>
+        </AccordionItem>
+        <AccordionItem value="item-4">
+          <AccordionTrigger>取消訂閱後資料會保留多久?</AccordionTrigger>
+          <AccordionContent>
+            取消後資料保留 90 天供復用。期滿後永久刪除,請於期限內匯出。企業方案可延長保留期至 180 天。
+          </AccordionContent>
+        </AccordionItem>
+      </Accordion>
+    </div>
+  ),
+}
+
+// ── Settings sections(multiple)——Jira / Linear 類設定頁 ──────────
+
+export const SettingsSections: Story = {
+  name: '設定分組',
+  render: () => (
+    <div className="max-w-[640px]">
+      <Accordion type="multiple" defaultValue={['notifications']}>
+        <AccordionItem value="general">
+          <AccordionTrigger>一般設定</AccordionTrigger>
+          <AccordionContent>
+            <div className="flex flex-col gap-2 text-body text-fg-secondary">
+              <p>工作區名稱:Acme Design Team</p>
+              <p>時區:台北(UTC+8)</p>
+              <p>預設語言:繁體中文</p>
+            </div>
+          </AccordionContent>
+        </AccordionItem>
+        <AccordionItem value="notifications">
+          <AccordionTrigger>通知偏好</AccordionTrigger>
+          <AccordionContent>
+            <div className="flex flex-col gap-2 text-body text-fg-secondary">
+              <p>Email 每日摘要:開啟</p>
+              <p>桌面即時通知:關閉</p>
+              <p>@提及我時:立即通知</p>
+            </div>
+          </AccordionContent>
+        </AccordionItem>
+        <AccordionItem value="security">
+          <AccordionTrigger>安全與登入</AccordionTrigger>
+          <AccordionContent>
+            <div className="flex flex-col gap-2 text-body text-fg-secondary">
+              <p>兩步驟驗證:已啟用(Authenticator)</p>
+              <p>登入工作階段:3 個裝置</p>
+              <p>最近登入:2 小時前(Chrome on macOS)</p>
+            </div>
+          </AccordionContent>
+        </AccordionItem>
+        <AccordionItem value="billing">
+          <AccordionTrigger>帳單與付款</AccordionTrigger>
+          <AccordionContent>
+            <div className="flex flex-col gap-2 text-body text-fg-secondary">
+              <p>目前方案:Team(月付 NT$480 / 每位使用者)</p>
+              <p>下次扣款:2026/05/19</p>
+              <p>付款方式:Visa **** 4242</p>
+            </div>
+          </AccordionContent>
+        </AccordionItem>
+      </Accordion>
+    </div>
+  ),
+}
+
+// ── 進階選項可隱藏 ───────────────────────────────────────────────
+
+export const AdvancedOptions: Story = {
+  name: '進階選項可隱藏',
+  render: () => (
+    <div className="max-w-[640px] flex flex-col gap-4">
+      <Field>
+        <FieldLabel>專案名稱</FieldLabel>
+        <Input defaultValue="Q2 發布計畫" />
+      </Field>
+      <Field>
+        <FieldLabel>專案描述</FieldLabel>
+        <Input placeholder="一句話描述此專案" />
+      </Field>
+      {/* 2026-07-14 Dim 68 修:原單一 AccordionItem 違反 accordion.spec.md「❌ 單一 item 不用
+          Accordion」(單區塊該用 <details>,見 principles「單一項目不用 Accordion」)。補第二個
+          可獨立收合的低頻設定段(type="multiple" 非互斥),成為合法多段收合場景。 */}
+      <Accordion type="multiple">
+        <AccordionItem value="advanced">
+          <AccordionTrigger>進階選項</AccordionTrigger>
+          <AccordionContent>
+            <div className="flex flex-col gap-3">
+              <Field>
+                <FieldLabel>專案識別碼(選填)</FieldLabel>
+                <Input className="font-mono" placeholder="例:Q2-RELEASE" />
+              </Field>
+              <Field>
+                <FieldLabel>預設檢視模式</FieldLabel>
+                <Input defaultValue="看板" />
+              </Field>
+            </div>
+          </AccordionContent>
+        </AccordionItem>
+        <AccordionItem value="notifications">
+          <AccordionTrigger>通知設定</AccordionTrigger>
+          <AccordionContent>
+            <Field>
+              <FieldLabel>狀態變更通知對象</FieldLabel>
+              <Input placeholder="例:專案成員 + 關注者" />
+            </Field>
+          </AccordionContent>
+        </AccordionItem>
+      </Accordion>
+    </div>
+  ),
+}