@qijenchen/design-system 0.1.0-beta.3 → 0.1.0-beta.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qijenchen/design-system",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.32",
   "private": false,
   "description": "World-class design system — components, patterns, tokens, hooks (single source of truth for team distribution).",
   "type": "module",
@@ -8,14 +8,17 @@
   "files": [
     "dist",
     "src/**/*.{tsx,ts,css}",
+    "src/**/*.spec.md",
     "!src/**/*.stories.tsx",
     "!src/**/*.anatomy.stories.tsx",
     "!src/**/*.principles.stories.tsx",
-    "!src/**/*.spec.md",
     "!src/**/*.spec.ts",
     "!src/**/*.test.ts",
     "README.md",
-    "scripts"
+    "CLAUDE.md",
+    "ds-canonical",
+    "cli-init.mjs",
+    "ds-story-manifest.json"
   ],
   "exports": {
     ".": {
@@ -30,12 +33,18 @@
       "types": "./dist/patterns/*/index.d.ts",
       "import": "./dist/patterns/*/index.js"
     },
-    "./tokens/*": "./dist/tokens/*",
+    "./tokens/*": "./src/tokens/*",
     "./hooks/*": {
       "types": "./dist/hooks/*.d.ts",
       "import": "./dist/hooks/*.js"
     },
-    "./styles/globals.css": "./dist/globals.css"
+    "./styles/tokens.css": "./src/styles/tokens.css",
+    "./styles/tokens": "./src/styles/tokens.css",
+    "./package.json": "./package.json",
+    "./ds-story-manifest.json": "./ds-story-manifest.json"
+  },
+  "bin": {
+    "qijenchen-ds-init": "./cli-init.mjs"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -45,10 +54,13 @@
   ],
   "scripts": {
     "build": "vite build",
-    "build:dts": "tsc -p tsconfig.json",
+    "build:dts": "tsc -p tsconfig.json && tsc-alias -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
     "@radix-ui/react-accordion": "^1.2.12",
     "@radix-ui/react-aspect-ratio": "^1.1.8",
     "@radix-ui/react-checkbox": "^1.3.3",
@@ -68,9 +80,6 @@
     "@radix-ui/react-toggle": "^1.1.10",
     "@radix-ui/react-toggle-group": "^1.1.11",
     "@radix-ui/react-tooltip": "^1.2.8",
-    "@dnd-kit/core": "^6.3.1",
-    "@dnd-kit/sortable": "^10.0.0",
-    "@dnd-kit/utilities": "^3.2.2",
     "@tanstack/react-table": "^8.21.3",
     "@tanstack/react-virtual": "^3.13.23",
     "class-variance-authority": "^0.7.1",
@@ -80,6 +89,7 @@
     "embla-carousel-react": "^8.6.0",
     "lucide-react": "^0.577.0",
     "react-day-picker": "^9.14.0",
+    "react-is": "^18.0.0 || ^19.0.0",
     "react-zoom-pan-pinch": "^4.0.3",
     "recharts": "^3.8.1",
     "sonner": "^2.0.7",
@@ -89,5 +99,8 @@
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
     "tailwindcss": ">=4.0.0"
+  },
+  "devDependencies": {
+    "tsc-alias": "^1.8.17"
   }
 }

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

