# @qijenchen/design-system — 完整設計參考(llms-full)

> 全 component / pattern 的 variants / sizes / 禁止事項。build-time 從 spec.md frontmatter 生成,禁手改。v0.1.0-beta.65。

# Components

## Accordion(family composite)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Accordion/

## Alert(family 2)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Alert/

### Variants
- **neutral**: 中性提示(系統公告、非緊急說明);無情緒色
- **info**: 資訊性提示(版本更新、流程說明);藍色 hue
- **success**: 成功狀態的持久性宣告(綁定生效、付款完成需保留確認)
- **warning**: 警告但非阻斷(方案即將到期、需更新付款方式);最高頻使用
- **error**: 錯誤但非阻斷(系統錯誤但可重試、API 失敗摘要);搭配 aria-live=assertive

## app-shell(family composite)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/AppShell/

## AspectRatio(family self-contained)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/AspectRatio/

## Avatar(family self-contained)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Avatar/

## Badge(family self-contained)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Badge/

### Variants
- **critical**: 最高優先級通知 — 錯誤計數 / 緊急徽章（Gmail 未讀 / iOS notification red dot）
- **high**: 高優先級通知 — 主要計數（Slack 訊息計數 / GitHub PR review badge）
- **medium**: 中優先級提示 — 次級計數（Linear issue count / Notion sidebar indicator）
- **low**: 低強度指示 — 使用者切 tab 才看（Slack sidebar 靜默標記 / VS Code tab modified dot）

## Breadcrumb(family composite)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Breadcrumb/

## BulkActionBar(family composite)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/BulkActionBar/

## Button(family 3)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Button/

### Variants
- **primary**: 主要 action / CTA。**必 explicit `variant="primary"`,不靠預設**(2026-06-06 起預設改低 emphasis)
- **secondary**: 陪襯 primary 的次要 action
- **tertiary**: **labeled 按鈕預設** / 第三級 action(tool-like / icon-heavy)。中性外框、清楚可點性,再按重要程度升 primary
- **text**: 文字樣式 — low emphasis / toolbar embedded。**iconOnly 按鈕預設**(對齊 action-bar「純動作工具→text」+ Material 3「icon-only = no fill」)
- **link**: 內文連結 — inline reading context

### Sizes
- **xs**: row-embedded inline(FileItem rich action / DataTable row action)
- **sm**: form field-height 28 / compact chrome
- **md**: default general UI
- **lg**: touch / prominent CTA / stakeholder-facing surface

### 禁止事項(when NOT / anti-pattern)
- iconOnly 必傳 aria-label — a11y 硬性要求 — 無 label 盲人讀不到
- 不自加 embedded=true / dense 類維度 — Embedded 情境走 L2 host slot(如 Input.endAction)不擴 Button
- dismiss 走 dismiss prop 不用 destructive — Dismiss 是功能弱化 fg-muted,非破壞性

## Calendar(family composite)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Calendar/

## Carousel(family composite)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Carousel/

## Chart(family composite)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Chart/

## Checkbox(family self-contained)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Checkbox/

### Sizes
- **sm**: form field-height 28 / compact chrome / dialog / panel context
- **md**: default general UI
- **lg**: touch / prominent CTA / stakeholder-facing surface

## Chip(family 3)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Chip/

## CircularProgress(family self-contained)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/CircularProgress/

## Coachmark(family composite)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Coachmark/

## Combobox(family 4)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Combobox/

## DataTable(family composite)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/DataTable/

## DatePicker(family 4)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/DatePicker/

## DescriptionList(family composite)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/DescriptionList/

## Dialog(family composite)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Dialog/

## DropdownMenu(family 1)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/DropdownMenu/

## Empty(family composite)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Empty/

## Field(family self-contained)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Field/

## FieldControlGroup(family self-contained)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/FieldControlGroup/

## FieldControls

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Field/

## FileItem(family 2)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/FileItem/

## FileUpload(family self-contained)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/FileUpload/

### Variants
- **dropzone**: 預設 — 大型 dashed 拖放區;「拖放有價值」+ 主要上傳區(drag + click)
- **button**: form 內單欄 / 空間省 / 與其他 field 並列 — 緊湊 Button 觸發(click-only)

## FileViewer(family composite)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/FileViewer/

## Input(family 4)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Input/

## LinkInput(family 4)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/LinkInput/

## NumberInput(family 4)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/NumberInput/

## PeoplePicker(family 4)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/PeoplePicker/

## Popover(family composite)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Popover/

## ProgressBar(family self-contained)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/ProgressBar/

## RadioGroup(family self-contained)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/RadioGroup/

### Sizes
- **sm**: form field-height 28 / compact chrome / dialog / panel context
- **md**: default general UI
- **lg**: touch / prominent CTA / stakeholder-facing surface

## Rating(family self-contained)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Rating/

## ScrollArea(family self-contained)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/ScrollArea/

## SegmentedControl(family 3)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/SegmentedControl/

### Sizes
- **xs**: row-embedded inline action(DataTable row inline action / Toolbar 內塞 segmented filter);text-caption
- **sm**: form field-height 28 / compact chrome bar(Filter bar / dense Toolbar)
- **md**: 預設 — 跟 Button / Input / 所有 field-height 系列一致;通用 form 內 toggle
- **lg**: touch / prominent 切換(landing 主視覺切 chart 維度、marketing form);text-body-lg

