Design on kenji.blog

Hugo的主題自訂：導入Tailwind CSS的方法

Sun, 13 Sep 2026 03:00:00 +0900

前言：靜態網站生成器Hugo與Tailwind CSS的強大協同效應

在現代的Web前端開發中，兼顧效能與開發體驗（DX：Developer Experience）是所有專案中最重要的課題之一。將在靜態網站生成器（SSG）中擁有世界最快建置速度的Hugo，與引入了實用優先（Utility-First）這一革新典範的Tailwind CSS相結合，可以說是由此課題得出的一個終極解答。

Hugo是使用Go語言編寫的，即使是擁有數千個頁面的網站，也具備在短短幾秒，甚至毫秒級別內完成建置的驚人效能。另一方面，Tailwind CSS透過在HTML中直接寫入預先定義的無數個實用類別（例如：flex、text-center、mt-4等），消除了在CSS檔案與HTML檔案之間來回切換的上下文切換（Context Switch），從而加速了設計的迭代。

本文將徹底且詳細地解說在Hugo主題中導入Tailwind CSS，並進一步使用PostCSS建立進階資源管道（Hugo Pipes）的步驟，內容涵蓋從架構的基礎到數學的效能最佳化觀點。

1. 實用優先CSS與元件導向的演變

在進入Tailwind CSS的導入步驟之前，深入理解為什麼我們應該使用Tailwind CSS，以及其背景中的CSS設計思想歷史與演變，是非常有幫助的。

傳統CSS設計（BEM與OOCSS）的極限

在過去的Web開發中，賦予語意化的類別名稱被認為是最佳實踐。例如，當建立卡片元件時，會像以下這樣將HTML與CSS分離。

1
2
3
4
5
6
7


<div class="card">
 <img class="card__image" src="image.jpg" alt="thumbnail">
 <div class="card__content">
 <h2 class="card__title">標題</h2>
 <p class="card__description">說明文字會放在這裡。</p>
 </div>
</div>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


.card {
 border-radius: 8px;
 box-shadow: 0 4px 6px rgba(0,0,0,0.1);
 background-color: #ffffff;
 overflow: hidden;
}
.card__title {
 font-size: 1.5rem;
 font-weight: bold;
 color: #333333;
}
/* 之後會接著詳細的樣式 */

像這樣基於BEM（Block Element Modifier）的設計，在專案規模較小時還能運作良好，但往往會引發以下問題：

命名枯竭與疲勞：每當製作類似的元件時，就必須思考新的類別名稱（例：card-news、card-featured等）。
CSS的肥大化：每當新增新功能時，CSS的行數就會持續增加，而一旦寫好的CSS因為害怕「不知道在哪裡被使用」，所以很少會被刪除，導致無效程式碼（Dead Code）不斷累積。
上下文切換：因為將HTML的結構與CSS的樣式分開在不同的檔案中管理，在編輯器上來回切換分頁的次數會呈指數級增加。

Tailwind CSS帶來的典範轉移

Tailwind CSS透過「實用類別的組合」這種方法來解決這些問題。如果使用Tailwind CSS，上述的卡片元件將會變成如下所示：

1
2
3
4
5
6
7


<div class="rounded-lg shadow-md bg-white overflow-hidden">
 <img class="w-full h-48 object-cover" src="image.jpg" alt="thumbnail">
 <div class="p-6">
 <h2 class="text-2xl font-bold text-gray-800">標題</h2>
 <p class="mt-2 text-gray-600">說明文字會放在這裡。</p>
 </div>
</div>

由於類別名稱本身就代表了樣式的具體數值（例如 p-6 是 padding: 1.5rem;），因此只需看HTML就能預測最終的渲染結果。此外，透過Tailwind的JIT（Just-In-Time）編譯器，只有實際被使用的類別才會被提取到正式環境用的CSS檔案中，所以CSS的檔案大小會被縮減到極致。

2. Hugo Pipes與PostCSS的架構

為了將Tailwind CSS整合到Hugo中，必須理解被稱為Hugo Pipes的資源處理管道。Hugo Pipes是一個強大的功能，它能讓與資源相關的任何處理（如Sass/SCSS的編譯、JavaScript的打包與壓縮（Minify），以及本次將使用的PostCSS的執行等）都在Hugo內部完成。

PostCSS是一個使用JavaScript外掛來轉換CSS的工具。事實上，Tailwind CSS本身也是作為PostCSS的外掛在運作。

透過PostCSS進行的AST（抽象語法樹）轉換機制

理解PostCSS是如何處理CSS的，對於進行疑難排解時會有很大的幫助。以下的Mermaid圖表顯示了PostCSS讀取CSS檔案、透過外掛進行轉換，直到輸出最終CSS的管道處理過程。

flowchart TD
A["原始 CSS (styles.css)"] -->|解析器 (Parser)| B["AST (抽象語法樹)"]
B --> C["外掛 1: Tailwind CSS"]
C --> D["外掛 2: Autoprefixer"]
D --> E["外掛 N: cssnano"]
E -->|字串化器 (Stringifier)| F["編譯與最佳化後的 CSS"]

Parser（解析器）：解析輸入的原始CSS字串，並將其轉換為可供程式操作的資料結構——AST（抽象語法樹）。
Plugins（外掛群）：
- Tailwind CSS：掃描樣板檔案（HTML或Markdown），並將使用到的實用類別作為節點新增到AST上。此外，它也會展開 @tailwind 指令。
- Autoprefixer：參考 Can I Use 的資料庫，並在必要時將供應商前綴（Vendor Prefix，如 -webkit-、-moz- 等）新增到AST的屬性中。
Stringifier（字串化器）：將轉換完成的AST重新轉換為瀏覽器可解析的CSS字串並輸出。

3. 環境建置與先決條件

那麼，我們就進入實際的導入步驟吧。首先要確認是否已安裝必要的軟體。

必備條件

Hugo Extended Version：必須是包含Sass/SCSS處理功能與原生PostCSS整合功能的Extended版，而不是普通的Hugo版本。請在終端機中執行以下指令，並確認版本資訊中是否包含 extended 字串。
1 2 3

hugo version # 預期的輸出範例: # hugo v0.121.2-4146... windows/amd64 BuildDate=... VendorInfo=gohugoio +extended
Node.js與npm： Tailwind CSS與PostCSS等依賴套件是在Node.js上運作的。請確認是否已安裝Node.js（建議使用LTS版）。
1 2

node -v npm -v

安裝npm套件

在專案的根目錄（即Hugo設定檔 hugo.toml 所在的層級）初始化npm，並安裝必要的套件。

1
2
3
4
5


# 產生 package.json
npm init -y

# 安裝 Tailwind CSS、PostCSS、Autoprefixer 作為開發依賴套件
npm install -D tailwindcss postcss postcss-cli autoprefixer

