coastdigitalgroup/coastai-skills

深色主題設計系統

目的

「深色主題設計系統」技能提供了一套將淺色網路介面轉換為深色對應版本的方法論。設計深色模式並非單純反轉色彩值這麼簡單。這樣做會破壞物理照明隱喻、造成嚴重的視覺疲勞，並產生難以辨識且眩光嚴重的介面。

此系統建立了低光源設計的視覺與空間規則：

• 高度反轉 (Elevation Reversal)： 在深色模式下，透過提亮浮動層級的表面背景來傳達深度，而非使用深色陰影。
• 色彩去飽和度 (Color Desaturation)： 將鮮豔的品牌與語意強調色調整至低對比程度，以防止視覺「震動」與眼睛疲勞。
• 對比度與光暈預防 (Contrast & Halation Prevention)： 避免純白配純黑的組合，因為這會對散光或閱讀障礙者造成極端的發光效應（光暈），應改用米白與深灰。
• 字重校準 (Typographic Weight Calibration)： 抵消「照射效應」（即淺色文字在深色背景上比深色文字在淺色背景上看起來更粗更重的視覺錯覺）。
• 媒體調暗 (Media Dimming)： 調整圖片、影片與向量圖示，使其在低光源條件下不會讓使用者感到「刺眼」。

---

使用案例

• 設計雙主題 UI 套件： 建立一個原生支援淺色與深色模式的系統化語意設計標記架構。
• 重新設計 SaaS 儀表板與閱讀環境： 建立專為長時間觀看、開發者工作流程或夜間使用而最佳化的低疲勞介面。
• 審計無法存取的深色主題： 識別並修復對比度問題、震動的強調色、難以辨識的文字級距以及刺眼的媒體素材。
• 提供多主題交接規格： 產出清晰、開發人員可讀的規格，準確顯示元素在不同主題下的行為。

---

何時不應使用

• 預設深色（電影式）環境： 如果應用程式是專屬深色模式（例如 Spotify、Netflix 或遊戲串流平台），且永遠不會支援淺色主題。在這種情況下，雙主題設計系統是額外且不必要的負擔。
• 高度表現性 / 藝術性的微活動頁面： 獨立的登陸頁面，其視覺顛覆性、極高飽和度調色盤或藝術品牌形象凌駕於長時間觀看的舒適度或嚴格的無障礙規則之上。
• 嚴格靜態的舊有框架： 前端架構無法載入動態樣式表或缺乏 CSS 變數支援的應用程式，導致無法進行系統性主題適配。

---

輸入

1. 淺色模式核心調色盤與品牌風格： 現有的主要品牌色彩、次要顏色、字級比例與流暢間距標記。
2. 元件清單與深度層級架構： 頁面佈局與 UI 圖層（背景、側邊欄、卡片、模態視窗、下拉選單）的完整清單。
3. 照明環境脈絡： 目標使用者的典型物理環境（例如，夜間睡前閱讀 vs. 明亮照明的工業控制室）。
4. 無障礙目標： 標準 WCAG 2.2 AA（最低）或 AAA（增強），包括對散光與色盲的考量。

---

輸出

1. 統一語意標記映射表： 將淺色模式值直接對應到其深色模式對應值的系統化規格。
2. 基於高度的表面層級： 一個 5 到 6 階的層級定義，說明表面背景值在 Z 軸上層級越高時如何變亮。
3. 去飽和強調色調色盤： 一組為深色背景校準過的去飽和主要、次要與語意狀態色彩。
4. 文字級距樣式表修正： 針對字重、字距與文字色彩調整的特定規則，以抵消照射效應。
5. 媒體調暗規格： 用於降低圖片對比度/亮度以及調整向量圖形的 CSS 和 HTML 技術。

---

工作流程

1. 設定基礎：選擇非純黑與非純白

避免對背景使用絕對的 #000000（純黑色），以及對內文使用絕對的 #FFFFFF（純白色）。

