CSS light-dark() 函數完全指南：原生主題切換不再需要 JavaScript 2026

什麼是 CSS light-dark() 函數？

在 2024 年之前，實現網站的深色/淺色主題切換幾乎都需要依賴 JavaScript —— 動態切換 class、操作 CSS 變數，或是使用第三方套件。CSS light-dark() 函數的出現徹底改變了這個局面。

light-dark() 是 CSS Color Level 5 規範中引入的新函數，讓你可以在 CSS 屬性中直接指定「淺色模式的值」和「深色模式的值」，瀏覽器會根據使用者的系統偏好或 color-scheme 屬性設定自動選擇正確的值。

這是一個真正「以 CSS 為核心」的解決方案，不需要任何 JavaScript 介入，也不需要複雜的 CSS 變數管理架構。

瀏覽器支援狀況

截至 2026 年初，light-dark() 已獲得所有主流瀏覽器的支援：

• Chrome / Edge：119+ 完整支援
• Firefox：120+ 完整支援
• Safari：17.5+ 完整支援

全球瀏覽器支援率已超過 93%，可以放心用於正式專案。如需支援舊版瀏覽器，可以搭配 @supports 做漸進增強。

基本語法與用法

使用 light-dark() 前，你必須先在 :root 或目標元素上設定 color-scheme 屬性：

:root {
  color-scheme: light dark;
}

body {
  background-color: light-dark(#ffffff, #1a1a2e);
  color: light-dark(#333333, #e8e8e8);
}

.card {
  background: light-dark(#f5f5f5, #16213e);
  border: 1px solid light-dark(#e0e0e0, #2d2d44);
  box-shadow: 0 2px 8px light-dark(rgba(0,0,0,0.1), rgba(0,0,0,0.4));
}

函數的語法非常直觀：light-dark(淺色模式值, 深色模式值)。第一個參數是淺色模式下使用的值，第二個參數是深色模式下使用的值。

color-scheme 屬性深度整合

color-scheme 屬性是 light-dark() 能運作的關鍵。它告訴瀏覽器目前元素「支援哪些配色方案」，並影響 light-dark() 選擇哪個值。

/* 跟隨系統設定（預設行為） */
:root { color-scheme: light dark; }

/* 強制淺色模式 */
:root { color-scheme: light; }

/* 強制深色模式 */
:root { color-scheme: dark; }

/* 讓使用者透過 JS 切換 */
document.documentElement.style.colorScheme = 'dark';

這種設計讓你可以在不改變任何 light-dark() 呼叫的情況下，只需修改一個 CSS 屬性就能切換整個網站的主題。

進階使用模式

與 CSS 自訂屬性結合

將 light-dark() 與 CSS 自訂屬性搭配使用，可以建立極具彈性的設計 token 系統：

:root {
  color-scheme: light dark;
  
  --color-surface: light-dark(#ffffff, #121212);
  --color-surface-variant: light-dark(#f3f3f3, #1e1e1e);
  --color-on-surface: light-dark(#1c1c1e, #f5f5f7);
  --color-primary: light-dark(#0066cc, #4da3ff);
  --color-primary-container: light-dark(#ddeeff, #003366);
  
  --shadow-sm: light-dark(
    0 1px 3px rgba(0,0,0,0.12),
    0 1px 3px rgba(0,0,0,0.5)
  );
  --shadow-md: light-dark(
    0 4px 12px rgba(0,0,0,0.15),
    0 4px 12px rgba(0,0,0,0.6)
  );
}

.button-primary {
  background: var(--color-primary);
  color: var(--color-surface);
  box-shadow: var(--shadow-sm);
}

在不同屬性類型上的應用

light-dark() 不只限於顏色，任何接受顏色值的屬性都可以使用：

/* 漸層背景 */
.hero {
  background: light-dark(
    linear-gradient(135deg, #667eea 0%, #764ba2 100%),
    linear-gradient(135deg, #1a1a2e 0%, #16213e 100%)
  );
}

/* 邊框顏色 */
.input {
  border-color: light-dark(#cccccc, #444444);
  outline-color: light-dark(#0066cc, #4da3ff);
}

/* 文字陰影 */
.heading {
  text-shadow: light-dark(
    none,
    0 0 20px rgba(77, 163, 255, 0.3)
  );
}

light-dark() vs prefers-color-scheme 媒體查詢

很多開發者會問：我已經在用 @media (prefers-color-scheme: dark)，還需要換成 light-dark() 嗎？

以下是兩種方式的比較：

建議在新專案中優先使用 light-dark()，舊專案可以逐步遷移。

實戰範例：完整主題系統

以下是一個完整的元件庫主題系統範例，結合了 CSS 自訂屬性、light-dark() 與使用者可切換的機制：

/* 1. 全域主題定義 */
:root {
  color-scheme: light dark;
  
  /* 語意化 token */
  --bg-base: light-dark(#fafafa, #0f0f0f);
  --bg-elevated: light-dark(#ffffff, #1a1a1a);
  --bg-overlay: light-dark(#f0f0f0, #252525);
  
  --text-primary: light-dark(#111111, #f0f0f0);
  --text-secondary: light-dark(#555555, #aaaaaa);
  --text-disabled: light-dark(#999999, #555555);
  
  --border-default: light-dark(#e2e2e2, #333333);
  --border-focus: light-dark(#0066cc, #4da3ff);
  
  --interactive-primary: light-dark(#0066cc, #4da3ff);
  --interactive-primary-hover: light-dark(#0052a3, #66b5ff);
  --interactive-danger: light-dark(#cc0000, #ff6b6b);
}

/* 2. 元件使用 */
.card {
  background: var(--bg-elevated);
  border: 1px solid var(--border-default);
  color: var(--text-primary);
  border-radius: 12px;
  padding: 1.5rem;
  transition: box-shadow 0.2s;
}

.card:hover {
  box-shadow: light-dark(
    0 8px 24px rgba(0,0,0,0.12),
    0 8px 24px rgba(0,0,0,0.5)
  );
}

/* 3. 使用者手動切換（JavaScript） */
function setTheme(theme) {
  document.documentElement.style.colorScheme = theme; // 'light' | 'dark' | 'light dark'
  localStorage.setItem('theme', theme);
}

這個架構與CSS Popover API等新特性結合，可以打造完全不依賴 JS 框架的現代 UI。

效能考量

light-dark() 是純 CSS 解決方案，相較於 JavaScript 切換主題有以下效能優勢：

• 無閃爍（FOUC）：CSS 在頁面渲染前就確定樣式，不會有 JS 切換主題時常見的白色閃爍
• 更少的 JavaScript：減少 JS bundle 大小，改善 First Contentful Paint
• 瀏覽器原生優化：瀏覽器可以對 color-scheme 變更做批次樣式重算，而非逐一處理 class 切換
• 系統整合：自動與 OS 層級的深色模式同步，包含表單元件、捲軸等系統 UI

在大型前端應用中，結合 CSS 設計 token 系統使用 light-dark()，可以顯著降低主題管理的複雜度，同時提升使用者體驗。

結語

CSS light-dark() 函數代表了 CSS 語言進化的一個重要里程碑 —— 讓原本需要 JavaScript 才能實現的功能，以更優雅、效能更好的方式在 CSS 層面就能完成。

對於 2026 年的前端開發者來說，掌握 light-dark() 搭配 color-scheme 的組合，是打造現代化、無障礙網站主題系統的必備技能。從今天開始，讓你的主題切換邏輯回歸 CSS 的本質吧！