[!IMPORTANT] 如果沒有安裝 postcss-cli，在從Hugo內部呼叫PostCSS時可能會發生錯誤。因為Hugo Pipes在內部會使用 postcss-cli，所以請務必將其安裝。

4. 建立設定檔（PostCSS & Tailwind CSS）

套件安裝完成後，接著要建立兩個控制專案行為的重要設定檔。請將它們放置在專案的根目錄。

建立 tailwind.config.js

在終端機中執行以下指令，將會產生預設的設定檔。

1

npx tailwindcss init

使用編輯器打開生成的 tailwind.config.js，並設定 content 屬性。這部分非常重要。Tailwind會解析這裡指定路徑的檔案，並提取被使用的類別。請配合Hugo的專案結構，準確地指定版面配置檔（Layout）和內容檔（Content）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


/** @type {import('tailwindcss').Config} */
module.exports = {
 // 配合Hugo的目錄結構指定掃描對象
 content: [
 "./content/**/*.md",
 "./content/**/*.html",
 "./layouts/**/*.html",
 "./assets/**/*.js",
 // 如果有使用主題，也必須包含主題的目錄
 // "./themes/my-theme/layouts/**/*.html",
 ],
 theme: {
 extend: {
 // 在此擴充自訂顏色或字型
 colors: {
 'brand-primary': '#3490dc',
 'brand-secondary': '#ffed4a',
 },
 fontFamily: {
 'sans': ['Helvetica Neue', 'Arial', 'Hiragino Kaku Gothic ProN', 'Meiryo', 'sans-serif'],
 }
 },
 },
 plugins: [
 // 視需要加入官方外掛（例如：Typography 外掛）
 // require('@tailwindcss/typography'),
 ],
}

建立 postcss.config.js

接著，在專案根目錄建立 postcss.config.js，用來定義PostCSS要以什麼順序執行哪些外掛。

1
2
3
4
5
6


module.exports = {
 plugins: {
 tailwindcss: {},
 autoprefixer: {},
 }
}

透過這個設定，當Hugo呼叫PostCSS時，會先進行Tailwind CSS的處理，然後再由Autoprefixer賦予供應商前綴。

5. 在Hugo中建立CSS資源管道

設定完成後，終於要在Hugo的主題端整合Tailwind CSS了。

5-1. 建立作為進入點的CSS檔案

在 assets/css/ 目錄（如果不存在請建立它）中，建立作為進入點的CSS檔案。這裡我們將其命名為 main.css。

檔案路徑：assets/css/main.css

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


/* 載入Tailwind的基礎樣式（Reset CSS等） */
@tailwind base;

/* 載入元件類別 */
@tailwind components;

/* 載入實用類別 */
@tailwind utilities;

/* 如果需要自有的客製化CSS，可以寫在這裡，
 但建議盡可能透過 tailwind.config.js 的 extend 來處理 */
@layer components {
 .btn-primary {
 @apply bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded transition-colors duration-300;
 }
}

5-2. 編輯版面配置檔（head.html）

接著，要撰寫從Hugo的樣板載入上述CSS檔案，並透過PostCSS處理的管道。一般來說，會編輯定義 <head> 標籤內的局部樣板（Partial Template）（例如：layouts/partials/head.html）。

檔案路徑：layouts/partials/head.html

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


<head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>{{ .Title }} | {{ .Site.Title }}</title>

 <!-- 取得 assets/css/main.css -->
 {{ $css := resources.Get "css/main.css" }}

 <!-- 定義PostCSS的選項 -->
 {{ $options := dict "inlineImports" true }}
 {{ $css = $css | resources.PostCSS $options }}

 <!-- 針對正式環境（Production）的資源最佳化管道 -->
 {{ if hugo.IsProduction }}
 <!-- 1. 壓縮（Minify） -->
 {{ $css = $css | minify }}
 <!-- 2. Fingerprint（為了快取破壞（Cache Busting）的雜湊賦予） -->
 {{ $css = $css | fingerprint "sha512" }}
 <!-- 3. 輸出包含SRI（Subresource Integrity）的標籤 -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}" crossorigin="anonymous">
 {{ else }}
 <!-- 在開發環境（Development）不進行壓縮，直接輸出（優先考量建置速度） -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}">
 {{ end }}
</head>

管道解說與Mermaid圖解

上述的Go樣板程式碼是如何處理CSS檔案的，這裡將一連串的管道處理進行圖解。

flowchart TD
A["assets/css/main.css"] -->|resources.Get| B["Hugo 記憶體空間"]
B -->|resources.PostCSS| C["PostCSS + Tailwind JIT 處理"]
C --> D{"hugo.IsProduction ?"}
D -- Yes (正式環境) --> E["minify (刪除空白與換行)"]
E --> F["fingerprint (雜湊計算)"]
F --> G["public/css/main.[hash].css (附帶 SRI)"]
D -- No (開發環境) --> H["public/css/main.css"]

resources.Get：尋找 assets 目錄內指定的檔案，並將其作為資源物件載入到記憶體中。
resources.PostCSS：參考專案根目錄的 postcss.config.js，對CSS原始碼套用Tailwind CSS與Autoprefixer的處理。在開發環境（hugo server）中，JIT模式會啟動，在修改檔案時，能高速生成僅需的類別。
minify：在正式環境建置時（如 hugo --environment production），刪除不需要的空白與註解，將檔案大小最小化。
fingerprint：根據檔案的內容計算SHA雜湊值，並附加到檔案名稱上（例：main.ab12cd...css）。藉此，在利用瀏覽器強大快取的同時，也能實現在CSS更新時確保讀取新檔案的「快取破壞（Cache Busting）」。
integrity：使用Fingerprint計算出的雜湊值，輸出SRI屬性，以防止來自CDN等的竄改。

6. CSS最佳化中的數學效能分析

導入Tailwind CSS最大的好處之一，就是能將傳輸的CSS檔案大小極小化。這會對網頁效能（特別是首次內容繪製：FCP）帶來什麼樣的影響呢？讓我們使用數學模型來進行量化分析。

CSS檔案大小的縮減模型

在傳統的CSS框架（如Bootstrap等）中，因為包含未使用的樣式也會全部載入，檔案大小 $S_{original}$ 通常會很大（約150KB～200KB）。若將Tailwind CSS的JIT編譯器套用清除（Purge）不需要類別後的檔案大小設為 $S_{purged}$，使用縮減率 $R_{purge}$ 則可以表示如下：

$$ S_{purged} = S_{original} \times (1 - R_{purge}) $$

在典型的專案中，$R_{purge}$ 可接近 $0.9$（減少90%），而 $S_{purged}$ 僅有約10KB～20KB左右。

