# Design System: Paper 紙感極簡

> 為 AI 生成介面設計的極簡系統：留白優先、清晰排版、克制且有紀律的語意色彩，準確性與無障礙優先於視覺花招。
> Direction from TypeUI's Paper design skill（typeui.sh）；本實作與配色細節為原創撰寫。

---

## 1. Visual Theme & Atmosphere

**Design Philosophy:** Paper 把介面當作一張排版精確的白紙——資訊本身就是設計。系統拒絕裝飾性陰影、漸層、玻璃擬態，把預算全部花在間距節奏、字重對比、與「使用者永遠知道焦點在哪」這三件事上。當美觀與可用性衝突時，可用性永遠贏。

**Atmosphere Keywords:** Minimal, Disciplined, Legible, Accessible-first, Opinionated, Quiet, Structural, Keyboard-first

**Visual Anchors:**
- 純白畫布（`#FFFFFF`）+ 1px 細邊框——不用陰影堆疊層次
- 單一近黑主色（`#111111`）扛起所有強調與標題
- 一抹紫色點綴（`#8B5CF6`）標示互動與連結，其餘畫面保持中性
- 永遠可見的 2px focus-visible 外框——鍵盤操作者永遠看得見焦點
- 4px 為基準的間距刻度，貫穿所有 padding / gap
- 小圓角（6–10px）——有溫度但不圓潤到失去結構感

**Mood Board References:**
- 瑞士排版網格系統
- WCAG 2.2 AA 無障礙規範文件本身的排版
- 開發者工具（VS Code、終端機）的功能性美學
- 紙本文件排版（頁邊界、標題階層、正文行距）

---

## 2. Color Palette & Roles

| Swatch | 中文名 | English Name | Hex | Role |
|--------|--------|--------------|-----|------|
| ⬛ | 極夜黑 | Primary | `#111111` | 主要互動元件、標題、強調文字 |
| 🟣 | 紫羅蘭 | Secondary | `#8B5CF6` | 強調點綴、連結、次要操作、focus ring |
| 🟢 | 確認綠 | Success | `#16A34A` | 正向回饋、確認訊息 |
| 🟠 | 警戒橙 | Warning | `#D97706` | 警示指標 |
| 🔴 | 危險紅 | Danger | `#DC2626` | 錯誤狀態、破壞性操作 |
| ⬜ | 紙白 | Surface | `#FFFFFF` | 背景、卡片表面 |
| ⚫ | 墨灰 | Text | `#111827` | 正文文字 |

**Rule:** 核心 7 色不擴充語意集合——需要更多層次時用 Primary/Text 的透明度變化（如 `rgba(17,17,17,0.08)` 做邊框、`rgba(17,17,17,0.5)` 做次要文字），不新增色相。

---

## 3. Typography Rules

### Font Stack

| Token | Font | Use |
|-------|------|-----|
| `--font-heading` | Montserrat | 標題、Hero、Display 文字 |
| `--font-body` | Roboto | 正文、標籤、一般 UI 文字 |
| `--font-mono` | PT Mono | 程式碼、技術性內容 |

三者皆來自 Google Fonts，載入 `wght` 範圍涵蓋 100（thin）到 900（black），供標題視需要拉開字重對比。

### Type Scale

| Level | Size | Typical Use |
|-------|------|-------------|
| xs | 14px | caption、輔助文字 |
| sm | 16px | body 正文（基準） |
| md | 18px | lead paragraph、卡片標題 |
| lg | 24px | h3、section 小標 |
| xl | 32px | h2 |
| 2xl | 40px | h1、hero 標題 |

### Weight Range

系統刻意展示完整字重光譜：**100（thin）→ 300（light）→ 400（regular）→ 500（medium）→ 700（bold）→ 900（black）**。標題慣用 700–900 建立清楚階層，正文固定 400，次要標籤可用 500 做輕度強調——避免中間字重（600）造成模糊層次。

---

## 4. Component Stylings

### Buttons

- Primary：`#111111` 底、白字、`border-radius: 8px`，無陰影
- Secondary：透明底 + 1px `#111111` 邊框
- Disabled：`opacity: 0.4` + `cursor: not-allowed`，不使用灰底掩蓋文字對比
- **每個互動元件必須有顯式的 5 態**：default / hover / focus-visible / active / disabled——這是系統的核心紀律，見第 9 節簽名元件。

### Inputs

- 1px `#111827` 20% 透明邊框，`border-radius: 8px`，padding 依 8/16 刻度
- Focus：邊框轉 Secondary 紫 + 2px offset outline，不只是邊框變色（單靠顏色對色盲使用者不可見）

### Cards

