Tailwind CSS on kenji.blog

Hugoのテーマカスタマイズ：Tailwind CSSを導入する方法

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

はじめに：静的サイトジェネレーターHugoとTailwind CSSの強力なシナジー

現代のWebフロントエンド開発において、パフォーマンスと開発体験（DX：Developer Experience）の両立は、あらゆるプロジェクトにおいて最重要課題の一つです。静的サイトジェネレーター（SSG）の中で世界最速クラスのビルドスピードを誇るHugoと、ユーティリティファーストという革新的なパラダイムを持ち込んだTailwind CSSを組み合わせることは、この課題に対する一つの究極の解答と言えます。

HugoはGo言語で記述されており、数千ページのサイトであってもわずか数秒、あるいはミリ秒単位でビルドを完了させる驚異的なパフォーマンスを持っています。一方、Tailwind CSSは事前に定義された無数のユーティリティクラス（flex, text-center, mt-4など）をHTMLに直接記述していくことで、CSSファイルとHTMLファイルの間を往復するコンテキストスイッチを無くし、デザインのイテレーションを高速化します。

本記事では、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は「どこで使われているか分からない」という恐怖から削除されることが少なくなり、デッドコードが蓄積していきます。
コンテキストスイッチ: 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のアーキテクチャ

HugoにTailwind CSSを統合するためには、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["Raw CSS (styles.css)"] -->|Parser| B["AST (Abstract Syntax Tree)"]
B --> C["Plugin 1: Tailwind CSS"]
C --> D["Plugin 2: Autoprefixer"]
D --> E["Plugin N: cssnano"]
E -->|Stringifier| F["Compiled & Optimized CSS"]

Parser（パーサー）: 入力された生のCSS文字列を解析し、プログラムで操作可能なデータ構造であるAST（抽象構文木）に変換します。
Plugins（プラグイン群）:
- Tailwind CSS: テンプレートファイル（HTMLやMarkdown）をスキャンし、使用されているユーティリティクラスをAST上にノードとして追加します。また、@tailwindディレクティブを展開します。
- Autoprefixer: Can I Useのデータベースを参照し、必要に応じてベンダープレフィックス（-webkit-, -moz-など）をASTのプロパティに追加します。
Stringifier（ストリンギファイア）: 変換が完了したASTを、再びブラウザが解釈可能なCSS文字列に変換して出力します。

3. 環境構築と前提条件

それでは、実際の導入手順に入っていきましょう。まずは必要なソフトウェアがインストールされているか確認します。

必須要件

Hugo Extended Version: 通常のHugoではなく、Sass/SCSS処理機能やネイティブでのPostCSS連携機能が含まれたExtended版が必須です。ターミナルで以下のコマンドを実行し、バージョン情報に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）

パッケージのインストールが完了したら、プロジェクトの挙動を制御する2つの重要な設定ファイルを作成します。プロジェクトのルートディレクトリに配置してください。

tailwind.config.js の作成

ターミナルで以下のコマンドを実行すると、デフォルトの設定ファイルが生成されます。

1

npx tailwindcss init