此外，傳輸時伺服器端還會透過Brotli或Gzip進行壓縮。若將壓縮率設為 $R_{compress}$（通常在0.7～0.8左右），則網路上傳輸的最終負載大小 $S_{final}$ 透過以下公式計算：

$$ S_{final} = S_{purged} \times (1 - R_{compress}) $$

關鍵渲染路徑與網路延遲

瀏覽器直到在畫面上繪製出最初內容為止的時間（FCP），可以由HTML的下載時間、CSS的下載時間，以及渲染時間的總和來近似計算。

$$ T_{FCP} \approx RTT + \frac{S_{HTML}}{BW} + RTT + \frac{S_{final}}{BW} + T_{render} $$

這裡的：

$RTT$：Round Trip Time（與伺服器來回通訊的延遲時間）
$BW$：網路頻寬（Bandwidth）

在如行動網路等 $BW$ 較窄且 $RTT$ 較大（延遲較高）的環境中，Tailwind CSS能將 $S_{final}$ 削減到數KB單位的方法，可以使 $\frac{S_{final}}{BW}$ 這一項極度逼近零，這正是能夠在Google PageSpeed Insights等工具中獲得驚人高分的動力來源。

7. 啟動開發伺服器與確認熱重載（Hot Reload）

當所有設定都完成後，啟動Hugo的開發伺服器，並確認Tailwind CSS是否能正常運作。

1

hugo server -D

使用瀏覽器造訪 http://localhost:1313/，並確認網站是否正常顯示。請打開Markdown的內容檔或是Hugo的樣板（layouts/ 以下的檔案），試著加入類別看看。

1
2
3
4
5


<!-- 測試用的Tailwind類別套用範例 -->
<div class="bg-gradient-to-r from-blue-500 to-purple-600 text-white p-8 rounded-xl shadow-2xl text-center transform transition duration-500 hover:scale-105">
 <h1 class="text-4xl font-extrabold tracking-tight">Tailwind CSS + Hugo is Awesome!</h1>
 <p class="mt-4 text-lg font-medium">請確認熱重載（Hot Reload）是否瞬間反映。</p>
</div>

在儲存檔案的瞬間，Hugo強大的檔案監視器與Tailwind的JIT編譯器會互相配合，在毫秒級別內重新建置CSS，你應該能體驗到瀏覽器自動重新載入（熱重載）的快感。

疑難排解：如果樣式沒有反映的情況

如果變更沒有反映，請檢查以下幾點：

tailwind.config.js 的 content 路徑設定 如果掃描對象的檔案路徑有誤，Tailwind就無法偵測到該檔案內使用的類別，也不會輸出到CSS中。特別是當有使用主題時，請確認是否遺漏了主題目錄的路徑。
PostCSS錯誤 如果在終端機的Hugo伺服器日誌中出現如 Error: failed to transform resource: PostCSS not found 這樣的錯誤，可能是 npm install 沒有正確執行，或者是缺少了 postcss-cli。
清除Hugo的快取 有時候會因為Hugo快取的原因而殘留舊的CSS。請停止伺服器，然後使用 hugo server --ignoreCache 來啟動，或是試著刪除OS的暫存目錄（例如 /tmp/hugo_cache/）。

8. 針對正式環境的建置與進一步的進階設定

將網站部署到正式伺服器（如Netlify、Vercel、GitHub Pages、Cloudflare Pages等）時，必須設定環境變數並執行正式環境用的最佳化管道。

1
2


# 正式環境建置指令的範例
NODE_ENV=production hugo --minify --environment production

透過加上 --environment production 標籤，會執行 head.html 內的 {{ if hugo.IsProduction }} 區塊，進行CSS的壓縮（Minify）並賦予Fingerprint。

使用Typography外掛進行Markdown的樣式設定

在像Hugo這類的部落格或文件網站中，無法直接對由Markdown生成的純HTML元素（如 <h1>、<p>、<ul> 等）加上類別。在這種情況下，非常有用的就是Tailwind官方的 Typography 外掛。

安裝外掛

1

npm install -D @tailwindcss/typography

新增到 tailwind.config.js

1
2
3
4
5
6


module.exports = {
 // ...
 plugins: [
 require('@tailwindcss/typography'),
 ],
}

在樣板中套用只要在輸出文章本文的容器元素上加上 prose 類別（以及個人喜好的顏色或尺寸變體），就能套用美麗的預設樣式。
1 2 3

<article class="prose prose-lg prose-blue mx-auto mt-10"> {{ .Content }} </article>

這樣一來，就完全不需要手寫複雜的CSS選擇器（如 .article-content h2 { ... }），能完全保持元件的模組性。

9. 總結：完成具高維護性的前端生態系統

辛苦了。到這裡，具備Hugo超高速靜態網站生成引擎、Tailwind CSS現代化樣式設定功能，以及PostCSS擴充性的完美Web開發資源管道就完成了。

這個架構的優點在於，「設定只需在最初進行一次即可」。只要建立好管道，開發者就不需要打開CSS檔案，只需在HTML或Markdown樣板中寫入直觀的實用類別，就能以驚人的速度構建出複雜的UI。

此外，由於輸出的CSS大小始終會被最小化，這將直接提升Core Web Vitals的分數，從SEO的角度來看也非常有利。

Hugo與Tailwind CSS的組合，從個人技術部落格到大型企業網站，在所有專案中都將會是「最佳選擇」之一。請務必活用這個強大的工具鏈，享受舒適的Web開發生活！

軟體架構的基礎：什麼是整潔架構？

Sat, 12 Sep 2026 12:00:00 +0900

現代軟體開發中，建構「適應變化的系統」是一個永恆的課題。業務需求的變更、新框架的崛起、UI 的翻新、資料庫的轉移。面對這一切的變化，我們需要一種不需要重構整個系統就能靈活適應的架構。作為解答之一，Robert C. Martin（被稱為 Uncle Bob）提出了整潔架構（Clean Architecture）。

本文將透過整潔架構的歷史、目的、四個層次的細節、依賴規則，以及具體的實作範例，深入探討整潔架構的精髓。我們將進行非常深入且詳細的技術解說。

1. 傳統架構的問題點與整潔架構的歷史

從歷史來看，軟體架構經歷了各種典範轉移。早期的系統中，業務邏輯、UI、資料存取的程式碼高度耦合（也就是所謂的義大利麵程式碼）。之後，為了關注點分離（Separation of Concerns），三層式架構（表現層、業務邏輯層、資料存取層）變得普及。

然而，傳統的三層式架構有一個巨大的問題。那就是「領域（業務邏輯）會依賴於資料庫或框架」。

例如，當業務邏輯層直接呼叫資料存取層（如 ORM 等）時，資料庫的綱要變更或 ORM 的變更就會波及業務邏輯。也就是說，產生了一個矛盾：最重要、最不應該被變更的「業務規則」，竟然依賴於最容易發生技術變更的「基礎設施」。

