# DESIGN.md — CLI Anything 網站設計規格

> 本文件根據 https://clianything.org/zh 實機抓取的 CSS token 與 DOM 結構彙整而成，可直接作為複刻、二次開發或延伸設計的依據。

---

## 1. 設計定位（Design Principle）

| 項目 | 說明 |
|------|------|
| 產品類型 | 開發者工具 / 開源 Claude Code 插件 |
| 目標受眾 | AI 代理開發者、工具鏈工程師、關注自動化的工程文化社群 |
| 設計關鍵字 | **極簡、克制、技術感、綠色科技、文件驅動、清透** |
| 視覺基調 | **亮面現代極簡 + 終端機感的等寬字節奏**。不走炫技路線，以排版、留白、節制色彩呈現工程可信度 |
| 品牌人格 | 技術專業、務實、自信（強調「100% 測試通過」「2k+ Stars」），但語氣對開發者友善 |

---

## 2. 色彩系統（Color Tokens）

採用 Tailwind CSS v4 的 CSS Variables 架構，支援 Light / Dark 雙主題。**預設為淺色主題**。

### 2.1 Light Theme（主）

| Token | HEX | 用途 |
|-------|-----|------|
| `--background` | `#fcfcfc` | 全站底色（近白但非純白，降低刺眼感） |
| `--foreground` | `#171717` | 主要文字 |
| `--card` | `#fcfcfc` | 卡片底（與背景同色，靠 border 區隔） |
| `--primary` | `#00bb7f` | **品牌主色**（翡翠綠 / emerald），用於 CTA、強調、圖示 |
| `--secondary` | `#fdfdfd` | 次級區塊底 |
| `--muted` | `#ededed` | 柔和背景（如 code inline、tag） |
| `--muted-foreground` | `#202020` | 柔和文字 |
| `--accent` | `#ededed` | 互動 hover 背景 |
| `--border` | `#dfdfdf` | 分隔線、卡片描邊 |
| `--ring` | `#72e3ad` | focus ring（主色淡化版） |

### 2.2 Dark Theme

| Token | HEX |
|-------|-----|
| `--background` | `#121212` |
| `--foreground` | `#e2e8f0` |
| `--card` | `#171717` |
| `--primary` | `#007956`（深一階的翡翠綠） |
| `--secondary` | `#242424` |
| `--muted` | `#1f1f1f` |
| `--muted-foreground` | `#a2a2a2` |
| `--accent` | `#313131` |
| `--border` | `#292929` |
| `--ring` | `#4ade80` |

### 2.3 功能色（狀態/語意）

沿用 Tailwind 官方色票：
- 成功：`green-500 #00c758` / `green-600 #00a544`
- 警告：`amber-400 #fcbb00` / `yellow-400 #fac800`
- 危險：`red-500 #fb2c36`
- 紫（徽章）：`purple-400 #c07eff`
- 中性：`zinc-500 #71717b` / `neutral-500 #737373`

### 2.4 配色原則
1. **主色只做一件事**：`#00bb7f` 僅用於 CTA、LOGO、關鍵圖示、連結 hover、進度點；不做大面積填充。
2. **卡片與底色同色**：`card` 與 `background` 都是 `#fcfcfc`，利用 `border: 1px solid #dfdfdf` 劃分層級，形成「平面分區」質感。
3. **文字以中性灰階為主**：`#171717` 主體、`#525252`（neutral-600）次級說明、`#a1a1a1`（neutral-400）輔助。

---

## 3. 字體系統（Typography）

### 3.1 字體家族

```css
--font-sans:  "Space Grotesk", system-ui, sans-serif;   /* 標題與 UI */
--font-serif: "Merriweather", Georgia, serif;           /* 少量引用、強調段落 */
--font-mono:  "JetBrains Mono", "Fira Code", monospace; /* 程式碼、指令、技術詞 */
```

選用邏輯：
- **Space Grotesk**：幾何人文無襯線，字腔開闊、帶一點工程感，適合技術品牌標題。
- **Merriweather**：作為對比的 serif，偶爾用於強調「宣言式」文案。
- **JetBrains Mono**：開發者社群熟悉的等寬字，強化「命令列」品牌語言。

### 3.2 字級階層

| Token | Size / Line-height | 使用場景 |
|-------|--------------------|----------|
| `text-7xl` | 72 / 1.0 | Hero 主標題（桌機） |
| `text-5xl` | 48 / 1.0 | Section 大標 |
| `text-4xl` | 36 / 1.11 | Section 次級標 |
| `text-3xl` | 30 / 1.2 | 卡片內標題 |
| `text-xl`  | 20 / 1.4 | Hero 副標、引言 |
| `text-base`| 16 / 1.5 | 正文 |
| `text-sm`  | 14 / 1.43 | 註解、metadata |
| `text-xs`  | 12 / 1.33 | 徽章、footer |

字重：`400 / 500 / 600 / 700`，Hero 標題使用 `700`，一般段落 `400`，小標 `600`。

---

## 4. 間距、圓角、陰影

