如何為你的網站或應用程式加入深色模式（沒有閃白）

要加入深色模式，請把你的顏色定義為具名的權杖（背景、文字、表面、邊框、強調色），而不是寫死的數值；為每個權杖設定淺色與深色兩組值；並使用 CSS 的 prefers-color-scheme 媒體功能在兩者之間切換，讓網站跟隨訪客的系統設定。如果你還想要手動切換，請把使用者的選擇存在瀏覽器中，並用一段極小的內嵌腳本（放在頁面的 head 裡）套用，這樣載入時就不會閃白。接著，在兩種主題下檢查對比度、圖片與圖表。在 AI 應用程式建置工具中，一段清楚的提示詞就能完成大部分工作；真正決定品質的是檢查的過程。

兩種做法

大多數應用程式採用第二種做法效果最好：預設尊重系統設定，同時讓人們可以自行覆寫。

從色彩權杖開始

如果顏色散落在程式碼各處，寫成 white、#333 和 gray-100，深色模式就會很痛苦。若每種顏色都來自一小組具名權杖，就會容易得多：

每個元件都使用權杖名稱。這樣切換主題時，只要替換一組數值，而不需要逐一修改每個元件。

深色調色盤的幾點建議：

• 大面積避免使用純黑與純白。 非常深的灰色與微白的文字更容易閱讀。
• 用較亮的表面來呈現深度， 而不是陰影，因為陰影在深色背景上幾乎看不出來。
• 稍微降低明亮品牌色的飽和度。 它們在深色背景上可能會發出令人不適的光。
• 保持可讀的對比。 WCAG 的 AA 等級要求一般文字至少為 4.5:1 的對比度。在深色主題中，灰色的次要文字常常達不到這個標準。

搭配 Tailwind CSS

Tailwind 是許多 AI 製作的應用程式預設使用的樣式工具。根據 Tailwind 的深色模式文件，dark: 變體預設使用 prefers-color-scheme，因此像 bg-white dark:bg-gray-900 這樣的類別，不需要額外的工作就能跟隨系統設定。

若要在 Tailwind v4 中做手動切換，文件展示了如何把變體改成放在父元素上的 class：

@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));

接著，應用程式會在根元素上新增或移除 dark class。文件也建議在 head 中放一段內嵌腳本，在頁面繪製之前就套用已儲存的選擇（或系統設定）。這正是避免閃白的做法。

避免閃白

閃白發生的原因是：頁面先以淺色模式繪製，然後 JavaScript 載入、讀取已儲存的選擇，再切換成深色。解決方法：

1. 在頁面的 head 中放一段極小的內嵌腳本，讀取已儲存的主題，並在任何內容渲染之前，就在根元素上設定 class。
2. 為每種主題設定 color-scheme CSS 屬性，讓瀏覽器繪製的部分（捲軸、表單控制項）與主題相符。
3. 為兩種主題都設定明確的背景色。
4. 如果應用程式是伺服器端渲染，請確保伺服器與瀏覽器對初始主題的判斷一致，否則頁面可能會重新渲染而閃爍。

提示詞範例

完整設定：

加入深色模式。首先，把寫死的顏色換成主題權杖（背景、表面、文字、次要文字、邊框、強調色），並為每個權杖提供淺色與深色的值。預設跟隨訪客的系統設定。在頁首加入主題切換，提供淺色、深色和跟隨系統三個選項，把選擇記在 localStorage 中，並在 head 中以內嵌腳本套用，讓載入時不會閃白。為每種主題設定 color-scheme。保持目前的淺色設計完全不變。

修正剩下的問題：

在深色模式下檢查每個頁面，並修正以下問題：對比度過低的文字（至少 4.5:1）、寫死的白色背景、消失的邊框、深色文字落在深色背景上的圖表，以及消失的標誌。不要改動淺色主題。

圖片與圖表：

深色模式下使用淺色版的標誌。讓圖表的座標軸、格線與標籤使用主題權杖。在深色模式下為截圖加上細緻的邊框，讓它們不會與背景融在一起。

逐步操作

1. 稽核顏色。 找出寫死的顏色，並替換成權杖。這占了大部分工作量。
2. 為每個權杖定義深色值。
3. 用 prefers-color-scheme 跟隨系統（或使用 Tailwind 預設的 dark:）。
4. 如果需要，加入切換按鈕：淺色、深色、跟隨系統。把選擇存在瀏覽器中；對於需要登入的應用程式，也可以把它存到使用者的個人資料中。
5. 用內嵌的 head 腳本與 color-scheme 防止閃白。
6. 檢查容易出問題的部分：標誌、圖示、帶白色背景的圖片、圖表、程式碼區塊、地圖、嵌入內容、電子郵件。
7. 測試兩種主題，在桌機與手機上都測試，分別在系統設為淺色與深色時測試，並在強制重新整理後測試。

常見錯誤

• 把所有東西都反轉。 用濾鏡反轉顏色會毀掉照片與品牌色。
• 留下寫死的顏色。 深色頁面中一張白色卡片會立刻很突兀。
• 低對比的灰色文字。 看起來很時尚，但不易閱讀。
• 載入時閃白。 在夜間的手機上特別明顯。
• 忘記第三方嵌入內容。 地圖、影片與小工具可能仍是淺色的；請檢查它們是否提供深色選項。
• 只有兩種狀態的切換按鈕。 一旦有人點選，他們就無法再回到跟隨系統的狀態。
• 破壞淺色主題。 在提示詞中明確說明淺色設計應保持不變。

檢查清單

• 所有顏色都來自主題權杖
• 預設跟隨系統設定
• 提供可選的「淺色、深色、跟隨系統」切換，並記住選擇
• 載入或強制重新整理時不會閃白
• 已設定 color-scheme，讓表單控制項與捲軸相符
• 兩種主題中的文字對比都至少為 4.5:1
• 已在深色模式下檢查標誌、圖片、圖表與嵌入內容
• 淺色主題保持不變
• 已在桌機與手機上測試

在 Mythex 中使用深色模式

在 Mythex 上建置的應用程式預設使用 Vite、React、TypeScript 和 Tailwind，因此上述的 Tailwind 做法可以直接套用：把完整設定的提示詞貼到對話中，然後在預覽中以兩種主題、以及手機尺寸檢查。Mythex 的設計提示詞建議是，明確說明要改什麼、要保留什麼，這在這裡很重要，例如說明淺色主題必須保持不變。參閱設計與 UI 提示詞；如果某次修改出錯，可以用檢查點還原。

想要把外觀做好，請參閱如何用 AI 設計好看的應用程式與如何為 AI 應用程式建置工具撰寫提示詞。

常見問題