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

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

@@ -0,0 +1,190 @@
+// @story-trait-rationale: 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'
+
+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">
+      <div className="flex flex-col gap-1">
+        <label className="text-body font-medium text-foreground">專案名稱</label>
+        <input
+          className="h-field-md border border-border rounded-md px-3 text-body"
+          defaultValue="Q2 發布計畫"
+        />
+      </div>
+      <div className="flex flex-col gap-1">
+        <label className="text-body font-medium text-foreground">專案描述</label>
+        <input
+          className="h-field-md border border-border rounded-md px-3 text-body"
+          placeholder="一句話描述此專案"
+        />
+      </div>
+      <Accordion type="single" collapsible>
+        <AccordionItem value="advanced">
+          <AccordionTrigger>進階選項</AccordionTrigger>
+          <AccordionContent>
+            <div className="flex flex-col gap-3">
+              <div className="flex flex-col gap-1">
+                <label className="text-body text-foreground">專案識別碼(選填)</label>
+                <input
+                  className="h-field-md border border-border rounded-md px-3 text-body font-mono"
+                  placeholder="例:Q2-RELEASE"
+                />
+              </div>
+              <div className="flex flex-col gap-1">
+                <label className="text-body text-foreground">預設檢視模式</label>
+                <input
+                  className="h-field-md border border-border rounded-md px-3 text-body"
+                  defaultValue="看板"
+                />
+              </div>
+            </div>
+          </AccordionContent>
+        </AccordionItem>
+      </Accordion>
+    </div>
+  ),
+}

package/src/components/Accordion/accordion.tsx

@@ -49,6 +49,9 @@ const AccordionTrigger = React.forwardRef<
         'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
         // AccordionTrigger 單一 text-style 列 → semantic `text-fg-disabled`(非 opacity);Button canonical 對齊
         'disabled:text-fg-disabled disabled:pointer-events-none',
+        // 2026-05-31 M24:disabled 時 chevron(icon 載體)亦降 text-fg-disabled,不停留 text-fg-muted
+        //（muted=neutral-7 比 disabled=neutral-6 深 → 層級顛倒)。覆寫 chevron 自身 text-fg-muted。
+        'disabled:[&>svg]:text-fg-disabled',
         "[&[data-state=open]>svg]:rotate-180",
         className,
       )}