## Select(family 4)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Select/

## Separator(family self-contained)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Separator/

## Sheet(family composite)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Sheet/

## Sidebar(family 1)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Sidebar/

### Variants
- **default**: 標準導覽 row — 參與 single-selection,fg-secondary → hover foreground / active neutral-selected
- **meta**: Section 底部命令 row(「Show more」「載入更多」「+ 新增專案」);font-normal + fg-muted,不參與 selection

### Sizes
- **sm**: 次導覽 / 設定頁分類 / 緊湊空間;對齊 field-height-sm
- **md**: 預設 — 應用程式主導覽 row;對齊 TreeView / MenuItem 同 size 視覺無縫
- **lg**: 重要主導覽(高 touch 區、horizontal headroom 大)、icon-prominent workspace switcher

## Skeleton(family self-contained)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Skeleton/

## Slider(family self-contained)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Slider/

### Sizes
- **sm**: Toolbar / inline 編輯;對齊 field-height-sm(md density)
- **md**: 預設 — Form + 設定面板 + DataTable cell inline edit;對齊 field-height-md(md density)
- **lg**: Marketing hero 互動 / 高 touch 區;對齊 field-height-lg(md density)

## Steps(family 2)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Steps/

### Sizes
- **sm**: Sidebar / 緊湊 onboarding;indicator 8px dot(hit area 24px),無內部 icon。對齊 INDICATOR_SIZE.sm + INDICATOR_ICON_SIZE.sm=0(steps.tsx:18-28)
- **md**: 預設 — 主流程 wizard / checkout / 註冊;indicator 24px circle,內部 icon 16px(對齊 uiSize Icon Tier sm/md)
- **lg**: Marketing / 重要 onboarding;indicator 32px circle,內部 icon 20px(對齊 uiSize Icon Tier lg)

## Switch(family self-contained)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Switch/

### Sizes
- **sm**: form field-height 28 / compact chrome / dialog / panel context
- **md**: default general UI
- **lg**: touch / prominent CTA / stakeholder-facing surface

## Tabs(family composite)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Tabs/

### Sizes
- **sm**: ★ cva default — 所有 header 內 tabs(overlay / chrome header / Dialog / Sidebar / dense toolbar)
- **md**: future tier — 目前無 recommended use case,新 consumer 須先諮詢 DS owner
- **lg**: 獨立 tabs 直接取代 chrome header — page-level workspace 主導覽(tab 高度 = chrome-header-height)

## Tag(family 3)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Tag/

### Variants
- **neutral**: 通用分類、草稿、無特定語義（GitHub label default / Notion page tag untagged）
- **blue**: categorical 色相（--color-blue-*）— 分類 / 標記，常用於資訊類
- **green**: categorical 色相（--color-green-*）— 分類 / 標記，常用於完成 / 正向類
- **deep-orange**: categorical 色相（--color-deep-orange-*，hue 38）— 暖橙紅分類
- **yellow**: categorical 色相（--color-yellow-*，淺底深字）— 分類 / 標記，常用於注意類
- **red**: categorical 色相（--color-red-*，品牌紅家族 hue 25；≠ 語意 --error，與 deep-orange 無關）
- **orange**: categorical 色相（--color-orange-*）— 分類 / 標記
- **amber**: categorical 色相（--color-amber-*，淺底深字）— 琥珀分類
- **lime**: categorical 色相（--color-lime-*）— 黃綠分類
- **turquoise**: categorical 色相（--color-turquoise-*）— 產品線 / 團隊區別標記
- **indigo**: categorical 色相（--color-indigo-*）— 產品線 / 團隊區別標記
- **purple**: categorical 色相（--color-purple-*）— 產品線 / 團隊區別標記
- **magenta**: categorical 色相（--color-magenta-*）— 產品線 / 團隊區別標記

### Sizes
- **sm**: form field-height 28 / compact chrome / dialog / panel context
- **md**: default general UI
- **lg**: touch / prominent CTA / stakeholder-facing surface

## Textarea(family 4)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Textarea/

### Sizes
- **sm**: form field-height 28 / compact chrome / dialog / panel context
- **md**: default general UI
- **lg**: text-body-lg（16px）

## TimePicker(family 4)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/TimePicker/

## Toast(family 2)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Toast/

### Variants
- **neutral**: 非狀態通知;一般 announcement / tip(『已複製到剪貼簿』『偏好已儲存』)
- **info**: 資訊性提示(『新版本可用』『同步完成』);非錯誤、非成功
- **success**: 成功確認(『訂單已寄送』『付款完成』『5 筆資料已匯入』)
- **warning**: 可恢復警告(『有未儲存變更』『連線不穩』『token 將過期』)
- **error**: 錯誤(『匯入失敗』『權限不足』『網路斷線』);action prop 可加重試

## Tooltip(family composite)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/Tooltip/

## TreeView(family 1)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/components/TreeView/

# Patterns

## action-bar

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/patterns/action-bar/

## element-anatomy

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/patterns/element-anatomy/

## header-canonical(family self-contained)

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/patterns/header-canonical/

## ResizeHandle

Storybook: https://ajenchen-design-system.netlify.app
Source(AI 讀此看官方範例): src/patterns/resize-handle/