- 白底 + 1px 邊框（`rgba(17,17,17,0.1)`），`border-radius: 10px`
- 最多疊加一層極輕陰影（`0 1px 2px rgba(0,0,0,0.04)`）作為表面分離提示，不做 hover 抬升動畫堆疊

### Focus States（系統最重要的組件規則）

`:focus-visible` 一律套用 **2px solid Secondary（或關鍵操作用 Primary）+ 2px offset**，鍵盤 Tab 巡覽時外框必須可見，不得用 `outline: none` 移除卻不提供替代方案。

---

## 5. Layout Principles

- **間距基準單位 4px**，刻度為 `4 / 8 / 12 / 16 / 24 / 32px`——所有 padding、gap、margin 只從這個刻度取值，不自由發揮
- **容器寬度**：內容區 max-width 1120px，窄版文字區塊（如正文段落）max-width 720px 維持行長可讀性
- **網格**：卡片牆用 `repeat(auto-fit, minmax(240px, 1fr))`，gap 固定 24px（刻度中段值）
- **垂直節奏**：section 間距 32px，段落內元素間距 16px 或 8px，不混用刻度外的數值
- **對齊**：一律靠左對齊為主，避免置中大段文字造成掃視困難

---

## 6. Depth & Elevation

Paper 的深度語言是**「扁平 + 焦點環」**，而不是陰影分層：

1. 表面之間只靠 1px 邊框分隔，不用陰影模擬「浮起」
2. 唯一允許的陰影是極輕的表面提示（見第 4 節 Cards），絕不使用多層模糊陰影堆疊出擬物質感
3. 真正的「深度」訊號來自互動狀態本身——focus-visible 的 2px 外框、active 的輕微位移——不是視覺深度，是狀態深度
4. 與 shadow-heavy 系統（如 Material Design 的 elevation 階梯）相反：Paper 假設使用者靠讀取結構理解層次，不是靠陰影猜測

---

## 7. Do's and Don'ts

### Do's

- 用 1px 細邊框劃分區塊，取代陰影
- 每個互動元件明確設計 5 態並各自可辨識
- 標題用 Montserrat 重字重（700+）製造對比，正文維持 Roboto 400
- 色彩使用克制——語意色只在真正語意場合出現（成功/警告/危險）
- focus-visible 永遠可見，不因為「畫面比較乾淨」而移除

### Don'ts

- 不用模糊陰影堆疊層次（`box-shadow` 多層漸變）
- 不用漸層背景或玻璃擬態
- 不把 Secondary 紫色當作大面積背景——它是點綴色不是主色
- 不用 `outline: none` 移除焦點外框而不提供替代方案
- 不混用刻度外的間距數值（如 `13px`、`22px`）
- 不用純黑 `#000000`——文字色固定 `#111827`

---

## 8. Responsive Behavior

| Breakpoint | Behavior |
|-----------|----------|
| ≥1120px | 完整多欄網格，容器 max-width 1120px |
| 641–1119px | 卡片牆降為 2 欄，間距刻度不變 |
| ≤640px | 單欄堆疊、hero 字級降階（40px→32px）、按鈕列直排、表格改為橫向捲動 |

---

## 9. Agent Prompt Guide

```
Build the interface in the "Paper" minimal design system:

- Palette (use exactly): Primary #111111, Secondary (violet accent) #8B5CF6,
  Success #16A34A, Warning #D97706, Danger #DC2626,
  Surface #FFFFFF, Text #111827
- Fonts: 'Montserrat' for headings/hero/display (weights 700-900),
  'Roboto' for body/labels/UI (weight 400, 500 for light emphasis),
  'PT Mono' for code/technical content. All via Google Fonts.
- Type scale: 14 / 16 / 18 / 24 / 32 / 40px
- Spacing: strict 4px base unit, scale = 4 / 8 / 12 / 16 / 24 / 32px —
  every padding/margin/gap must come from this scale
- Surfaces: flat white cards, 1px thin borders (rgba(17,17,17,0.1)),
  border-radius 6-10px, at most one very subtle shadow
  (0 1px 2px rgba(0,0,0,0.04)) — never stacked/blurry shadows
- Every interactive element needs 5 explicit states: default, hover,
  focus-visible, active, disabled
- focus-visible MUST always be visible: 2px solid outline in Secondary
  (#8B5CF6) or Primary (#111111), 2px offset — never outline:none
  without a replacement
- No gradients, no glassmorphism, no heavy drop shadows
- Layout: max-width 1120px container, left-aligned text,
  auto-fit card grids with minmax(240px, 1fr), 24px gaps
- Accessibility (WCAG 2.2 AA) wins over novelty whenever they conflict
```

---

*Direction extracted from TypeUI's Paper design skill (typeui.sh). Implementation and palette details are original.*