diff --git a/docs/color-token-convention.md b/docs/color-token-convention.md new file mode 100644 index 0000000..b40622d --- /dev/null +++ b/docs/color-token-convention.md @@ -0,0 +1,135 @@ +# CSS Color Token 命名規範 + +> 適用於任何前端專案。把自己的色值填進 `:root`,命名規則照用。 + +--- + +## 命名格式 + +``` +--color-[類別]-[修飾詞] +``` + +| 位置 | 說明 | +|---|---| +| `--color-` | 固定前綴,所有顏色 token 統一掛這個 | +| `[類別]` | 語意分類:`brand` / `bg` / `surface` / `text` | +| `[修飾詞]` | 可選,描述深淺或用途變體 | + +--- + +## 四個類別 + +### `brand` — 品牌色 +專案主色及其深淺變體。 + +```css +--color-brand /* 主色,最常用 */ +--color-brand-light /* 淡化版,用於 hover 背景、標籤底色 */ +--color-brand-dark /* 加深版,用於文字、引言、邊框 */ +``` + +### `bg` — 背景色 +頁面層級的大面積背景,通常是深色或中性色。 + +```css +--color-bg /* 最底層,全站頁面底色 */ +--color-bg-raised /* 稍淺一層,導覽列、頁尾、深色卡片 */ +--color-bg-alt /* 備用,與主底色形成微弱對比 */ +``` + +### `surface` — 表面色 +內容區塊的淺色底,通常是接近白色的暖/冷調。 + +```css +--color-surface /* 標準內容區底色 */ +--color-surface-soft /* 更溫和的變體,卡片、引言框 */ +``` + +### `text` — 文字色 + +```css +--color-text /* 一般內文 */ +--color-text-dark /* 強調、標題 */ +--color-text-muted /* 次要說明、標籤 */ +--color-text-inverse /* 用於深色背景上的淺色文字 */ +``` + +--- + +## :root 模板 + +直接複製,把 hex 換成你的品牌色: + +```css +:root { + /* Brand */ + --color-brand: ; + --color-brand-light: ; + --color-brand-dark: ; + + /* Background */ + --color-bg: ; + --color-bg-raised: ; + --color-bg-alt: ; + + /* Surface */ + --color-surface: ; + --color-surface-soft: ; + + /* Text */ + --color-text: ; + --color-text-dark: ; + --color-text-muted: ; + --color-text-inverse: ; +} +``` + +--- + +## 使用規則 + +**必須用 token,禁止硬寫 hex:** + +```css +/* ✅ */ +background: var(--color-brand); +color: var(--color-text-muted); + +/* ❌ */ +background: #ffcc00; +color: #4d4d4d; +``` + +**例外:`rgba()` 透明度** + +CSS 變數無法直接放進 `rgba()` 的色版參數,此情況允許保留 hex: + +```css +/* ✅ 允許 */ +border: 1px solid rgba(255, 204, 0, 0.28); +box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1); +``` + +**頁面 scope token** + +單一頁面或元件專用的顏色,用有意義的前綴隔離,不納入全站 `:root`: + +```css +/* 只在該頁面的 + + +
+