作為這個問題的解決方案，以下幾種架構被構思出來：

六角架構 (Ports and Adapters) - Alistair Cockburn
洋蔥架構 (Onion Architecture) - Jeffrey Palermo
DCI (Data, Context and Interaction) - James Coplien, Trygve Reenskaug
BCE (Boundary-Control-Entity) - Ivar Jacobson

這些架構都有相同的目的。那就是「關注點分離」。將軟體分割成不同層次，使其每一層都能獨立測試，並處於獨立於外部代理（UI、資料庫、框架）的狀態。

Robert C. Martin 將這些優秀架構的概念整合，並將它們歸納成一個實用的規則，命名為「整潔架構」。

2. 整潔架構的目的與特性

採用整潔架構的系統具有以下特性：

獨立於框架 (Independent of Frameworks)：架構不依賴於功能豐富的軟體函式庫的存在。這使得您可以將框架作為「工具」來使用，而無需將系統強塞進框架的限制中。
可測試 (Testable)：業務規則可以在沒有 UI、資料庫、Web 伺服器或其他外部元素的情況下進行測試。
獨立於 UI (Independent of UI)：UI 可以在不改變系統其餘部分的情況下輕鬆變更。例如，Web UI 可以替換為 Console UI，而無需變更業務規則。
獨立於資料庫 (Independent of Database)：您可以將 Oracle 或 SQL Server 替換為 Mongo、BigTable、CouchDB 等。業務規則不會被資料庫所綁定。
獨立於外部代理 (Independent of any external agency)：實際上，業務規則對外部世界一無所知。

3. 整潔架構的四個層次 (Layers)

整潔架構通常以同心圓的圖形表示。越靠近中心，軟體就越屬於高層級的策略（抽象度較高的業務規則）。越往外圍，就越是機制（具體的細節）。

graph TD
subgraph "External Interfaces (Frameworks & Drivers)"
A["Web"]
B["UI"]
C["資料庫"]
D["外部 API"]
end
subgraph "Interface Adapters"
E["控制器"]
F["閘道器"]
G["展示器"]
end
subgraph "Application Business Rules (Use Cases)"
H["使用案例互動器"]
end
subgraph "Enterprise Business Rules (Entities)"
I["實體"]
end
A --> E
B --> E
C --> F
D --> F
E --> H
F --> H
G --> H
H --> I

3.1. 實體 (Entities)

實體封裝了全公司範圍的業務規則（Enterprise Business Rules）。實體可以是擁有方法的物件，也可以是資料結構與函式的集合。它們是可以在公司內多個不同應用程式中重複使用的，最通用且高層級的規則。即使您只建立單一應用程式，實體也是該應用程式的業務物件。即使發生外部變更（例如頁面導覽變更或安全性變更），實體也絕對不會受到影響。

3.2. 使用案例 (Use Cases)

使用案例層包含特定於應用程式的業務規則（Application Business Rules）。這裡封裝並實作了系統的所有使用案例。使用案例負責協調往返於實體之間的資料流，並指示實體以達成系統的目標。這一層的變更不應該影響實體。此外，資料庫、UI、框架等外部的變更也不會影響這一層。使用案例完全與這些關注點分離。

3.3. 介面轉接器 (Interface Adapters)

介面轉接器層是一組轉接器，負責將資料從對使用案例和實體方便的格式，轉換為對資料庫或 Web 等外部代理方便的格式。例如，在 Web 世界中，GUI 的 MVC（Model-View-Controller）架構元素就屬於這裡。控制器接收使用者的輸入，傳遞給使用案例，展示器接收來自使用案例的輸出，並將其格式化給視圖（UI）。此外，將資料轉換為資料庫（如 SQL）能夠理解的格式，也是這一層的職責。這一層內側的程式碼不應該對資料庫有任何了解。

3.4. 框架與驅動程式 (Frameworks & Drivers)

最外層由資料庫、Web 框架等工具組成。通常在這裡，除了與內圈溝通的「黏合程式碼（Glue Code）」之外，我們不會撰寫太多其他程式碼。這一層保留了所有的細節。Web 是細節。資料庫也是細節。為了將損害降到最低，我們將這些細節放置在最外側。

4. 依賴規則 (The Dependency Rule)

為了使整潔架構成立，有一個最重要且絕對不能打破的規則。那就是「依賴規則 (The Dependency Rule)」。

原始碼的依賴關係必須只能指向內側（高層級的策略）。

屬於內圈的程式碼，絕對不能知道任何關於外圈程式碼的事情。在外圈宣告的名稱（函式、類別、變數等），不得在內圈被提及。同樣地，外圈使用的資料格式也不應該在內圈使用。特別是當該格式是由外圈的框架所生成時更是如此。

graph LR
A["框架與驅動程式"] -->| 依賴 | B["介面轉接器"]
B -->| 依賴 | C["使用案例"]
C -->| 依賴 | D["實體"]
style A fill:#f9f9f9,stroke:#333,stroke-width:2px
style B fill:#e6f7ff,stroke:#333,stroke-width:2px
style C fill:#fff0f6,stroke:#333,stroke-width:2px
style D fill:#f6ffed,stroke:#333,stroke-width:2px

用數學來表示的話，假設層級索引為 $L_i$，$i=0$ 定義為實體（最內層），$i=3$ 定義為框架（最外層），當存在從某一層 $L_m$ 到 $L_n$ 的依賴關係時，必定要滿足以下不等式：

$$ m > n $$

也就是說，依賴關係的向量 $\vec{D}$ 總是朝向中心。

5. 跨越邊界：依賴反轉原則 (DIP)

當我們試圖遵守依賴規則時，很快就會面臨一個巨大的問題：「當使用案例需要從資料庫取得資料時，該怎麼辦？」

如果使用案例層（內側）直接呼叫介面轉接器層（外側的 Repository 實作），依賴關係就會指向外側，從而違反了依賴規則。

解決這個問題的方法，是 SOLID 原則中的「D（Dependency Inversion Principle: 依賴反轉原則）」。

依賴反轉原則 (DIP) 的定義

高層模組不應該依賴於低層模組。兩者都應該依賴於抽象。
抽象不應該依賴於細節。細節應該依賴於抽象。

為了實現這一點，我們在使用案例層定義介面（抽象），並在外層（介面轉接器）實作該介面。使用案例層只依賴於自己定義的介面，而不依賴於外層的具體實作。