@@ -0,0 +1,114 @@
+---
+component: Accordion
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+  - isStructural
+benchmark:
+  - Radix Accordion primitive: github.com/radix-ui/primitives/tree/main/packages/react/accordion
+  - MUI Accordion: github.com/mui/material-ui/tree/master/packages/mui-material/src/Accordion
+  - Ant Design Collapse: github.com/ant-design/ant-design/tree/master/components/collapse
+  - Carbon Accordion: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Accordion
+---
+
+# Accordion 設計原則
+
+## 定位
+
+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 質感不符)。
+
+**Layout Family**：非上述 family — composite / multi-section（多個 AccordionItem 垂直堆疊，自 own layout）。
+
+---
+
+## 何時用
+
+- **FAQ / 說明**：常見問題、使用教學（預設全收合，使用者展開有興趣的）
+- **設定分組**：一般 / 通知 / 安全 / 付款等多節 settings 頁（長 form 拆段）
+- **進階選項可隱藏**：預設展示主要欄位，「進階選項」收合起來避免壓力
+- **單邊 sidebar 多分類**：檔案樹、notion-style 工作區 sidebar
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 只有一個區塊要收合 | `<details>` 或自組 toggle | Accordion 是「多 item」pattern,單 item 無必要 |
+| 切換平行視圖（A / B / C 三選一）| `Tabs` | Tabs 是互斥切換,Accordion 是獨立收合(或單選) |
+| 複雜 sidebar 導航（深度 tree）| `TreeView` / `Sidebar` | Accordion 無 nested 結構 |
+| 收合整個浮層/側欄 | `Dialog` / `Sheet` / `Popover` | 那是浮層控制不是 inline 收合 |
+| 長列表只顯示 N 個 | 自組 「顯示更多」按鈕 | Accordion 不是「more / less」pattern |
+
+---
+
+## type：single vs multiple
+
+**`type="single"`**（預設推薦）：一次只能展開一個 item。展開新 item 自動收合前一個。適合 FAQ / 指南類(讀者看完一段再下一段)。
+
+**`type="multiple"`**：多個 item 可同時展開。適合 settings page / 工作 context(使用者同時比對多段)。
+
+**判斷法**：「使用者會不會想同時看兩段?」會 → multiple;不會 / 同時看反而混亂 → single。
+
+---
+
+## collapsible (配合 single)
+
+`single` 搭配 `collapsible={true}`:已展開的那個可以再點一次收合(回到「全部收合」狀態)。預設 `false`——已展開的無法再收合(必須保持有一個展開)。
+
+- **FAQ / 使用教學** → `collapsible={true}`(允許全收起,乾淨視覺)
+- **必須展開一個才合理** → `collapsible={false}`(罕見)
+
+---
+
+## 視覺規則
+
+- **AccordionItem 底線**:相鄰 item 以底 divider 分隔(視覺界定每一段)
+- **Trigger 文字**:正常閱讀色 + medium 字重(可掃視的 section heading 等級)
+- **Trigger hover**:文字色 tint 弱化,**不用 underline**
+- **Chevron**:朝下 → data-state=open 旋轉 180° → 朝上,transition 帶平滑
+- **Content 文字**:次要閱讀色—— 主資訊在 trigger,展開內容是補充
+- **焦點環**:鍵盤 focus 用 ring token(非自訂 outline)
+
+**為什麼 hover 不用底線**:shadcn 預設 `hover:underline` 是 web 早期 link convention,現代 SaaS(Notion / Linear / Stripe / Vercel)皆不使用。改用文字色 tint 弱化維持統一質感,同時保留可點擊提示——不變色會讓使用者不確定是否能點擊,比起「被誤以為是 link」的風險,「失去可點擊提示」的風險更高。
+
+完整 class / token 對照見 anatomy story(`ColorMatrix` + `SizeMatrix`)。
+
+---
+
+## 禁止事項
+
+- ❌ **不在 Accordion 內放另一個 Accordion**（巢狀會讓使用者迷失;用 TreeView 或拆頁）
+- ❌ **不寫「全部展開 / 全部收合」按鈕**（違反 accordion 節省空間的設計意圖;若需要此功能,改用 TreeView 或 DescriptionList）
+- ❌ **單一 item 不用 Accordion**（用 `<details>` 或自組 toggle;見「何時不用」）
+- ❌ **不用 Accordion 做主要導航**（主導航用 Tabs / Sidebar,Accordion 是 content-level 收合）
+- ❌ **AccordionContent 不放互動重焦點元素**（例:complex form / Dialog trigger;收合後焦點消失,但如果只是輸入欄位可以）
+
+---
+
+## A11y 預設
+
+Radix Accordion 自動處理:
+- **鍵盤**：Tab 到 trigger → Enter/Space 切換;ArrowUp/Down 在 trigger 間移動
+- **ARIA**：trigger `aria-expanded` / `aria-controls` 自動設置,content `role="region"` + `aria-labelledby`
+- **焦點**：收合時焦點停在 trigger,不會跳到隱藏 content 內
+
+Consumer 無需額外處理,保留 Radix `data-state` 屬性即可。
+
+---
+
+## 邊界狀態
+
+Empty state 由 consumer 處理(無 items 則不渲染);loading 狀態由 consumer 用 `<Skeleton />` 包;disabled state 詳 `../Field/field-controls.spec.md`;density 由 Radix 繼承。
+
+---
+
+## 相關
+
+- `../Tabs/tabs.spec.md` — 互斥切換視圖（非收合）
+- `../Dialog/dialog.spec.md` — 阻斷性浮層
+- `../Sheet/sheet.spec.md` — 側邊抽屜
+- `../TreeView/tree-view.spec.md` — 具層級結構的收合（Accordion 的巢狀延伸）
+- Radix Accordion primitive — `@radix-ui/react-accordion`

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.spec.md

