136 lines
3.0 KiB
Markdown
136 lines
3.0 KiB
Markdown
# 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
|
||
/* 只在該頁面的 <style> 或專屬 .css 裡定義 */
|
||
:root {
|
||
--lyrics-bg: #2a2a2a;
|
||
--lyrics-accent: #f5dfa8;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 常見錯誤
|
||
|
||
| 錯誤 | 問題 | 修正 |
|
||
|---|---|---|
|
||
| `--primary` | 語意不明，是文字色？背景色？ | `--color-brand` |
|
||
| `--text-color` 和 `--text-main` 並存 | 重複，造成混亂 | 合併成 `--color-text` |
|
||
| `--black` | 不知道是背景黑還是文字黑 | `--color-bg-raised` 或 `--color-text-dark` |
|
||
| `--gray` | 完全沒有語意 | 依用途改為 `--color-text-muted` 或 `--color-text-inverse` |
|