• 基礎背景： 建立一個深色、帶有調色的中性色（例如深板岩色、木炭色或深海軍灰，範圍在 #121212 到 #1A1A1A 之間）。這能減少眼睛疲勞、防止螢幕閃爍，並保留一些視覺深度。
• 文字基礎： 選擇米白或淺灰色（例如 #E2E8F0 或帶有 85% 到 90% 不透明度的 #EAEAEA）。這能確保舒適的對比度，而不會引起光暈效應（光線在閱讀者眼中散射）。

2. 透過高度提亮來轉譯深度

在淺色主題中，我們透過投射較暗的陰影來表示元素被提升。在深色主題中，深色陰影在深色背景上是看不見的。

• 提亮原則： 當元素在 Z 軸上層級越高時，它會更接近虛擬環境光源，因此會變得更亮，而不是更暗。
• 建立高度表面層級：
  • 層級 0（畫布基底）： 最暗的顏色（例如 #121212）。
  • 層級 1（卡片/列表項目）： 稍微亮一點（例如 #1D1D1D）。
  • 層級 2（固定頁首/浮動動作）： 再亮一點（例如 #242424）。
  • 層級 3（模態視窗/對話框）： 最亮的表面（例如 #2C2C2C）。
• 使用柔和陰影輔助： 在浮動圖層上使用非常微妙的深灰色或半透明黑色陰影（例如 rgba(0, 0, 0, 0.5)），為位於層級 1 項目之上的較大表面提供分離感。

3. 校準並去飽和強調色

在白色畫布上看起來鮮豔的高飽和度色彩，在深色畫布上會「震動」，造成嚴重的視覺疲勞並且無法通過對比度測試。

• 去飽和品牌強調色： 將品牌色彩轉換為更淺、更柔和、更像粉彩的等效色。（例如，在淺色背景上鮮豔的主要藍色 #0055FF 應映射到深色背景上飽和度較低的藍色 #66A3FF 或 #80B3FF）。
• 維持安全的對比度強調色： 驗證深色表面上的去飽和強調色是否仍符合 WCAG 2.2 AA 標準（文字最低 4.5:1，互動狀態 3:1）。
• 避免大面積飽和色塊： 不要將整個按鈕或橫幅渲染成純飽和色，應節制使用，例如用於文字連結、邊框或微妙的指示器。

4. 針對光學照射調整排版

深色背景上的淺色文字會受到照射效應的影響——白色文字似乎會「滲入」周圍的黑暗，使字母看起來比它們在淺色背景上的對應版本更粗、更厚、更緊密。

• 字重校準： 將淺色主題中的粗體標題字重降低一級（例如，在深色模式下將 700（粗體）改為 600（半粗體）甚至 500（中粗體））。
• 字距校準： 稍微增加深色模式內文的字距（例如 letter-spacing: 0.02em; 或 0.015em;），以防止各個字母相互滲透。
• 次要/第三層級層級： 透過調整文字色彩的不透明度來控制層級，而不僅僅是大小。對高優先級內文使用 opacity: 0.87，對次要輔助文字使用 opacity: 0.60，對禁用指示器使用 opacity: 0.38。

5. 適配媒體與豐富內容

未經修改的照片、圖表和圖示可能會破壞原本完美的深色模式體驗，因為它們會用明亮、高對比的白色區域刺傷使用者的眼睛。

• 照片調暗： 對照片套用微妙的亮度和對比度降低，使其融入低光源氛圍中。

  [data-theme="dark"] img:not(.avatar) {
    filter: brightness(0.85) contrast(0.95);
  }
  

• 向量素材與插圖： 交換 SVG 中的亮色背景，或使用 SVG 濾鏡反轉特定路徑。對於插圖圖形，使用帶有媒體查詢的 <picture> 元素來載入自訂的深色主題素材。
• 資料視覺化： 重新定義圖表色彩系列，使用去飽和線條和半透明區域填滿，使其在不產生過度亮度的情況下保持可讀性。

---

決策規則

高度亮度規則

在建立視覺容器的背景時，請參閱其高度層級。絕不要讓浮動的模態視窗或下拉選單的背景比其下方的頁面背景更暗。