@@ -93,7 +96,7 @@ export const accordionMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  states: ['default', 'hover', 'focus-visible', 'disabled'],
   tokens: {
     bg: [],
     fg: ['text-fg-disabled', 'text-fg-muted', 'text-fg-secondary', 'text-foreground'],

package/src/components/Accordion/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 './accordion'

package/src/components/Alert/alert.anatomy.stories.tsx

@@ -0,0 +1,238 @@
+// @anatomy-exempt: anatomy specs / token 對照表格用 raw <table>,非業務資料表。業務資料表才用 <DataTable>。
+// @anatomy-rationale:
+//   SizeMatrix N/A — Alert 固定 md tier(由消費的 Notice primitive 決定),
+//     不隨 density 縮放(僅 placement="fixed" 的水平 px 走 --layout-space-loose,density-aware)。Placement(inline / fixed)取代 size 作為佈局決策,
+//     已由 PlacementMatrix 涵蓋。
+import type { Meta, StoryObj } from '@storybook/react'
+import { Alert, type AlertProps } from './alert'
+import { H3, Desc, Td, Th } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+const meta: Meta = {
+  title: 'Design System/Components/Alert/設計規格',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+type InspectorStory = StoryObj<AlertProps>
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>Anatomy</H3>
+        <Desc>Alert 跟 Toast 共用同一套排版、圖示與主題策略。結構:圖示 + 標題 + 說明文字 + 右側操作區(endContent)+ 右上角關閉鈕。</Desc>
+        <Alert
+          variant="warning"
+          title="方案即將到期"
+          description="您的 Pro 方案將在 3 天後到期,請及時續訂以維持服務"
+        />
+      </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>
+              {[
+                ['variant', "'neutral' | 'info' | 'success' | 'warning' | 'error'", "'neutral'", '語意類型(決定 icon + 色彩)'],
+                ['appearance', "'subtle' | 'solid'", "'subtle'", '視覺重量(淺底邊框 vs 飽和底色)'],
+                ['placement', "'inline' | 'fixed'", "'inline'", 'inline 嵌內容 vs fixed 頂部全域警告'],
+                ['title', 'ReactNode', '必填', '主要訊息'],
+                ['description', 'ReactNode', '—', '補充說明'],
+                ['endContent', 'ReactNode', '—', '右側操作區（CTA 按鈕等）'],
+                ['dismissible', 'boolean', 'true', '是否顯示右上角關閉按鈕'],
+                ['onDismiss', '() => void', '—', '按下關閉按鈕時觸發'],
+              ].map(([p, t, d, desc]) => (
+                <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const Inspector: InspectorStory = {
+  name: '元件檢閱器',
+  parameters: {
+    docs: {
+      description: {
+        story: '在右側 Controls 面板切換 variant / appearance / placement / dismissible,即時查看 render 結果。世界級 DS 的 Inspector = Figma inspect 替代,讓 designer 直接在 Storybook 試出各種組合。',
+      },
+    },
+  },
+  args: {
+    variant: 'warning',
+    appearance: 'subtle',
+    placement: 'inline',
+    title: '方案即將到期',
+    description: '您的 Pro 方案將在 3 天後到期,請及時續訂以維持服務',
+    dismissible: true,
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['neutral', 'info', 'success', 'warning', 'error'],
+      description: '語意類型(決定 icon + 色彩)',
+    },
+    appearance: {
+      control: 'radio',
+      options: ['subtle', 'solid'],
+      description: '視覺重量:subtle(淺底邊框,預設)/ solid(飽和底色,全站警告)',
+    },
+    placement: {
+      control: 'radio',
+      options: ['inline', 'fixed'],
+      description: 'inline(預設,圓角嵌入)/ fixed(頂部全域,無圓角無邊框)',
+    },
+    title: { control: 'text', description: '主要訊息' },
+    description: { control: 'text', description: '補充說明' },
+    dismissible: { control: 'boolean', description: '是否顯示關閉按鈕' },
+  },
+  render: (args) => <Alert {...args} />,
+}
+
+export const ColorMatrix: Story = {
+  name: '色彩對照表',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>Subtle(淺底 + 邊框,預設)</H3>
+        <Desc>視覺重量適中,99% 的 Alert 用 subtle。不搶頁面焦點,使用者注意但可繼續主要任務。</Desc>
+        <div className="flex flex-col gap-3 max-w-xl">
+          <Alert variant="neutral" title="新功能上線" description="我們推出了 Dark Mode,請前往設定啟用" />
+          <Alert variant="info" title="系統維護中" description="部分功能暫停服務,預計 30 分鐘內恢復" />
+          <Alert variant="success" title="驗證通過" description="您的電子郵件已成功驗證" />
+          <Alert variant="warning" title="額度即將用完" description="您本月 API 額度已使用 90%" />
+          <Alert variant="error" title="付款失敗" description="您上次的訂閱付款失敗,請更新付款方式" />
+        </div>
+      </div>
+
+      <div>
+        <H3>Solid(飽和底色)</H3>
+        <Desc>視覺重量高,用於真的很重要的全站警告。一個頁面最多一個 solid Alert。</Desc>
+        <div className="flex flex-col gap-3 max-w-xl">
+          <Alert variant="info" appearance="solid" title="系統升級" description="本站將於 02:00 進行升級" />
+          <Alert variant="warning" appearance="solid" title="配額用盡" description="請立即升級方案以繼續使用" />
+          <Alert variant="error" appearance="solid" title="服務中斷" description="API 服務暫時不可用,工程團隊正在修復" />
+        </div>
+      </div>
+
+      <div>
+        <H3>Variant × Theme 策略</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Variant</Th><Th>Subtle</Th><Th>Solid</Th></tr></thead>
+            <tbody>
+              <tr><Td mono>neutral</Td><Td mono>bg-muted + border-border;無 status icon(VARIANT_ICON.neutral = null)</Td><Td>bg-surface-raised + data-theme inverse(跟頁面反)</Td></tr>
+              <tr><Td mono>info</Td><Td mono>bg-info-subtle + border-[var(--info-text)] + text-info-text</Td><Td mono>bg-info + data-theme="dark"(藍底白字)</Td></tr>
+              <tr><Td mono>success</Td><Td mono>bg-success-subtle + border-[var(--success-text)] + text-success-text</Td><Td mono>bg-success + data-theme="dark"(綠底白字)</Td></tr>
+              <tr><Td mono>warning</Td><Td mono>bg-warning-subtle + border-[var(--warning-text)] + text-warning-text</Td><Td mono>bg-warning + data-theme="light"(黃底深字)</Td></tr>
+              <tr><Td mono>error</Td><Td mono>bg-error-subtle + border-[var(--error-text)] + text-error-text</Td><Td mono>bg-error + data-theme="dark"(橘底白字)</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const PlacementMatrix: Story = {
+  name: '出現位置（內嵌 vs 固定）',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>Inline(預設) — 嵌入頁面內容</H3>
+        <Desc>`rounded-md`(4px)圓角 + 邊框,像一張 card 嵌在內容區塊裡。Settings 頁的方案提示、表單內的注意事項。</Desc>
+        <Alert
+          variant="warning"
+          title="即將到期"
+          description="您的方案將在 3 天後到期"
+        />
+      </div>
+
+      <div>
+        <H3>Fixed — 頂部全域警告</H3>
+        <Desc>無圓角無邊框,頁面寬度橫條。系統維護、服務降級、全站重要公告。</Desc>
+        <Alert
+          variant="info"
+          placement="fixed"
+          title="系統維護中"
+          description="2026-04-20 02:00-04:00 進行系統升級,部分功能暫停"
+        />
+      </div>
+
+      <div>
+        <H3>Placement 對照</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Placement</Th><Th>圓角</Th><Th>Border</Th><Th>用途</Th></tr></thead>
+            <tbody>
+              <tr><Td mono>inline ★default</Td><Td mono>rounded-md(4px)</Td><Td>有</Td><Td>頁面內嵌</Td></tr>
+              <tr><Td mono>fixed</Td><Td>無(rounded-none)</Td><Td>無</Td><Td>header 底下全域警告</Td></tr>
+            </tbody>
+          </table>
+        </div>
+        <p className="text-footnote text-fg-muted mt-3">Alert 是 inline 容器(不是浮層),用 `rounded-md`(4px)。Toast 是浮層用 `rounded-lg`(8px)。</p>
+      </div>
+    </div>
+  ),
+}
+
+export const StateBehavior: Story = {
+  name: '狀態行為',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>Dismissible(右側 close icon)</H3>
+        <Desc>
+          Alert 預設 `dismissible=true`,右上角顯示 close button。按 close 觸發 `onDismiss` 由 consumer 控制移除(Alert 本身不 own unmount 狀態——inline 通知通常需要 consumer 記住「使用者已關閉」狀態)。
+        </Desc>
+        <div className="flex flex-col gap-3 max-w-xl">
+          <Alert variant="info" title="可關閉" description="右上角有 close icon,按下觸發 onDismiss" />
+          <Alert variant="warning" title="不可關閉" description="永久性警告,設 dismissible={false} 隱藏 close icon" dismissible={false} />
+        </div>
+      </div>
+
+      <div>
+        <H3>Close button 互動狀態</H3>
+        <Desc>
+          Chrome corner close 用 **Button iconOnly `dismiss` size="xs"**(notification banner family 設計準則,見 `overlay-surface.spec.md`「Chrome dismiss size canonical」)。現行 canonical 為兩分:notification banner family(Notice / Alert / Toast,px-4 py-3 固定)dismiss 用 `xs`;overlay surface(Dialog / Sheet / Popover)另走 `sm` + unbounded 負 margin trick。corner 屬 action group region,實務上可與 refresh / share 等 Button 並排(用 ButtonDivider 分群),必須統一 Button primitive + 同 family 全 xs。`dismiss` prop 自動套 `variant="text"` + icon `fg-muted` 弱化,hover 時恢復 foreground。
+        </Desc>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>State</Th><Th>視覺</Th><Th>Token</Th></tr></thead>
+            <tbody>
+              <tr><Td>default</Td><Td>Button xs iconOnly(24×24),X icon 16,fg-muted</Td><Td mono>text-fg-muted(`dismiss` override)</Td></tr>
+              <tr><Td>hover</Td><Td>Button bg 套 neutral-hover,icon 升 foreground</Td><Td mono>bg-neutral-hover / text-foreground</Td></tr>
+              <tr><Td>focus</Td><Td>2px ring(鍵盤導航)</Td><Td mono>ring-ring ring-offset-1</Td></tr>
+              <tr><Td>solid appearance</Td><Td>icon 隨 variant 的 data-theme:info / success / error(dark theme)白字,warning(light theme)深字</Td><Td mono>text-fg-muted → hover text-foreground(隨 data-theme 翻轉)</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div>
+        <H3>非互動 Alert(無內建 open/close state)</H3>
+        <Desc>
+          Alert 本身無 open/closed state——它是 inline 容器,「顯示」= consumer 把 Alert render 進 tree,「關閉」= consumer 從 tree 移除。與 Toast(有 open 動畫 + auto-dismiss timer)語意不同。
+        </Desc>
+      </div>
+    </div>
+  ),
+}
+
+// ── Accessibility ─────────────────────────────────────────────────────────
+// 2026-05-17 ship per audit Dim 13(story-rules.md 6-canonical 含 Accessibility)
+export const Accessibility = {
+  name: '無障礙',
+  render: () => (
+    <div className="max-w-3xl text-body text-fg-secondary">
+      <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
+      <p className="whitespace-pre-line">{"無障礙朗讀行為依 variant 自動切換：\n\n-   一般提示（neutral / info / success）  ： role=\"status\"  +  aria-live=\"polite\" ——螢幕報讀器在使用者空閒時才讀出內容，不打斷目前動作\n-   緊急提示（warning / error）  ： role=\"alert\"  +  aria-live=\"assertive\" ——立即中斷目前朗讀讀出內容，因為使用者必須馬上知道\n-   關閉按鈕  ：必須有  aria-label （如「關閉通知」）\n-   行動按鈕  ：放在 Alert 內的操作按鈕用最小尺寸、低調樣式，文字直接描述動作（「前往設定」「立即更新」）"}</p>
+    </div>
+  ),
+}