classDiagram
class UseCaseInteractor {
- UserRepository repository
+ execute()
}
class UserRepository {
<<Interface>>
+ findById(id)
+ save(user)
}
class UserRepositoryImpl {
+ findById(id)
+ save(user)
}
UseCaseInteractor --> UserRepository : "Depends on (依賴)"
UserRepositoryImpl ..|> UserRepository : "Implements (實作)"
note for UseCaseInteractor "Inner Layer (使用案例)"
note for UserRepository "Inner Layer (使用案例)"
note for UserRepositoryImpl "Outer Layer (介面轉接器)"

在上面的圖中，執行時期的控制流程（Control Flow）是 UseCaseInteractor $\rightarrow$ UserRepositoryImpl。然而，原始碼的依賴關係（Source Code Dependency）則是 UserRepositoryImpl $\rightarrow$ UserRepository（內側）。透過利用多型（Polymorphism），我們成功地將原始碼的依賴關係指向與控制流程相反的方向。這就是為什麼被稱為依賴的「反轉」的緣故。

6. 使用 TypeScript 的具體實作範例

這裡我們使用 TypeScript 來展示一個簡單的整潔架構實作範例（使用者註冊功能）。

6.1. 實體 (Entities)

位於最中心的業務規則。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// src/domain/entities/User.ts
export class User {
 constructor(
 public readonly id: string,
 public readonly name: string,
 public readonly email: string,
 public readonly createdAt: Date
 ) {}

 // 實體特有的業務規則（例如：名稱長度檢查等）
 public isValid(): boolean {
 return this.name.length >= 3 && this.email.includes('@');
 }
}

6.2. 使用案例 (Use Cases)

在使用案例層中，我們定義輸入和輸出的資料結構（DTO），以及為了反轉依賴而使用的 Repository 介面。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


// src/application/repositories/UserRepository.ts
import { User } from '../../domain/entities/User';

// 使用案例層所定義的介面
export interface UserRepository {
 findByEmail(email: string): Promise<User | null>;
 save(user: User): Promise<void>;
}

// src/application/usecases/RegisterUser/RegisterUserDTO.ts
export interface RegisterUserInputDTO {
 name: string;
 email: string;
}

export interface RegisterUserOutputDTO {
 id: string;
 name: string;
 email: string;
 createdAt: Date;
}

// src/application/usecases/RegisterUser/RegisterUserUseCase.ts
import { User } from '../../domain/entities/User';
import { UserRepository } from '../../repositories/UserRepository';
import { RegisterUserInputDTO, RegisterUserOutputDTO } from './RegisterUserDTO';

export class RegisterUserUseCase {
 // 依賴於抽象（介面）。不依賴於具體實作。
 constructor(private readonly userRepository: UserRepository) {}

 public async execute(input: RegisterUserInputDTO): Promise<RegisterUserOutputDTO> {
 const existingUser = await this.userRepository.findByEmail(input.email);
 if (existingUser) {
 throw new Error('User already exists');
 }

 const newUser = new User(
 crypto.randomUUID(),
 input.name,
 input.email,
 new Date()
 );

 if (!newUser.isValid()) {
 throw new Error('Invalid user data');
 }

 // 呼叫外層的 DB 儲存處理，但依賴是指向內側（介面）的
 await this.userRepository.save(newUser);

 return {
 id: newUser.id,
 name: newUser.name,
 email: newUser.email,
 createdAt: newUser.createdAt
 };
 }
}

6.3. 介面轉接器 (Interface Adapters)

建立對資料庫的具體存取處理（Repository 的實作），以及處理 HTTP 請求的 Controller。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


// src/adapters/repositories/PostgresUserRepository.ts
import { UserRepository } from '../../application/repositories/UserRepository';
import { User } from '../../domain/entities/User';
// 設想為外層（Driver）的 DB 客戶端
import { DatabaseClient } from '../../infrastructure/database/DatabaseClient';

export class PostgresUserRepository implements UserRepository {
 constructor(private readonly dbClient: DatabaseClient) {}

 public async findByEmail(email: string): Promise<User | null> {
 const record = await this.dbClient.query('SELECT * FROM users WHERE email = $1', [email]);
 if (!record) return null;
 return new User(record.id, record.name, record.email, record.created_at);
 }

 public async save(user: User): Promise<void> {
 await this.dbClient.query(
 'INSERT INTO users (id, name, email, created_at) VALUES ($1, $2, $3, $4)',
 [user.id, user.name, user.email, user.createdAt]
 );
 }
}

// src/adapters/controllers/UserController.ts
import { RegisterUserUseCase } from '../../application/usecases/RegisterUser/RegisterUserUseCase';

export class UserController {
 constructor(private readonly registerUserUseCase: RegisterUserUseCase) {}

 public async register(req: any, res: any): Promise<void> {
 try {
 const input = {
 name: req.body.name,
 email: req.body.email
 };
 const output = await this.registerUserUseCase.execute(input);
 res.status(201).json(output);
 } catch (error: any) {
 res.status(400).json({ message: error.message });
 }
 }
}

6.4. 主要元件 (依賴注入: DI)

在應用程式啟動時，建構所有的依賴關係（Wiring）。這被稱為 Composition Root。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


// src/infrastructure/web/server.ts
import express from 'express';
import { DatabaseClient } from '../database/DatabaseClient';
import { PostgresUserRepository } from '../../adapters/repositories/PostgresUserRepository';
import { RegisterUserUseCase } from '../../application/usecases/RegisterUser/RegisterUserUseCase';
import { UserController } from '../../adapters/controllers/UserController';

const app = express();
app.use(express.json());

// 1. 驅動程式的初始化
const dbClient = new DatabaseClient(/* 連線資訊 */);

// 2. 轉接器的初始化 (將具體類別實例化)
const userRepository = new PostgresUserRepository(dbClient);

// 3. 使用案例的初始化 (將具體實作注入到介面 = DI)
const registerUserUseCase = new RegisterUserUseCase(userRepository);

// 4. 控制器的初始化
const userController = new UserController(registerUserUseCase);

// 路由
app.post('/users', (req, res) => userController.register(req, res));

app.listen(3000, () => {
 console.log('Server is running on port 3000');
});

像這樣，最外層的「啟動腳本」承擔了骯髒的細節（具體類別的實例化），並讓內層只接收乾淨的介面，透過這種結構，業務邏輯就能完全與外部世界隔離。

7. 耦合度與內聚度的數學探討

在軟體工程中，用來評估架構品質的指標有耦合度 (Coupling) 與 內聚度 (Cohesion)。

耦合度 $C$ 代表模組之間依賴的強度。當模組 $A$ 依賴於模組 $B$ 時，若系統的總依賴關係數為 $N_{dep}$，模組數為 $N_{mod}$，則表示複雜度的一個指標可以如下表示：

$$ Complexity \propto \frac{N_{dep}}{N_{mod}} $$

在整潔架構中，透過應用 DIP，我們將物理依賴的箭頭指向抽象。抽象（介面）的變更頻率（不穩定性，Instability: $I$）被設計為非常低。