高度層級	淺色模式背景	深色模式背景	隱含的高度提示
層級 0（畫布）	#FFFFFF（白色）或 #F8F9FA	#121212（非純黑）	地面層級/基底
層級 1（卡片/區塊）	#FFFFFF（白色）帶邊框	#1E1E1E（表面 1）	浮動 1-2dp
層級 2（頁首/固定）	#FFFFFF 或微妙的半透明色調	#252525（表面 2）	浮動 4-8dp
層級 3（模態/對話框）	#FFFFFF 帶重陰影	#2D2D2D（表面 3）	浮動 12-24dp

飽和度上限

• 用作互動狀態背景（例如次要標籤容器）的強調色，在深色模式下的飽和度應設定在 10% 到 15% 之間。
• 用作前景文字或圖示的強調色，飽和度應設定在 40% 到 60% 之間，以確保它們在深色表面脫穎而出而不會震動。

對比度緩衝

由於螢幕眩光與低品質螢幕對深色模式可見度的損害比淺色模式更為嚴重，因此深色模式內文的對比度應始終力求達到 5.0:1（超出 WCAG 4.5:1 的最低要求），以作為惡劣物理環境的緩衝。

---

限制條件

• 無障礙 (WCAG AA)： 文字元素必須達到至少 4.5:1 的對比度（大文字為 3:1）。UI 邊框、焦點環與功能性圖示必須達到至少 3:1 的對比度。焦點指示器必須保持高度可見，且不被深色背景光暈淹沒（WCAG 2.2 SC 2.4.11）。
• 響應式眩光適配： 文字色彩必須能夠抵抗高環境眩光（例如在戶外使用的行動螢幕），這意味著必須避免絕對的最低對比度水準。
• 不依賴純色彩層級： 不要僅依靠去飽和色彩的色調來傳達狀態（例如圖表中的警告 vs. 錯誤）。應整合不同的圖案、文字標籤或圖示。

---

常見失敗模式

• 「直接反轉器」： 對淺色主題執行自動色彩反轉濾鏡。這會將帶有深色陰影的浮動淺色模式元素，轉變為帶有發光白色環的凹陷深色模式元素，破壞所有自然照明模型。
• 「震動霓虹燈」惡夢： 將完全飽和的品牌色彩（例如 #00FF00 或 #FF00FF）直接放在純黑色背景上。這會引發視覺疲勞，使文字在幾秒鐘內幾乎無法閱讀。
• OLED 極端（純黑發光）： 在 #000000 背景上使用 #FFFFFF 文字。這會在許多顯示器上造成嚴重的光暈/眩光效果，降低閱讀速度並導致眼睛疲勞。
• 消失的焦點環： 設計了漂亮的深色模式，但保留了瀏覽器的預設焦點指示器（通常是深藍色），使其在深色板岩背景上完全看不見。
• 刺眼的插圖： 創造了無縫的深色 UI，但保留了 SVG 圖表、Logo 或插圖圖示內高對比度的純白色背景。

---

驗證標準

• 基礎值： 主要畫布背景未使用絕對的純黑 (#000)，內文未使用絕對的純白 (#FFF)。
• 高度模型： 表面在 Z 軸上層級越高時，顏色會逐漸變亮（更高的亮度值）。
• 對比度檢查： 每種文字顏色，包括暗淡的輔助文字，都達到或超過 WCAG 2.2 AA 對比度標準（一般文字 4.5:1，大文字 3:1）。
• 非震動強調色： 根據應用場景，強調色與狀態色彩的去飽和度範圍在 10% 到 60% 之間，避免視覺震動。
• 焦點可見性： 互動元素具有高對比度、鮮明的焦點指示器，在深色表面上清晰可見。
• 排版校準： 已調整粗體文字（降一級字重或增加字距）以補償照射效應。
• 媒體濾鏡： 指定了響應式機制（CSS 濾鏡或深色素材互換）以降低豐富媒體與向量素材的亮度和對比度。