@@ -0,0 +1,197 @@
+---
+component: Alert
+family: 2
+traits:
+  - hasVariants
+  - hasInteractiveStates
+variants:
+  neutral:
+    when: "中性提示(系統公告、非緊急說明);無情緒色"
+    world-class: ["Ant Alert type=info(neutral)", "Polaris Banner default"]
+  info:
+    when: "資訊性提示(版本更新、流程說明);藍色 hue"
+    world-class: ["Ant Alert type=info", "Material Alert severity=info", "Carbon InlineNotification kind=info"]
+  success:
+    when: "成功狀態的持久性宣告(綁定生效、付款完成需保留確認)"
+    world-class: ["Ant Alert type=success", "Polaris Banner status=success"]
+  warning:
+    when: "警告但非阻斷(方案即將到期、需更新付款方式);最高頻使用"
+    world-class: ["Ant Alert type=warning", "Polaris Banner status=warning", "Material Alert severity=warning"]
+  error:
+    when: "錯誤但非阻斷(系統錯誤但可重試、API 失敗摘要);搭配 aria-live=assertive"
+    world-class: ["Ant Alert type=error", "Polaris Banner status=critical", "Carbon InlineNotification kind=error"]
+sizes: {}
+benchmark:
+  - Ant Design Alert: github.com/ant-design/ant-design/tree/master/components/alert
+  - MUI Alert: github.com/mui/material-ui/tree/master/packages/mui-material/src/Alert
+  - Carbon Notification: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Notification
+  - Polaris Banner: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Banner
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Alert 設計原則
+
+## 定位
+
+Alert 是**持久性通知**，嵌入在頁面中。用於系統狀態提示、警告、錯誤訊息。使用者需要主動 dismiss 或處理。
+
+**實作基礎**：消費 Notice primitive（共享 Toast 的 layout + icon + theme 策略）。
+
+**Layout Family**：CLAUDE.md 4-Family Model **Family 2（List item layout）** 消費者。結構繼承 `patterns/element-anatomy/item-anatomy.spec.md`「List item layout」章節的 reading-mode 規格。Alert 透過 Notice 繼承 Family 2 結構。
+
+---
+
+## 何時用
+
+- **頁面內需要持續存在的狀態通知**：方案即將到期、帳戶驗證未完成、需要更新付款方式
+- **頂部全域警告**（`placement="fixed"`）：系統維護中、服務降級、重要公告
+- **表單 / Dialog 內的 inline 提示**：複雜動作的前置警告（刪除前的資料影響說明）
+- **需要使用者處理才會消失的訊息**：有 CTA 可以解決問題、或需明確按下 dismiss
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 操作結果短暫回饋（儲存成功、刪除失敗）| `Toast` | Toast 自動消失，不佔頁面空間 |
+| 需要阻斷背景互動 | `Dialog` | Alert 是 inline，不阻斷 |
+| 欄位級驗證錯誤 | Field error message | Alert 是頁面級，欄位錯誤靠在欄位下方 |
+| 成功訊息需要使用者確認 | `Toast`（非阻斷）/ `Dialog`（需確認）| Alert 的持久成本對成功訊息太高 |
+
+---
+
+## 與 Toast / Notice 的分界
+
+**本節是 SSOT**——Toast spec 反向引用此節，避免兩側漂移。
+
+- **Alert**：持續顯示的 on-page 通知，使用者需主動 dismiss 或永不關閉（如頂部全域警告）
+- **Toast**：短暫浮動通知，自動消失（預設 3–5 秒）
+- **Notice**：兩者共用的內部 layout primitive，consumer **不直接使用**（由 Alert / Toast 消費）
+
+**判斷法**：問「這個訊息重要到需要使用者 acknowledge 嗎？」
+
+- 是（方案到期、帳戶未驗證、系統維護中、錯誤需要處理）→ **Alert**
+- 否（儲存成功、已複製、上傳完成）→ **Toast**
+
+---
+
+## 禁止事項
+
+- ❌ **不在 Alert 內放長篇內容**：Alert 是摘要 + CTA,超過 2–3 行的內容改用 Dialog 或導向獨立頁面
+- ❌ **不把 error form validation 做成 Alert**：欄位級錯誤必須貼近發生位置（FieldError）,使用者才能快速定位；頁面級 Alert 只放非欄位的整體錯誤（如提交失敗、權限不足）
+- ❌ **Alert 不疊 Alert**：同區出現多個 Alert 視覺雜訊重,整理成一組 messages 或合併為單一 Alert with list
+- ❌ **destructive 操作確認不用 Alert**：刪除 / 離開等需要明確確認的動作用 Dialog,Alert 無法承載 confirm / cancel 雙按鈕的阻斷流程
+- ❌ **body action row 不得混入 close X**:close X 必在 chrome corner action group,不可跟 CTA 擺在同一 row(違反 same-row consistency — CTA 是 labeled Button sm tertiary,close X 是 Button iconOnly sm dismiss,box size 與視覺分量不同,同 row 會造成 gap / 對齊錯亂)。完整規則見 `patterns/element-anatomy/inline-action.spec.md`「Same-row consistency rule(防混用)」節
+- ❌ **close X 不用 Inline Action 或自刻 `<button><X /></button>`**:corner 屬 action group region,必用 `<Button iconOnly dismiss size="sm" />`(見上方 Chrome corner close X canonical)
+
+---
+
+## A11y 預設
+
+- **預設**：`role="alert"` + `aria-live="polite"`——screen reader 在空閒時讀出 Alert 內容，不中斷使用者目前動作
+- **error variant 可升級**：`aria-live="assertive"` 中斷 screen reader 目前朗讀，立即讀出 Alert（僅用於真正 critical 的錯誤，避免濫用干擾）
+- **Close X 按鈕**：必須有 `aria-label`(如「關閉通知」),實作見下方「Chrome corner close X canonical」
+- **CTA 按鈕**：放在 Alert body action row 時 size 固定為 `xs` tertiary,文字描述動作(「前往設定」「立即更新」)
+
+---
+
+## Chrome corner close X canonical
+
+Alert 右上角的 close X **必須用 `<Button iconOnly dismiss size="sm" />`**,不是 Inline Action、不是自刻 button。
+
+**為什麼是 Button(Cat 3 Action group region)而非 Inline Action**:
+- Alert 的 chrome corner 屬 **action group region**(toolbar / chrome corner / standalone 類),實務上 close 左側可並排 refresh / share / minimize 等額外 action + `<Separator orientation="vertical" />`——一旦成為 action group,所有成員必同類(same-row consistency),統一 Button iconOnly
+- Inline Action 是「embedded 在 host 內部的 tap target」(Cat 1,如 Input clear X / Tag dismiss X),不參與 action group 規則,兩者不可混用
+- `dismiss` prop 自動套 `variant="text"` + `fg-muted → hover foreground` 弱化,視覺輕量不壓過內容
+
+**只有 X close(dismiss 語意「關閉 surface」)才套 `dismiss` prop**——Trash / Delete / Clear / Remove 不屬 dismiss,不套此 prop。
+
+SSOT 詳見 `patterns/element-anatomy/inline-action.spec.md`「Predicate:Inline Action vs Button iconOnly(canonical)」+「Dismiss canonical — X close only」章節;Button 端詳見 `components/Button/button.spec.md`「Dismiss 視覺類」段。
+
+### Corner action group 佈局 canonical
+
+Alert chrome corner 可承載多個 action(close 左側並排):
+
+```
+┌─ Alert ────────────────── [⟲] │ [X] ┐   ← chrome corner action group(Button sm)
+│ [icon] Title                         │     refresh / share / minimize 等 + Separator + close X
+│ Description                          │
+│                      [CTA1] [CTA2]   │   ← body action row(Button sm tertiary)
+└──────────────────────────────────────┘
+```
+
+**規則**:
+- 同一 action group 所有 Button 同 `size="sm"`(跟 close X 對齊)
+- 多 action 之間用 `<Separator orientation="vertical" />` 分群(`refresh / share` 一群,`close` 一群)
+- 若只有 close X 則不需要 Separator(單一 action 即 group)
+
+**世界級對照**:
+- **Material Banner**(`<Banner actions={[...]}/>` 右上 close + 可加 refresh)
+- **Polaris Banner**(`onDismiss` 走 IconButton,右上 action group)
+- **VS Code editor tab** window corner(close + pin + split,全部同 size IconButton)
+- **Figma panel corner**(close + collapse 同 group,Separator 分隔)
+
+### Multi corner action 場景
+
+目前 Alert API 只透過 `dismissible` 渲染單一 close X。多 corner action 場景目前不支援;若未來 consumer 有需求,走 Checkpoint 3 決策(M8 benchmark + consumer survey),不預先投機擴 API。
+
+---
+
+## Appearance
+
+### Subtle(預設)
+
+淺底色 + 四邊 1px border(邊框採語意色的 hover tint)。99% 場景用 subtle——視覺重量適中,使用者注意但可繼續主要任務。不設 `data-theme`,元素跟隨頁面 theme。
+
+### Solid
+
+飽和底色,跟 Toast 完全相同的 theme 策略(critical severity 場景:info / success / error 走 dark theme 白字,warning 走 light theme 深字以保對比)。一個頁面最多一個 solid Alert。
+
+Subtle vs Solid 的完整 variant × theme class 對照見 anatomy `ColorMatrix` story。
+
+## Placement
+
+- **`inline`(預設)**:頁面內嵌,圓角 + 邊框,像一張 card 嵌在內容區塊裡
+- **`fixed`**:頂部全域警告,無圓角無邊框,橫跨頁面寬度
+
+**為什麼兩種 placement 的圓角不同**:inline 是 content-level card(rounded-md = 4px,對齊 Alert 的 inline 容器身份,與 Dialog / Card 一致);fixed 是 page-level bar(無 radius,橫跨畫面形成整條)。Toast 是浮層用 `rounded-lg`(8px,浮層慣例),跟 Alert 區分。
+
+完整 placement 對照見 anatomy `PlacementMatrix` story。
+
+## 為何無 Inspector / SizeMatrix
+
+- **無 Inspector**:Alert 的關鍵決策維度是 `variant`(5 色)× `appearance`(subtle / solid)× `placement`(inline / fixed),已在 `ColorMatrix` 完整呈現 variant × appearance 矩陣,再加 `PlacementMatrix` 呈現 placement——互動切換式 Inspector 不會比這兩張矩陣更能傳達 Alert 的設計規格。
+- **無 SizeMatrix**:Alert 無 `size` prop,其視覺尺寸繼承自 Notice primitive(14px body / 16px icon / fixed padding),不隨 density 變動。尺寸規格由 `Notice` spec own。改 Notice 時 Alert 自動跟進,不需要 Alert 有獨立 SizeMatrix。
+
+對應 anatomy story:保留 `Overview` + `ColorMatrix` + `StateBehavior` + 元件特有 `PlacementMatrix`。
+
+---
+
+## API
+
+```tsx
+<Alert variant="warning" title="即將到期" description="您的方案將在 3 天後到期" />
+<Alert variant="error" appearance="solid" title="系統錯誤" />
+<Alert variant="info" placement="fixed" title="系統維護中，部分功能暫停" />
+```
+
+---
+
+## 邊界案例
+
+- **Disabled(dismiss button)**:Alert 本身無 `disabled` prop(持久通知不該被禁用),但 dismiss close X 為 `<Button iconOnly dismiss size="sm" />`,自動繼承 Button disabled 視覺(`text-fg-disabled` + `cursor-not-allowed` + 無 hover bg);實務場景:後台正在執行 close action(API in-flight)時 consumer 可 disable button 防 double-click,fg token 走 Button SSOT 不在 Alert 加層。
+- **Loading**:Alert 本身不需 loading state(非 async surface);若 Alert body action row 內 CTA 在 async 動作中,該 Button 自己處理 `loading` prop。
+- **Empty / icon-only**:Alert 必有 `title`(API contract),無 empty 場景;若無 description 則僅顯示 title + icon,layout 自動收斂。
+
+## 相關
+
+- `../Notice/notice.spec.md` — Alert 消費的 layout primitive（與 Toast 共用）
+- `../Toast/toast.spec.md` — 非阻斷短暫通知（同一套視覺策略）
+- `../Dialog/dialog.spec.md` — 需要阻斷背景的警告改用 Dialog
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `empty.spec.md`
+- `skeleton.spec.md`

package/src/components/Alert/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 './alert'