不穩定性 $I$ 由以下公式計算（根據 Robert C. Martin 的定義）：

$C_e$ (Efferent Coupling): 向外耦合（自己所依賴的數量）
$C_a$ (Afferent Coupling): 向內耦合（依賴於自己的數量）

$$ I = \frac{C_e}{C_e + C_a} $$

當 $I = 0$ 時，該元件完全穩定（不依賴任何人，且被他人依賴）。
當 $I = 1$ 時，該元件完全不穩定（不被他人依賴，且依賴他人）。

整潔架構的「實體層」因為 $C_e = 0$（不依賴外側），所以 $I = 0$。也就是說，它是最穩定的層。反之，「UI 層」或「DB 層」的 $C_a \approx 0$，且 $C_e > 0$，因此 $I \approx 1$，成為容易變更的層（不穩定的層）。

作為架構重要原則的 SDP（Stable Dependencies Principle: 穩定依賴原則）規定：「依賴必須指向更穩定的元件（$I$ 較小的元件）」。整潔架構的同心圓正是將這個 SDP 視覺化，並被設計為依賴總是從外側（$I=1$）指向內側（$I=0$）。

8. 測試策略與整潔架構

整潔架構最大的優點之一，就是測試的容易度。由於層次被分離，我們可以針對每一層獨立撰寫相應的測試。

8.1. 實體的測試 (Unit Test)

因為是完全沒有外部依賴的純粹邏輯，所以不需要 DB 也不需要 Mock。這是能夠最快執行且最確實的測試。

8.2. 使用案例的測試 (Unit Test with Mocks)

由於 Repository 等外部依賴全部都被定義為介面，測試時只需要注入（DI）**測試用的 Mock 或記憶體內實作（Fake）**即可。不需要啟動實際的資料庫。如此一來，就能高速地測試業務邏輯的複雜分支和例外處理。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// 使用案例的測試範例 (假設使用 Jest)
test('嘗試使用既有的電子郵件地址註冊時會發生錯誤', async () => {
 // 建立 Fake Repository
 const mockRepo: UserRepository = {
 findByEmail: async (email) => new User('1', 'Test', email, new Date()), // 傳回既有使用者
 save: async (user) => {}
 };

 const useCase = new RegisterUserUseCase(mockRepo);

 // 執行使用案例並驗證錯誤
 await expect(useCase.execute({ name: 'Bob', email: 'test@example.com' }))
 .rejects
 .toThrow('User already exists');
});

8.3. 轉接器的測試 (Integration Test)

Repository 的實作類別會實際連接到資料庫來測試 SQL 是否正確。Controller 的測試則是測試接收 HTTP 請求並回傳 JSON 的部分。在這裡不進行業務邏輯的詳細驗證，純粹只確認「轉換」與「通訊」是否正確。

9. 整潔架構的缺點與應採用的時機

整潔架構雖然看起來像是萬能的，但並不是強力的銀彈。存在著以下缺點（權衡）：

初期學習成本與開發成本的增加：檔案數量和介面（抽象）的數量會大幅增加。像是 DTO 重新封裝等「樣板程式碼（Boilerplate Code）」會變多。
對小規模專案來說是大材小用（Overkill）：對於只要幾天就能做出來的原型，或是幾乎不會發生變更的一次性工具，採用這種架構通常會造成無謂的成本浪費。對於只有 CRUD 操作的單純 API 也不適合。

應該採用的時機：

預期會長期（數年以上）維護與營運的產品。
業務規則複雜，且頻繁進行規格變更的系統。
希望在大規模開發團隊中推進分工（前端、後端、基礎設施等）的情況。
希望結合領域驅動設計（DDD: Domain-Driven Design）來對複雜業務領域進行塑模的情況。

10. 總結

整潔架構是一種設計理念，旨在保護「業務規則」這個系統的核心，使其免受 UI、資料庫、框架等「細節」的影響。

其核心是依賴規則與依賴反轉原則 (DIP)。透過正確應用這些原則，軟體能夠更靈活地適應變化，測試也變得容易，並能在很長一段時間內持續維持其價值。

重要的是，不要盲目地模仿整潔架構的目錄結構，而是要理解「為什麼要這樣分割」、「依賴關係的箭頭指向哪裡」的本質，並根據自身專案的規模和複雜度來適當地應用。

Reference: “Clean Architecture: A Craftsman’s Guide to Software Structure and Design” by Robert C. Martin

部落格深色模式支援的 CSS 設計重點

Sat, 12 Sep 2026 12:00:00 +0900

現代 Web 開發中，深色模式（Dark Mode）的支援已經從單純的「有了會更好（Nice to have）」的功能，轉變為提升使用者體驗（UX）的「必備條件（Must have）」。特別是在部落格或文件網站這類以長時間閱讀文字為前提的媒體中，因為具有減輕使用者眼睛疲勞、降低裝置電池消耗的效果，深色模式支援的重要性可說是非常高。

本文將從前端工程師的視角，非常深入地探討在部落格的深色模式支援中無法避免的技術課題，以及高維護性 CSS 設計的重點。從 CSS Custom Properties（CSS 變數）的活用、防止 FOUC（Flash of Unstyled Content）的進階 JavaScript 控制與 SSR 整合、確保無障礙（WCAG 2.1 AAA）的色彩設計（RGB、HSL 以及最新的 OKLCH），甚至到使用 Tailwind CSS 的實作程式碼範例，網羅了深色模式實作的所有內容。

1. 透過 CSS Custom Properties（CSS 變數）進行主題設計的基礎

在實作深色模式時，目前最標準且最強大的手法就是利用 CSS Custom Properties（CSS 變數） 的方法。相對於 Sass 等 CSS 預處理器的變數（$color）是在編譯時靜態解析，CSS 變數則是在瀏覽器的執行階段動態解析並覆寫。這使得只要透過 JavaScript 切換 class，就能瞬間改變整個頁面的色調。

1.1 基本色彩主題的定義

首先，使用 :root 偽類別來定義淺色模式（預設）的調色盤。然後，當賦予如 [data-theme='dark'] 這樣的屬性（或是 .dark class）時，覆寫這些變數，這是最常見的設計模式。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


/* 淺色模式（預設）的變數定義 */
:root {
 --color-bg-primary: #ffffff;
 --color-bg-secondary: #f3f4f6;
 --color-text-primary: #111827;
 --color-text-secondary: #4b5563;
 --color-accent: #3b82f6;
 --color-border: #e5e7eb;
}

/* 深色模式時的變數覆寫 */
[data-theme='dark'] {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
}

/* 實際套用 */
body {
 background-color: var(--color-bg-primary);
 color: var(--color-text-primary);
 transition: background-color 0.3s ease, color 0.3s ease;
}

