Design System · 設計系統

---
doc_type: "design-system"
variant: "light"
status: "draft"
owner: "<your-name>"
last_updated: "YYYY-MM-DD"
upstream:
  required: ["mockups", "brand-spec"]
  optional: ["existing-component-library"]
---

# Design System: <product-name>

**Status:** Draft v0.X · **Owner:** <UI name> · **Last updated:** YYYY-MM-DD

> [!IMPORTANT]
> **AI 填寫規則：** 本範本 6 段（編號 1, 2, 3, 6, 10, 12），全部必填——刻意沿用完整版章節編號讓兩版可對照。Tokens 至少 4 類（color / spacing / typography / radius）；元件至少 5 個核心；states 至少 5 種；每結論行內加 `（依據：mockup §XXX / brand §YYY）`；每量化欄位加 `[H]/[M]/[L]` badge；缺資料寫 `_TODO: 需要 XXX_` 不編造 hex 值或 props；a11y 對比 ≥ 4.5:1 必填。

---

## 1. Executive Summary

<!-- ai-fill: 3-5 行：token 範圍、核心元件數、命名風格選擇、最強 evidence 來源 -->

<3-5 行說明>

> **TL;DR:** <一句話：本 design-system 收斂哪些視覺決策>

---

## 2. Design Tokens

<!-- ai-rule: 4 類必填（color / spacing / typography / radius）；shadow / motion 可選。Color 必須分 primitive 與 semantic 兩層 -->

### Color

| Layer | Token | Value | Confidence |
|---|---|---|---|
| Primitive | `blue-500` | `#2563EB` | **[H]** |
| Primitive | `gray-100` | `#F5F5F5` | **[H]** |
| Semantic | `bg-action-primary` | → `blue-500` | **[H]** |
| Semantic | `bg-surface` | → `gray-100` | **[M]** |

### Spacing

- **Base:** 8-point grid
- **Scale:** `space-1`(4) / `space-2`(8) / `space-3`(12) / `space-4`(16) / `space-6`(24) / `space-8`(32)

### Typography

| Token | Family | Size | Line-height | Weight |
|---|---|---|---|---|
| `text-body` | Inter | 16 | 24 | 400 |
| `text-h2` | Inter | 24 | 32 | 600 |

### Radius

- `radius-sm`: 4px / `radius-md`: 8px / `radius-lg`: 16px

---

## 3. Core Components（5-10 個）

<!-- ai-rule: 每元件 4 維度描述（anatomy / variants / states / props）；states 至少 5 種 -->

### Button

- **Anatomy:** container · label · icon_left · icon_right
- **Variants:** primary · secondary · ghost · destructive
- **States:** default · hover · focus · active · disabled · loading
- **Props:** `size` / `variant` / `disabled` / `loading` / `icon`
- **A11y:** `role="button"` + keyboard `Enter` / `Space`
- **Confidence:** **[H]** — **Source:** mockup §3

### Input · Card · Modal · ...

---

## 6. A11y Baseline

<!-- ai-rule: 4 項必填（對比 / focus / 不只用色 / 暗色模式）；不適用須寫 rationale -->

| Dimension | Target | Rationale | Confidence |
|---|---|---|---|
| **Contrast (text)** | ≥ 4.5:1 | WCAG 2.2 AA | **[H]** |
| **Focus visible** | required | 鍵盤 a11y | **[H]** |
| **Color not sole indicator** | 用 icon / 文案輔助 | <為何> | **[H]** |
| **Dark mode** | not in v1 | <延後 V2> | **[M]** |

---

## 10. Decision Log（key 2-3 條）

<!-- ai-rule: 每條必含 chosen + 至少 1 個 rejected + 拒絕原因 -->

| Date | Decision | Options | Chosen | Rejected why | Confidence |
|---|---|---|---|---|---|
| YYYY-MM-DD | Token 命名風格 | semantic / literal / hybrid | hybrid | semantic (學習成本高)、literal (難 theming) | **[H]** |

---

## 12. Confidence & Sources & TODO

- **整份文件最低 confidence 欄位：** <列出所有 [L] 與 [M]>
- **Fabricated assumptions：**
  - <例：假設不支援暗色模式 V1>
- **Highest-value next input:** <例：Brand spec 終版 / FE 元件庫對齊>

### TODO（缺資料）

- _TODO: 需要 Brand 確認 logo 使用規範_

---

> [!CAUTION]
> **輸出前 AI 自檢：**
> - [ ] 6 段 H2 章節齊全（編號 1, 2, 3, 6, 10, 12）
> - [ ] Tokens 至少 4 類（color / spacing / typography / radius）
> - [ ] Color 表分 primitive + semantic 兩層
> - [ ] 元件 ≥ 5 個，每個 4 維度（anatomy / variants / states / props）
> - [ ] States ≥ 5 種（含 disabled / loading）
> - [ ] A11y 對比 ≥ 4.5:1 已標 H
> - [ ] Decision Log ≥ 1 條，每條有 rejected reason
> - [ ] 無 YAML / JSON schema 輸出（design-system 是給人讀的 markdown）