sechskies/docs/color-token-convention.md

CSS Color Token 命名規範

適用於任何前端專案。把自己的色值填進 :root，命名規則照用。

---

命名格式

--color-[類別]-[修飾詞]

位置	說明
--color-	固定前綴，所有顏色 token 統一掛這個
[類別]	語意分類：brand / bg / surface / text
[修飾詞]	可選，描述深淺或用途變體

---

四個類別

brand — 品牌色

專案主色及其深淺變體。

--color-brand           /* 主色，最常用 */
--color-brand-light     /* 淡化版，用於 hover 背景、標籤底色 */
--color-brand-dark      /* 加深版，用於文字、引言、邊框 */

bg — 背景色

頁面層級的大面積背景，通常是深色或中性色。

--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    /* 用於深色背景上的淺色文字 */

---

:root 模板

直接複製，把 hex 換成你的品牌色：

: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：

/* ✅ */
background: var(--color-brand);
color: var(--color-text-muted);

/* ❌ */
background: #ffcc00;
color: #4d4d4d;

例外：rgba() 透明度

CSS 變數無法直接放進 rgba() 的色版參數，此情況允許保留 hex：

/* ✅ 允許 */
border: 1px solid rgba(255, 204, 0, 0.28);
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);

頁面 scope token

單一頁面或元件專用的顏色，用有意義的前綴隔離，不納入全站 :root：

/* 只在該頁面的 <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