| Token | 值 | 用途 |
|-------|----|------|
| `--spacing` | `0.25rem (4px)` | 基礎單位（全站 4 的倍數） |
| `--radius-xs` | `2px` | inline code、小標籤 |
| `--radius-2xl` | `16px` | **按鈕、卡片預設** |
| `--radius-3xl` | `24px` | Hero 容器、大型區塊 |
| `--radius-4xl` | `32px` | 特殊浮動區塊 |
| `--shadow-sm` | 輕陰影 | 卡片靜態 |
| `--shadow-lg` | 中陰影 | hover 懸浮 |
| 過渡 | `cubic-bezier(.4, 0, .2, 1) 150ms` | 全站統一 ease-in-out |

**容器寬度**：最大 `--container-6xl: 72rem (1152px)` 為內容主幅寬。

---

## 5. 頁面結構與區塊（Layout）

```
┌─────────────────────────────────────────────┐
│  Header (sticky, 64px)                       │
├─────────────────────────────────────────────┤
│                                             │
│  Hero  — 大標 + 副標 + 雙 CTA + 徽章列         │
│                                             │
├─────────────────────────────────────────────┤
│  為什麼選擇 CLI  — 4 欄優勢卡片                │
├─────────────────────────────────────────────┤
│  5 分鐘上手  — 4 步驟編號卡                   │
├─────────────────────────────────────────────┤
│  應用覆蓋  — 6 類別卡片網格                    │
├─────────────────────────────────────────────┤
│  核心特性  — 7 階段流水線（水平時間軸）          │
├─────────────────────────────────────────────┤
│  FAQ  — Accordion 折疊問答                   │
├─────────────────────────────────────────────┤
│  Footer  — 4 欄連結 + 版權                   │
└─────────────────────────────────────────────┘
```

### 5.1 Header
- 高度 `64px`，`position: sticky; top: 0;`、背景半透明 + `backdrop-filter: blur(8px)`。
- 左：Logo（PNG，約 32px 高） + 品牌字「CLI Anything」。
- 右：`功能特性`、`在 GitHub 查看`（後者為 `primary` 填色按鈕）。
- 底部 `border-bottom: 1px solid #dfdfdf`。

### 5.2 Hero
- 垂直置中、上下 padding ≈ `96px`。
- 主標題：`text-7xl / 700 / tracking-tight`，行距 1.0，最多兩行。
- 副標題：`text-xl / 400 / neutral-600`，最大寬度 `42rem` 置中。
- 徽章列：`⭐ GitHub 2k+ Stars · 1,436 個測試全部通過 · 開源免費` — 使用 `text-sm`、灰階、中點分隔。
- 雙 CTA：
  - 主：`立即開始`（`bg-primary #00bb7f`、白字、`rounded-2xl`、`px-6 py-3`）。
  - 次：`在 GitHub 查看`（`outline` 風、透明底、border-neutral）。

### 5.3 Feature Grid（為什麼選擇 CLI）
- 4 欄（桌機）/ 2 欄（平板）/ 1 欄（手機）。
- 卡片：`bg-card`、`border`、`rounded-2xl`、內距 `24px`。
- 結構：頂部小圖示（`primary` 色，24px）+ 標題 + 描述。

### 5.4 快速上手步驟
- 水平排列的編號卡（1→2→3→4），每張卡含：
  - 大型編號（`text-5xl` + `primary` 色 + `font-mono`）。
  - 步驟標題。
  - 終端指令（背景 `#ededed`、`JetBrains Mono`、`rounded-xs`、內距 `8px 12px`）。

### 5.5 應用覆蓋（Apps Grid）
- 6 格卡片排版，每格一大類，內含 chip tag 列示支援的軟體名稱。
- Tag 樣式：`bg-muted`、`text-xs`、`rounded-xs`、`px-2 py-0.5`。

### 5.6 7 階段流水線
- 水平時間軸，7 個節點以 `primary` 圓點 + 連線呈現。
- 桌機水平、手機垂直折疊。

### 5.7 FAQ
- Accordion 組件，`border-bottom` 逐列劃分，點擊展開平滑過渡（150ms）。
- 問題使用 `font-semibold`，展開內容使用 `muted-foreground`。

### 5.8 Footer
- 4 欄：品牌敘述 / 導航 / 資源 / 法律。
- 背景同 `background`，頂部 `border-top`。
- 版權置中，`text-sm / neutral-500`。

---

## 6. 組件樣式規範（Components）

### 6.1 Button

```
/* Primary */
background: #00bb7f;
color: #fff;
padding: 12px 24px;
border-radius: 16px;
font-weight: 600;
transition: transform 150ms, box-shadow 150ms;
hover { transform: translateY(-1px); box-shadow: var(--shadow-lg); }

/* Secondary */
background: transparent;
color: #171717;
border: 1px solid #dfdfdf;
hover { background: #ededed; }

/* Ghost (Header link) */
padding: 8px 12px;
hover { color: #00bb7f; }
```

### 6.2 Card