生成された tailwind.config.js をエディタで開き、content プロパティを設定します。ここは非常に重要です。Tailwindはここで指定されたパスのファイルを解析し、使用されているクラスを抽出します。Hugoのプロジェクト構造に合わせて、レイアウトファイルやコンテンツファイルを正確に指定します。

 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がどのプラグインをどの順番で実行するかを定義する postcss.config.js をプロジェクトルートに作成します。

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のベーススタイル（リセット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> タグ内を定義しているパーシャルテンプレート（例：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（キャッシュバスティングのためのハッシュ付与） -->
 {{ $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 Memory Space"]
B -->|resources.PostCSS| C["PostCSS + Tailwind JIT Process"]
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更新時には確実に新しいファイルを読み込ませる「キャッシュバスティング」が実現します。
integrity: Fingerprintによって計算されたハッシュ値を用いて、CDN等からの改ざんを防ぐSRI属性を出力します。

6. CSS最適化における数学的パフォーマンス分析

Tailwind CSSを導入する最大のメリットの一つは、配信されるCSSファイルサイズの極小化です。これがウェブパフォーマンス（特にFirst Contentful Paint: 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$ が大きい（遅延が大きい）環境において、$S_{final}$ を数キロバイト単位まで削ぎ落とすことができるTailwind CSSのアプローチは、$\frac{S_{final}}{BW}$ の項を極限までゼロに近づけ、驚異的なスコア（Google PageSpeed Insights等）を叩き出す原動力となります。

7. 開発サーバーの起動とホットリロードの確認

全ての設定が完了したら、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">ホットリロードが瞬時に反映されることを確認してください。</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開発ライフを楽しんでください！

ブログのダークモード対応における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からクラスを切り替えるだけで、ページ全体の色合いを瞬時に変更することが可能になります。

1.1 基本的なカラーテーマの定義

まずは、:root 疑似クラスを用いて、ライトモード（デフォルト）のカラーパレットを定義します。そして、[data-theme='dark'] のような属性（あるいは .dark クラス）が付与された際に、それらの変数を上書きするという設計パターンが王道です。

 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) の活用

OSレベルでダークモードが設定されている場合、Webサイト初回訪問時から自動的にダークテーマを適用することがUXの観点から望ましいです。これを実現するのが @media (prefers-color-scheme: dark) というメディアクエリです。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


/* OSの環境設定がダークモードの場合のフォールバック */
@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'）していない限り、OSのダークモード設定を尊重して変数を上書きします。

2. 色空間の理解とアクセシビリティ（WCAG 2.1 AAA）

ダークモードの色彩設計において、単に「背景を黒く、文字を白くする」だけでは不十分です。コントラストが強すぎるとハレーションを起こして逆に読みにくくなり、コントラストが低すぎると視認性が損なわれます。Web Content Accessibility Guidelines (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ハイドレーション

ダークモード対応で最も開発者を悩ませるのが、FOUC（Flash of Unstyled Content） と呼ばれる画面のチラつき問題です。

3.1 クライアントサイドJSによるテーマ切り替えの罠

ReactやVueなどのSPA（あるいはSSGによる静的サイト）において、ユーザーの設定を localStorage に保存し、JavaScriptで読み込んでテーマを切り替える手法が一般的です。しかし、この処理をReactの useEffect などで行うと、以下のような問題が発生します。

ブラウザがライトモードのHTML/CSSを描画する。
JSのバンドルが読み込まれ、実行される。
localStorage から dark 設定を読み取る。
HTMLに dark クラスが付与され、画面が突然暗くなる（チラつき）。

3.2 完璧なFOUC防止策：CookieとSSRの活用

FOUCを完全に防止し、ハイドレーションのエラーを防ぐためのベストプラクティスは、ユーザーのテーマ設定を document.cookie に保存し、サーバーサイドレンダリング（SSR）の段階で適切なクラスを付与したHTMLを返す ことです。

以下のシーケンス図は、Cookieを利用したテーマ初期化の理想的なフローを示しています。

sequenceDiagram
participant User as "User"
participant Browser as "Browser OS"
participant Server as "Server SSR"
participant DOM as "Client DOM"
User->>Browser: "Request Page"
Browser->>Server: "GET request with Cookie (theme=dark)"
Server-->>Browser: "Return HTML with <html data-theme='dark'>"
Browser->>DOM: "Render Initial HTML (No FOUC)"
DOM->>DOM: "Execute Hydration Script"
alt "Cookie absent (First Visit)"
DOM->>Browser: "Check OS prefers-color-scheme"
Browser-->>DOM: "matchMedia result (e.g. dark)"
DOM->>DOM: "Set data-theme='dark' via inline blocking script"
end

3.3 インラインスクリプトによる防衛線（Cookieが使えない静的サイトの場合）

SSG（静的サイト生成）のみでSSRが不可能なブログ（HugoやGatsby, Astroの静的エクスポートなど）の場合は、<head> タグの内部にブロッキング実行されるインラインのJavaScriptを配置し、DOMが描画される直前にクラスを付与する手法が必須となります。

 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: バリアントを提供しており、非常に簡単にダークモードを実装できます。設定ファイル（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側では以下のようにクラスを付与するだけです。

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 : "Applies Utility Classes"

4.2 Raw 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>` タグによる画像の出し分け

ロゴ画像や、説明用の図解（背景が白で固定されている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="サイトのロゴ">
</picture>

※ただし、この方法は localStorage などによる手動トグルとは連動しない（OS設定にのみ依存する）ため、手動切り替えを実装している場合は、JSで画像の src を動的に書き換えるか、CSSクラスで display: none を切り替える必要があります。

5.3 SVGアイコンの `currentColor` 対応

アイコン等で使用するインライン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 を活用する: 色指定のハードコードを避け、セマンティックな変数名（例: --bg-primary）に抽象化する。
OKLCH 色空間を採用する: WCAG 2.1 AAA を満たすアクセシビリティの高いコントラスト比（7:1以上）を、知覚的に均一な色空間でロジカルに設計する。
FOUC対策を徹底する: SSRとCookieの連携、あるいは <head> 内のブロッキング・インラインスクリプトにより、初回ロード時の画面のチラつきを完全に排除する。
メディアとアセットの最適化: filter: brightness() や currentColor、<picture> タグを駆使して、テキスト以外の要素もダークテーマに調和させる。

単なる「色の反転」を超えたこれらの細やかな配慮こそが、ユーザーに長く愛され、目の疲れにくい優れた読書体験（リーディング・エクスペリエンス）を提供するモダンなブログの条件と言えるでしょう。これからダークモードを導入する開発者の方は、ぜひ本記事の設計パターンを参考にしてみてください。