a {
 color: var(--color-accent);
}

像這樣，將排版與字體的指定和顏色（主題）的指定完全分離，能讓 CSS 的維護性有飛躍性的提升。

1.2 活用 @media (prefers-color-scheme: dark)

當作業系統層級設定為深色模式時，從使用者初次造訪網站起就自動套用深色主題，這在 UX 的觀點上是比較理想的。能夠實現這點的就是 @media (prefers-color-scheme: dark) 這個媒體查詢。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


/* 當 OS 環境設定為深色模式時的備用方案（Fallback） */
@media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
 }
}

在這種寫法中，除非使用者明確選擇淺色模式（data-theme='light'），否則會尊重作業系統的深色模式設定來覆寫變數。

2. 理解色彩空間與無障礙設計（WCAG 2.1 AAA）

在深色模式的色彩設計中，單純地「把背景變黑、文字變白」是不夠的。對比太強會產生光暈反而難以閱讀，對比太低則會損害易視性。在網頁內容無障礙指南 (WCAG) 中，為了確保易視性，對比度有著嚴格的定義。

2.1 WCAG 對比度的計算公式

WCAG 中的對比度（Contrast Ratio） $CR$ ，是使用背景色與前景色的相對亮度（Relative Luminance）以下列方式定義：

$$CR = \frac{L_{lighter} + 0.05}{L_{darker} + 0.05}$$

這裡的 $L_{lighter}$ 是較亮顏色的相對亮度，$L_{darker}$ 是較暗顏色的相對亮度（值的範圍從 0.0 到 1.0）。為了達到 WCAG 2.1 的 AAA 等級，一般文字需要 7:1 以上，大型文字則需要 4.5:1 以上 的對比度。

相對亮度 $L$ 是從 sRGB 色彩空間的 RGB 值透過以下複雜的數學公式計算而來：

$$L = 0.2126 \times R + 0.7152 \times G + 0.0722 \times B$$

各成分（$R, G, B$）使用原始 8 位元值（$R_{sRGB}$）除以 255 的標準化值，進行以下轉換以解開伽瑪校正：

$$ R, G, B = \begin{cases} \frac{C_{sRGB}}{12.92} & \text{if } C_{sRGB} \le 0.03928 \\ \left( \frac{C_{sRGB} + 0.055}{1.055} \right)^{2.4} & \text{otherwise} \end{cases} $$

手動進行這項計算很困難，但透過運用色彩設計工具，可以機械式地選出符合對比度 7:1 ($CR \ge 7.0$) 的顏色。

2.2 HSL vs RGB vs OKLCH

過去在建立調色盤時，主流是 RGB 或 HSL。然而，這些在「知覺均勻度」的觀點上有著很大的缺陷。

RGB: 是機械式的光的三原色，人類很難直觀地進行「調亮」、「調暗」這類的調整。
HSL: 使用色相 (Hue)、彩度 (Saturation)、亮度 (Lightness)，但 HSL 的「亮度 (L)」與人類眼睛知覺到的亮度並不一致。例如，在 HSL 中亮度為 50% 的純黃色和純藍色，在數值上亮度相同，但在人類眼中黃色看起來卻亮得多。
OKLCH: 是近年在 CSS Color Module Level 4 中導入的最新色彩空間。由亮度 (Lightness，知覺明度)、彩度 (Chroma)、色相 (Hue) 組成，完全符合人類的視覺特性（知覺均勻）。

透過使用 OKLCH，即使改變色相（Hue），也能保持相同的知覺明度（Lightness），因此深色模式用的調色盤生成變得極具預測性且安全。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


/* 使用 OKLCH 的 CSS 變數定義範例 */
:root {
 /* 淺色模式的基礎明度較高，彩度較低 */
 --bg-base: oklch(0.98 0.01 250);
 --text-base: oklch(0.25 0.02 250);
 --primary-brand: oklch(0.65 0.15 250);
}

[data-theme="dark"] {
 /* 深色模式只需反轉明度，就容易維持知覺對比度 */
 --bg-base: oklch(0.20 0.02 250);
 --text-base: oklch(0.95 0.01 250);
 --primary-brand: oklch(0.75 0.15 250); /* 針對深色模式稍微調亮以確保易視性 */
}

像這樣採用 OKLCH，能夠簡單地建構出在多個主題間確保一致對比度（WCAG AAA 水準）的邏輯。

3. 防止 FOUC（Flash of Unstyled Content）與 SSR Hydration

在支援深色模式時，最讓開發者頭痛的就是被稱為 FOUC（Flash of Unstyled Content） 的畫面閃爍問題。

3.1 透過用戶端 JS 切換主題的陷阱

在 React 或 Vue 等 SPA（或是透過 SSG 建立的靜態網站）中，一般的做法是將使用者的設定儲存在 localStorage，再透過 JavaScript 讀取並切換主題。然而，如果將這個處理放在 React 的 useEffect 等地方執行，就會發生以下問題：

瀏覽器渲染淺色模式的 HTML/CSS。
JS 的 Bundle 被載入並執行。
從 localStorage 讀取 dark 設定。
HTML 被賦予 dark class，畫面突然變暗（閃爍）。

為了完全防止 FOUC，並預防 Hydration 錯誤，最佳實踐是將使用者的主題設定儲存在 document.cookie 中，並在伺服器端渲染（SSR）階段回傳已賦予適當 class 的 HTML。

以下的循序圖展示了利用 Cookie 進行主題初始化的理想流程：

sequenceDiagram
participant User as "使用者"
participant Browser as "瀏覽器 OS"
participant Server as "伺服器 SSR"
participant DOM as "用戶端 DOM"
User->>Browser: "請求頁面"
Browser->>Server: "帶有 Cookie (theme=dark) 的 GET 請求"
Server-->>Browser: "回傳帶有 <html data-theme='dark'> 的 HTML"
Browser->>DOM: "渲染初始 HTML (無 FOUC)"
DOM->>DOM: "執行 Hydration 腳本"
alt "Cookie 不存在 (初次造訪)"
DOM->>Browser: "檢查 OS prefers-color-scheme"
Browser-->>DOM: "matchMedia 結果 (例如: dark)"
DOM->>DOM: "透過行內阻擋腳本設定 data-theme='dark'"
end

如果是只有 SSG（靜態網站生成）而無法進行 SSR 的部落格（如 Hugo、Gatsby，或 Astro 的靜態匯出等），必須在 <head> 標籤內部配置會阻擋渲染執行的行內（inline）JavaScript，在 DOM 渲染前一刻賦予 class 的手法。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- 配置在 <head> 內的最後面 -->
<script>
 (function() {
 try {
 var localTheme = localStorage.getItem('theme');
 var osTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
 var theme = localTheme || osTheme;
 document.documentElement.setAttribute('data-theme', theme);
 } catch (e) {}
 })();