```
background: #fcfcfc;
border: 1px solid #dfdfdf;
border-radius: 16px;
padding: 24px;
/* 無預設陰影，hover 才浮起 */
hover { box-shadow: var(--shadow-lg); border-color: #00bb7f33; }
```

### 6.3 Badge / Tag

```
background: #ededed;
color: #202020;
font-size: 12px;
padding: 2px 8px;
border-radius: 2px;
font-family: var(--font-mono);
```

### 6.4 Inline Code / Command

```
font-family: "JetBrains Mono";
background: #ededed;
color: #171717;
padding: 2px 6px;
border-radius: 4px;
font-size: 0.875em;
```

---

## 7. 互動與動態（Motion）

| 項目 | 規格 |
|------|------|
| 預設過渡 | `150ms cubic-bezier(.4, 0, .2, 1)` |
| 按鈕 hover | `translateY(-1px)` + shadow-lg |
| 卡片 hover | border-color 轉成 primary（帶透明度）+ shadow-lg |
| Accordion | `max-height` / `opacity` 同時過渡 200ms |
| Scroll 進入 | 建議使用 `fade-up`（opacity 0→1, translateY 8px→0, 400ms） |
| 載入動畫 | `--animate-spin: spin 1s linear infinite` 供載入指示器使用 |

**原則**：不使用視差、粒子、3D 等重特效。動態只為回饋與引導視線，不喧賓奪主。

---

## 8. 圖示與圖片

- **Logo**：PNG 去背，單色可轉白（Footer）或原色（Header）。
- **圖示**：線性風格，`stroke-width: 1.5`，顏色 `#00bb7f` 或 `#171717`，尺寸 `24px`。
- **Hero 背景**：可選擇純色（預設）或加入極淡的 grid pattern / noise texture（opacity ≤ 5%）增加質感，避免放大型照片打破極簡感。

---

## 9. 響應式斷點（Breakpoints）

沿用 Tailwind 預設：

| 斷點 | 寬度 | 典型佈局變化 |
|------|------|---------------|
| `sm` | 640px | 單欄→雙欄起點 |
| `md` | 768px | 2 欄網格 |
| `lg` | 1024px | 4 欄 feature 網格 |
| `xl` | 1280px | 完整桌機版（7xl 大標） |
| `2xl`| 1536px | 容器置中、不再放大 |

手機版 Hero 主標降為 `text-4xl`，padding 壓縮至 `48px`。

---

## 10. 語氣與文案風格（Voice & Tone）

- **務實、技術、自信**：以數字佐證主張（1,436、2k+、100%）。
- **動詞開場**：「讓」、「告別」、「轉化」、「發現」。
- **開發者密語**：允許出現 `--json`、`--help`、`/plugin install` 等技術詞彙，不做科普式解釋，相信讀者能看懂。
- **避免行銷套話**：不使用「革命性」、「顛覆」、「一站式」等空泛形容詞。

---

## 11. 可及性（Accessibility）

- 正文對比率 `#171717` on `#fcfcfc` ≈ 16:1，超過 WCAG AAA。
- CTA `#fff` on `#00bb7f` 對比 ≈ 3.1:1，符合 AA Large。建議小字按鈕可加粗字重或增加 border。
- 所有互動元素必須具備 `focus-visible` ring（使用 `--ring: #72e3ad`，`outline: 2px solid`、`outline-offset: 2px`）。
- Accordion 使用語意化 `<details>` 或具 `aria-expanded` 的按鈕。
- 所有 icon-only button 附 `aria-label`。

---

## 12. 技術棧（參考）

| 層 | 技術 |
|----|------|
| 框架 | Next.js（App Router，依 `/_next/static/chunks` 推斷） |
| 樣式 | Tailwind CSS v4（CSS Variables + `@layer theme`） |
| 字體載入 | `next/font` 本地自管（Space Grotesk / Merriweather / JetBrains Mono） |
| 主題 | CSS 變數切換（Light / Dark，可能由 `class="dark"` 控制） |
| 部署 | 靜態化 Next.js |

---

## 13. 複刻檢核表（Checklist）

撰寫實作時可逐項對照：

- [ ] 背景色用 `#fcfcfc` 而非 `#ffffff`
- [ ] 主色只用於 CTA / Logo / 強調點，不大面積填充
- [ ] 卡片靠 `1px border` 劃界，而非陰影
- [ ] 標題使用 Space Grotesk、指令一律 JetBrains Mono
- [ ] 按鈕圓角 `16px (rounded-2xl)`
- [ ] Hover 有輕微上浮 + 陰影
- [ ] 所有過渡 150ms ease-in-out
- [ ] 容器最寬 `1152px` 置中
- [ ] 數字指標以 mono + 中點分隔列於 Hero 下方
- [ ] Footer 含 4 欄、版權置中
- [ ] 支援 Light / Dark 主題切換
- [ ] 所有互動元素可見 focus ring

---

_以上規格為觀察 clianything.org/zh 正式站點之設計萃取，可作為同風格專案的設計基礎；實際實作時若取得原始設計稿，以設計稿為準。_