</script>

這個小腳本會阻擋瀏覽器的渲染並立即執行，因此在畫面渲染的時間點，data-theme 屬性已經被設定好，可以完全防止畫面的閃爍（FOUC）。

4. Tailwind CSS 與原生 SCSS/CSS 的實作方法

在將深色模式實際整合進專案時，必須理解各項工具的做法。

4.1 Tailwind CSS 中的深色模式

Tailwind CSS 預設提供了 dark: 變體（variant），可以非常簡單地實作深色模式。在設定檔（tailwind.config.js）中設定 darkMode 屬性。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// tailwind.config.js
module.exports = {
 // 'media' (依賴 OS 設定) 或是 'class' (可手動切換)
 darkMode: 'class',
 theme: {
 extend: {
 colors: {
 /* 利用 CSS 變數來擴充 Tailwind 的調色盤 */
 primary: 'rgb(var(--color-primary) / <alpha-value>)',
 background: 'rgb(var(--color-background) / <alpha-value>)',
 }
 }
 }
}

在 HTML 端只需像下面這樣賦予 class 即可。

1
2
3
4


<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
 <h1 class="text-2xl font-bold">Hello World</h1>
 <p class="mt-2">Tailwind makes dark mode incredibly easy.</p>
</div>

然而，對所有元素都寫上 dark:bg-xxx 也會成為元件肥大的原因。在大型部落格或應用程式中，推薦採用以 CSS 變數為基礎，並從 Tailwind 參考這些 CSS 變數的混合式設計（語意化色彩設計）。

以下是展示 CSS 變數的繼承與套用層級的類別圖。

classDiagram
class GlobalCSSVariables {
"--color-brand-500"
"--color-gray-900"
}
class SemanticVariables {
"--bg-primary"
"--text-base"
"--accent"
}
class TailwindConfig {
"theme.colors.background"
"theme.colors.primary"
}
class UIComponents {
"class='bg-background text-primary'"
}
GlobalCSSVariables <|-- SemanticVariables : ":root & .dark"
SemanticVariables <|-- TailwindConfig : "tailwind.config.js"
TailwindConfig <.. UIComponents : "套用工具類別"

4.2 原生 SCSS/CSS 的實作（活用 Mixin）

在不使用 Tailwind，而是自行撰寫 SCSS 的專案中，可以活用 @mixin 來封裝深色模式的樣式。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


/* SCSS Mixin 的定義 */
@mixin dark-mode {
 /* 支援 [data-theme='dark'] 屬性，或是 OS 設定這兩者 */
 [data-theme='dark'] & {
 @content;
 }
 @media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) & {
 @content;
 }
 }
}

/* 使用範例 */
.card {
 background-color: #ffffff;
 color: #333333;
 border: 1px solid #eeeeee;

 @include dark-mode {
 background-color: #1a202c;
 color: #e2e8f0;
 border-color: #2d3748;
 }
}

這個方法很直觀，但編譯後的 CSS 檔案大小容易肥大（媒體查詢會複製到各個選擇器上），因此目前趨勢依然是轉向以 CSS 變數（Custom Properties）為中心的設計。

5. 圖片（Image）與 SVG 的深色模式最佳化

即使文字或背景的色彩設計完成，如果配置為內容的圖片或圖示（SVG）仍維持淺色模式的狀態，在深色模式下會顯得非常刺眼且突兀。對這些元素進行最佳化也是不可或缺的。

5.1 降低圖片亮度的 CSS 濾鏡

像是照片等點陣圖，在深色模式下直接顯示有時會過於刺眼。使用 CSS 的 filter 屬性，稍微降低圖片的亮度（brightness）與對比度（contrast），就能讓圖片自然地融入深色主題的 UI 中。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[data-theme='dark'] img:not([src*=".svg"]) {
 /* 降低亮度，稍微提高對比度 */
 filter: brightness(0.8) contrast(1.1);
 transition: filter 0.3s ease;
}

[data-theme='dark'] img:hover {
 /* 懸停時恢復原始亮度（使用者想要看清楚細節時） */
 filter: brightness(1) contrast(1);
}

5.2 透過 `<picture>` 標籤切換圖片

Logo 圖片或是說明的圖解（背景固定為白色的 JPEG 等），光靠濾鏡處理是無法解決的。在這種情況下，正確的做法是使用 HTML 的 <picture> 元素和媒體查詢，來切換顯示深色模式用的另一張圖片檔案。

1
2
3
4
5
6


<picture>
 <!-- 針對深色模式 OS 設定的使用者顯示這張 -->
 <source srcset="/img/logo-dark.png" media="(prefers-color-scheme: dark)">
 <!-- 預設（淺色模式） -->
 <img src="/img/logo-light.png" alt="網站 Logo">
</picture>

※不過，這個方法無法與透過 localStorage 等進行的手動切換連動（只依賴 OS 設定），因此如果實作了手動切換功能，就需要透過 JS 動態改寫圖片的 src，或是透過 CSS class 切換 display: none。

5.3 SVG 圖示的 `currentColor` 支援

在圖示等地方使用的行內（inline）SVG，最聰明的做法是讓填滿的顏色與父元素的文字顏色連動。在 SVG 的 fill 或 stroke 屬性中指定 currentColor。

1
2
3
4


<!-- CSS 的 color 屬性值（如 var(--text-primary)）會自動套用 -->
<svg viewBox="0 0 24 24" fill="currentColor">
 <path d="M12 2L2 22h20L12 2z" />
</svg>

這樣一來，當切換到深色模式且父元素的文字顏色變成白色系時，SVG 圖示也會自動變成白色系。

6. 總結：邁向永續的深色模式設計

為了在部落格或 Web 應用程式中實作高品質的深色模式，網羅了以下重點的 CSS 設計是不可或缺的。

活用 CSS Custom Properties：避免硬編碼（hardcoding）指定顏色，將其抽象化為語意化的變數名稱（例如：--bg-primary）。
採用 OKLCH 色彩空間：在知覺均勻的色彩空間中，有邏輯地設計出滿足 WCAG 2.1 AAA 的高無障礙對比度（7:1 以上）。
貫徹 FOUC 對策：透過 SSR 與 Cookie 的整合，或是在 <head> 內阻擋渲染的行內腳本，完全排除初次載入時的畫面閃爍。
媒體與資源的最佳化：充分運用 filter: brightness()、currentColor 以及 <picture> 標籤，讓文字以外的元素也能與深色主題協調。

超越單純的「顏色反轉」，這些細膩的考量正是現代部落格能長久受使用者喜愛、提供不易造成眼睛疲勞的優良閱讀體驗（Reading Experience）的必備條件。即將導入深色模式的開發者們，請務必參考本文的設計模式。