Tailwind CSS on kenji.blog

Hugo Theme Customization: How to Introduce Tailwind CSS

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

Introduction: The Powerful Synergy of the Static Site Generator Hugo and Tailwind CSS

In modern web frontend development, balancing performance and Developer Experience (DX) is one of the most critical challenges in every project. Combining Hugo, which boasts some of the world’s fastest build speeds among static site generators (SSGs), with Tailwind CSS, which introduced the innovative paradigm of utility-first CSS, can be considered an ultimate answer to this challenge.

Hugo is written in Go and has the astonishing performance to finish building thousands of pages in just a few seconds or even milliseconds. On the other hand, Tailwind CSS accelerates design iterations and eliminates the context switching of jumping back and forth between CSS and HTML files by allowing you to write countless predefined utility classes (such as flex, text-center, mt-4) directly into HTML.

In this article, we will thoroughly and comprehensively explain the steps to introduce Tailwind CSS into a Hugo theme and further build an advanced asset pipeline (Hugo Pipes) using PostCSS, covering everything from the foundation of the architecture to mathematical performance optimization perspectives.

1. The Transition of Utility-First CSS and Component-Oriented Design

Before diving into the Tailwind CSS installation steps, it is highly beneficial to deeply understand the history and evolution of the CSS design philosophy behind why we should use Tailwind CSS.

The Limitations of Traditional CSS Design (BEM and OOCSS)

In past web development, giving semantic class names was considered a best practice. For example, when creating a card component, HTML and CSS were separated as follows:

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">Title</h2>
 <p class="card__description">Description goes here.</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;
}
/* Detailed styles continue below */

While such BEM (Block Element Modifier) based design works when the project scale is small, it tends to cause the following problems:

Naming exhaustion and fatigue: You have to think of new class names every time you create a similar component (e.g., card-news, card-featured).
CSS Bloat: The number of CSS lines continues to increase every time a new feature is added, and once written, CSS is rarely deleted out of fear that “we don’t know where it’s used,” leading to an accumulation of dead code.
Context Switching: Because HTML structure and CSS styles are managed in separate files, the number of times you switch tabs in your editor increases exponentially.

Paradigm Shift by Tailwind CSS

Tailwind CSS solves these problems with the approach of “combining utility classes.” Using Tailwind CSS, the above card component looks like this:

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">Title</h2>
 <p class="mt-2 text-gray-600">Description goes here.</p>
 </div>
</div>

Since the class names themselves represent the specific values of styles (e.g., p-6 is padding: 1.5rem;), you can predict the final rendering result just by looking at the HTML. Furthermore, Tailwind’s JIT (Just-In-Time) compiler extracts only the actually used classes into the production CSS file, reducing the CSS file size to the absolute minimum.

2. Hugo Pipes and PostCSS Architecture

To integrate Tailwind CSS into Hugo, you need to understand the asset processing pipeline called Hugo Pipes. Hugo Pipes is a powerful feature that completes all asset-related processing internally within Hugo, such as compiling Sass/SCSS, bundling and minifying JavaScript, and executing the PostCSS we will use this time.

PostCSS is a tool for transforming CSS using JavaScript plugins. Tailwind CSS itself actually operates as a PostCSS plugin.

AST (Abstract Syntax Tree) Transformation Mechanism by PostCSS

Understanding how PostCSS processes CSS is highly useful for troubleshooting. The following Mermaid diagram shows the pipeline of how PostCSS reads a CSS file, transforms it through plugins, and outputs the final 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: Analyzes the inputted raw CSS string and converts it into an AST (Abstract Syntax Tree), a data structure that can be manipulated programmatically.
Plugins:
- Tailwind CSS: Scans template files (HTML or Markdown) and adds the used utility classes as nodes to the AST. It also expands the @tailwind directive.
- Autoprefixer: References the Can I Use database and adds vendor prefixes (such as -webkit-, -moz-) to the AST properties as needed.
Stringifier: Converts the transformed AST back into a browser-readable CSS string and outputs it.

3. Environment Setup and Prerequisites

Now, let’s move on to the actual installation steps. First, we will check if the necessary software is installed.

Prerequisites

Hugo Extended Version: You must have the Extended version, not the regular Hugo, as it includes Sass/SCSS processing capabilities and native PostCSS integration features. Run the following command in your terminal and verify that the version information contains the string extended.
1 2 3

hugo version # Expected output example: # hugo v0.121.2-4146... windows/amd64 BuildDate=... VendorInfo=gohugoio +extended
Node.js and npm: Dependencies like Tailwind CSS and PostCSS run on Node.js. Make sure Node.js (LTS version recommended) is installed.
1 2

node -v npm -v

Installing npm Packages

Initialize npm in the project’s root directory (where Hugo’s configuration file hugo.toml is located) and install the required packages.

1
2
3
4
5


# Generate package.json
npm init -y

# Install Tailwind CSS, PostCSS, and Autoprefixer as development dependencies
npm install -D tailwindcss postcss postcss-cli autoprefixer

[!IMPORTANT] If postcss-cli is not installed, errors may occur when invoking PostCSS from inside Hugo. Because Hugo Pipes internally uses postcss-cli, be absolutely sure to install it.

4. Building Configuration Files (PostCSS & Tailwind CSS)

Once the package installation is complete, create two important configuration files that control the project’s behavior. Place them in the project root directory.

Creating tailwind.config.js

Run the following command in your terminal to generate the default configuration file.

1

npx tailwindcss init

Open the generated tailwind.config.js in your editor and set the content property. This is extremely important. Tailwind analyzes the files at the paths specified here and extracts the classes being used. Precisely specify the layout files and content files according to your Hugo project structure.

 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 = {
 // Specify targets to scan according to Hugo's directory structure
 content: [
 "./content/**/*.md",
 "./content/**/*.html",
 "./layouts/**/*.html",
 "./assets/**/*.js",
 // If you are using a theme, you also need to include the theme's directory
 // "./themes/my-theme/layouts/**/*.html",
 ],
 theme: {
 extend: {
 // Extend custom colors and fonts here
 colors: {
 'brand-primary': '#3490dc',
 'brand-secondary': '#ffed4a',
 },
 fontFamily: {
 'sans': ['Helvetica Neue', 'Arial', 'Hiragino Kaku Gothic ProN', 'Meiryo', 'sans-serif'],
 }
 },
 },
 plugins: [
 // Add official plugins as needed (e.g., Typography plugin)
 // require('@tailwindcss/typography'),
 ],
}

Creating postcss.config.js

Next, create postcss.config.js in the project root, which defines which plugins PostCSS will run and in what order.

1
2
3
4
5
6


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

With this configuration, when Hugo calls PostCSS, it will first apply Tailwind CSS processing and then use Autoprefixer to add vendor prefixes.

5. Building the CSS Asset Pipeline in Hugo

Once the configuration is complete, it is finally time to integrate Tailwind CSS into the Hugo theme side.

5-1. Creating the Entry Point CSS File

Create the entry point CSS file in the assets/css/ directory (create it if it doesn’t exist). We will name it main.css here.

File Path: assets/css/main.css

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


/* Load Tailwind's base styles (reset CSS, etc.) */
@tailwind base;

/* Load component classes */
@tailwind components;

/* Load utility classes */
@tailwind utilities;

/* If you need your own custom CSS, you can add it here,
 but it is recommended to handle it in tailwind.config.js's extend as much as possible */
@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. Editing the Layout File (head.html)

Next, we will load the above CSS file from a Hugo template and write the pipeline to process it with PostCSS. Generally, you edit the partial template that defines the <head> tag (e.g., layouts/partials/head.html).

File Path: 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>

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

 <!-- Define PostCSS options -->
 {{ $options := dict "inlineImports" true }}
 {{ $css = $css | resources.PostCSS $options }}

 <!-- Asset optimization pipeline for the Production environment -->
 {{ if hugo.IsProduction }}
 <!-- 1. Minify -->
 {{ $css = $css | minify }}
 <!-- 2. Fingerprint (add hash for cache busting) -->
 {{ $css = $css | fingerprint "sha512" }}
 <!-- 3. Output the tag including SRI (Subresource Integrity) -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}" crossorigin="anonymous">
 {{ else }}
 <!-- In the Development environment, output as-is without minifying (prioritize build speed) -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}">
 {{ end }}
</head>

Pipeline Explanation and Mermaid Diagram Illustration

We will diagrammatically explain the sequence of pipeline processing for how the above Go template code handles the CSS file.

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 (Production environment)" --> E["minify (remove spaces/newlines)"]
E --> F["fingerprint (calculate hash)"]
F --> G["public/css/main.[hash].css (with SRI)"]
D -- "No (Development environment)" --> H["public/css/main.css"]

resources.Get: Looks for the specified file within the assets directory and loads it as a resource object in memory.
resources.PostCSS: Refers to postcss.config.js in the project root and applies Tailwind CSS and Autoprefixer processing to the CSS source code. In the development environment (hugo server), JIT mode kicks in and rapidly generates only the necessary classes when files are modified.
minify: During production builds (like hugo --environment production), it removes unnecessary whitespace and comments to minimize the file size.
fingerprint: Calculates a SHA hash based on the file’s contents and appends it to the filename (e.g., main.ab12cd...css). This enables “cache busting,” allowing you to utilize strong browser caching while ensuring a new file is reliably loaded when the CSS is updated.
integrity: Outputs an SRI attribute using the hash value calculated by Fingerprint to prevent tampering from CDNs and other sources.

6. Mathematical Performance Analysis in CSS Optimization

One of the greatest benefits of introducing Tailwind CSS is the minimization of the delivered CSS file size. Let’s use a mathematical model to quantitatively analyze how this impacts web performance (especially First Contentful Paint: FCP).

CSS File Size Reduction Model

With traditional CSS frameworks (like Bootstrap), the entire volume is loaded, including unused styles, so the file size $S_{original}$ tends to be large (around 150KB to 200KB). Let $S_{purged}$ be the size after purging unused classes with the Tailwind CSS JIT compiler, and $R_{purge}$ be the reduction rate. This can be expressed as follows:

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

In a typical project, $R_{purge}$ reaches close to $0.9$ (a 90% reduction), and $S_{purged}$ fits into just around 10KB to 20KB.

Furthermore, compression by Brotli or Gzip is performed on the server side upon delivery. Assuming a compression rate $R_{compress}$ (usually around 0.7 to 0.8), the final payload size $S_{final}$ flowing through the network is calculated with the following formula:

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

Critical Rendering Path and Network Latency

The time it takes for a browser to render the first piece of content on the screen (FCP) can be approximated as the sum of the HTML download time, CSS download time, and rendering time.

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

Where:

$RTT$ : Round Trip Time (communication latency with the server)
$BW$ : Network Bandwidth

In environments with narrow $BW$ and large $RTT$ (high latency) such as mobile networks, Tailwind CSS’s approach, which can strip $S_{final}$ down to mere kilobytes, pushes the $\frac{S_{final}}{BW}$ term extremely close to zero, acting as the driving force to achieve phenomenal scores (e.g., Google PageSpeed Insights).

7. Starting the Development Server and Checking Hot Reloading

Once all configurations are complete, start the Hugo development server and check if Tailwind CSS is working properly.

1

hugo server -D

Access http://localhost:1313/ in your browser and verify that the site is displayed. Try opening a Markdown content file or a Hugo template (files under layouts/) and adding some classes.

1
2
3
4
5


<!-- Example of applying Tailwind classes for testing -->
<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">Please verify that hot reloading is instantly reflected.</p>
</div>

The moment you save the file, Hugo’s powerful file watcher and Tailwind’s JIT compiler will work together to rebuild the CSS in milliseconds, allowing you to experience the thrill of the browser automatically reloading (hot reloading).

Troubleshooting: When Styles Are Not Reflected

If your changes are not reflected, check the following points.

The content path setting in tailwind.config.js If the scanned file paths are incorrect, Tailwind cannot detect the classes used within those files and will not output them to the CSS. Especially if you are using a theme, make sure the theme directory path is not missing.
PostCSS Errors If an error like Error: failed to transform resource: PostCSS not found appears in the Hugo server logs in your terminal, npm install might not have executed correctly, or postcss-cli might be missing.
Clearing the Hugo Cache Rarely, old CSS remains due to Hugo’s cache. Try stopping the server and starting it with hugo server --ignoreCache, or deleting the OS temporary directory (e.g., /tmp/hugo_cache/).

8. Production Builds and Further Advancements

When deploying your site to a production server (Netlify, Vercel, GitHub Pages, Cloudflare Pages, etc.), you need to set environment variables to run the production optimization pipeline.

1
2


# Example of a production build command
NODE_ENV=production hugo --minify --environment production

By adding the --environment production flag, the {{ if hugo.IsProduction }} block in head.html is executed, and CSS minification and fingerprinting will take place.

Styling Markdown with the Typography Plugin

In blogs and documentation sites like those made with Hugo, you cannot directly add classes to pure HTML elements (<h1>, <p>, <ul>, etc.) generated from Markdown. The official Tailwind Typography plugin is extremely useful in such cases.

Install the plugin

1

npm install -D @tailwindcss/typography

Add it to tailwind.config.js

1
2
3
4
5
6


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

Applying it in templates Simply adding the prose class (and your choice of color or size variants) to the container element that outputs the body of the article will apply beautiful default styles.
1 2 3

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

This completely eliminates the need to manually write complex CSS selectors (e.g., .article-content h2 { ... }) and perfectly preserves component modularity.

9. Conclusion: Completing a Highly Maintainable Frontend Ecosystem

Great job. You have now completed a perfect web development asset pipeline, combining Hugo’s ultra-fast static site generation engine, Tailwind CSS’s modern styling capabilities, and PostCSS’s extensibility.

The brilliance of this architecture is that “you only have to configure it once.” Once the pipeline is built, developers never have to open a CSS file; by simply writing intuitive utility classes into HTML or Markdown templates, they can build complex UIs at astonishing speeds.

Moreover, because the output CSS size is always minimized, it directly contributes to improving Core Web Vitals scores and works very advantageously from an SEO perspective.

The combination of Hugo and Tailwind CSS will remain one of the “best choices” for every project, from personal tech blogs to large corporate websites. Please take advantage of this powerful toolchain and enjoy a comfortable web development life!

Key Points in CSS Design for Blog Dark Mode Support

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

In modern web development, dark mode support has shifted from a mere “nice to have” feature to a “must have” requirement for improving user experience (UX). Particularly for media that assume long periods of text reading, such as blogs and documentation sites, dark mode support is extremely important because it helps reduce user eye strain and conserves device battery consumption.

In this article, I will delve deeply into the unavoidable technical challenges and key points of highly maintainable CSS design for blog dark mode support from a frontend engineer’s perspective. It covers everything about dark mode implementation: utilizing CSS Custom Properties (CSS variables), advanced JavaScript control and SSR integration to prevent FOUC (Flash of Unstyled Content), color design (RGB, HSL, and the latest OKLCH) to ensure accessibility (WCAG 2.1 AAA), and even practical code examples using Tailwind CSS.

1. Basics of Theme Design with CSS Custom Properties (CSS Variables)

Currently, the most standard and powerful approach for implementing dark mode is the use of CSS Custom Properties (CSS variables). While variables in CSS preprocessors like Sass ($color) are statically resolved at compile time, CSS variables are dynamically resolved and overridden in the browser’s runtime. This makes it possible to instantly change the overall page color simply by toggling a class from JavaScript.

1.1 Basic Color Theme Definition

First, we define a color palette for the light mode (default) using the :root pseudo-class. Then, the standard design pattern is to override those variables when an attribute like [data-theme='dark'] (or a .dark class) is applied.

 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


/* Light mode (default) variable definitions */
:root {
 --color-bg-primary: #ffffff;
 --color-bg-secondary: #f3f4f6;
 --color-text-primary: #111827;
 --color-text-secondary: #4b5563;
 --color-accent: #3b82f6;
 --color-border: #e5e7eb;
}

/* Variable overrides for dark mode */
[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;
}

/* Actual application */
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);
}

By completely separating layout and typography specifications from color (theme) specifications in this manner, the maintainability of your CSS improves dramatically.

1.2 Utilizing @media (prefers-color-scheme: dark)

When dark mode is set at the OS level, it is desirable from a UX perspective to automatically apply the dark theme from the first visit to the website. This is achieved using the @media (prefers-color-scheme: dark) media query.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


/* Fallback when the OS environment setting is dark mode */
@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;
 }
}

With this syntax, the variables are overridden in deference to the OS dark mode settings, unless the user has explicitly selected light mode (data-theme='light').

2. Understanding Color Spaces and Accessibility (WCAG 2.1 AAA)

In the color design of dark mode, simply “making the background black and text white” is insufficient. If the contrast is too strong, it causes halation and ironically becomes harder to read; if the contrast is too low, visibility is compromised. The Web Content Accessibility Guidelines (WCAG) strictly define the contrast ratio required to ensure visibility.

2.1 WCAG Contrast Ratio Calculation Formula

The Contrast Ratio $CR$ in WCAG is defined using the Relative Luminance of the background and foreground colors as follows:

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

Here, $L_{lighter}$ is the relative luminance of the lighter color, and $L_{darker}$ is the relative luminance of the darker color (values range from 0.0 to 1.0). To achieve WCAG 2.1 Level AAA, a contrast ratio of 7:1 or higher for normal text and 4.5:1 or higher for large text is required.

The relative luminance $L$ is calculated from the RGB values of the sRGB color space using the following complex formula:

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

For each component ($R, G, B$), using the normalized value obtained by dividing the original 8-bit value ($R_{sRGB}$) by 255, the following transformation is performed to decode gamma correction:

$$ 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} $$

Performing this calculation manually is difficult, but by utilizing color design tools, you can mechanically select colors that satisfy a contrast ratio of 7:1 ($CR \ge 7.0$).

2.2 HSL vs RGB vs OKLCH

When creating a color palette, RGB and HSL used to be the mainstream. However, they have significant flaws in terms of “perceptual uniformity.”

RGB: It represents the mechanical three primary colors of light, making it difficult for humans to intuitively make adjustments like “make it lighter” or “make it darker.”
HSL: Uses Hue, Saturation, and Lightness, but the “Lightness (L)” in HSL does not match the perceptual brightness of the human eye. For example, pure yellow and pure blue with 50% lightness in HSL have the same brightness numerically, but the yellow appears overwhelmingly brighter to the human eye.
OKLCH: The latest color space introduced in CSS Color Module Level 4 recently. Composed of Lightness (perceptual lightness), Chroma (saturation), and Hue, it perfectly matches human visual characteristics (perceptually uniform).

By using OKLCH, you can maintain the same perceptual Lightness even if you change the Hue, making color palette generation for dark mode extremely predictable and safe.

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


/* Example of CSS variable definition using OKLCH */
:root {
 /* Set base lightness high and keep chroma moderate for light mode */
 --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"] {
 /* For dark mode, just invert the lightness to easily maintain perceptual contrast */
 --bg-base: oklch(0.20 0.02 250);
 --text-base: oklch(0.95 0.01 250);
 --primary-brand: oklch(0.75 0.15 250); /* Slightly lighter for dark mode to ensure visibility */
}

By adopting OKLCH like this, you can simply build logic to ensure consistent contrast ratios (WCAG AAA level) across multiple themes.

3. Preventing FOUC (Flash of Unstyled Content) and SSR Hydration

The most troubling issue for developers regarding dark mode support is the screen flickering problem known as FOUC (Flash of Unstyled Content).

3.1 The Trap of Client-Side JS Theme Switching

In SPAs like React or Vue (or static sites generated by SSG), it is common to save user settings in localStorage and switch themes by reading them with JavaScript. However, if this process is done using React’s useEffect, the following problems occur:

The browser renders the light mode HTML/CSS.
The JS bundle is loaded and executed.
The dark setting is read from localStorage.
The dark class is applied to the HTML, and the screen suddenly goes dark (flickering).

3.2 The Perfect Anti-FOUC Measure: Utilizing Cookies and SSR

The best practice for completely preventing FOUC and avoiding hydration errors is to save the user’s theme setting in a document.cookie and return HTML with the appropriate class applied during Server-Side Rendering (SSR).

The sequence diagram below illustrates the ideal flow of theme initialization using cookies.

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 Defense Line with Inline Scripts (For Static Sites Without Cookies)

For blogs where SSR is impossible and only SSG (Static Site Generation) is used (such as Hugo, Gatsby, or Astro’s static exports), it is essential to place an inline, blocking JavaScript execution inside the <head> tag to apply the class right before the DOM is rendered.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- Place at the end inside <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>

Since this small script blocks browser rendering and executes immediately, the data-theme attribute is already set by the time the screen is rendered, completely preventing screen flickering (FOUC).

4. Implementation Approaches with Tailwind CSS and Raw SCSS/CSS

When incorporating dark mode into an actual project, it is necessary to understand the approaches for each tool.

4.1 Dark Mode in Tailwind CSS

Tailwind CSS provides a dark: variant by default, allowing for extremely easy dark mode implementation. You set the darkMode property in the configuration file (tailwind.config.js).

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


// tailwind.config.js
module.exports = {
 // 'media' (depends on OS settings) or 'class' (can be toggled manually)
 darkMode: 'class',
 theme: {
 extend: {
 colors: {
 /* Extend Tailwind's color palette using CSS variables */
 primary: 'rgb(var(--color-primary) / <alpha-value>)',
 background: 'rgb(var(--color-background) / <alpha-value>)',
 }
 }
 }
}

On the HTML side, you just add classes like below.

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>

However, writing dark:bg-xxx on every element can cause components to become bloated. For large blogs or apps, a hybrid design (semantic color design) where CSS variables serve as the foundation, and Tailwind references those CSS variables, is recommended.

Below is a class diagram illustrating the inheritance of CSS variables and application layers.

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 Implementation with Raw SCSS/CSS (Using Mixins)

In projects that do not use Tailwind and write custom SCSS, @mixin is utilized to encapsulate dark mode styles.

 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 definition */
@mixin dark-mode {
 /* Supports both [data-theme='dark'] attribute and OS settings */
 [data-theme='dark'] & {
 @content;
 }
 @media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) & {
 @content;
 }
 }
}

/* Usage example */
.card {
 background-color: #ffffff;
 color: #333333;
 border: 1px solid #eeeeee;

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

This method is intuitive, but because it tends to bloat the compiled CSS file size (as media queries are duplicated for each selector), moving to a design centered around CSS variables (Custom Properties) is the current trend.

5. Optimizing Images and SVGs for Dark Mode

Even after color design for text and backgrounds is complete, if content images and icons (SVGs) remain in light mode, they will appear glaringly out of place during dark mode. Optimizing these is also essential.

5.1 CSS Filters to Reduce Image Brightness

Bitmap images, such as photos, can sometimes be too glaring if displayed as-is in dark mode. By using the CSS filter property to slightly reduce the brightness and contrast of the image, you can make it blend naturally into the dark theme UI.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[data-theme='dark'] img:not([src*=".svg"]) {
 /* Reduce brightness and slightly increase contrast */
 filter: brightness(0.8) contrast(1.1);
 transition: filter 0.3s ease;
}

[data-theme='dark'] img:hover {
 /* Revert to original brightness on hover (for when users want to see details) */
 filter: brightness(1) contrast(1);
}

5.2 Conditional Image Rendering via the `<picture>` Tag

For logo images or explanatory diagrams (like JPEGs with a fixed white background), applying filters alone is not enough. In such cases, the correct approach is to use the HTML <picture> element and media queries to serve a different image file specifically for dark mode.

1
2
3
4
5
6


<picture>
 <!-- Display this for users with OS dark mode settings -->
 <source srcset="/img/logo-dark.png" media="(prefers-color-scheme: dark)">
 <!-- Default (light mode) -->
 <img src="/img/logo-light.png" alt="Site Logo">
</picture>

*Note: Since this method does not sync with manual toggles via localStorage or similar (it relies solely on OS settings), if you have implemented manual switching, you will need to either dynamically rewrite the image’s src using JS or toggle display: none using CSS classes.

5.3 `currentColor` Support for SVG Icons

For inline SVGs used as icons, the smartest approach is to link their fill color to the parent element’s text color. Specify currentColor for the SVG’s fill or stroke attributes.

1
2
3
4


<!-- The value of the CSS color property (e.g., var(--text-primary)) is automatically applied -->
<svg viewBox="0 0 24 24" fill="currentColor">
 <path d="M12 2L2 22h20L12 2z" />
</svg>

With this, if the site switches to dark mode and the parent element’s text color turns to a shade of white, the SVG icon will also automatically change to a shade of white.

6. Conclusion: Toward Sustainable Dark Mode Design

To implement high-quality dark mode in blogs and web applications, a CSS design that covers the following points is essential:

Utilize CSS Custom Properties: Avoid hardcoding colors and abstract them into semantic variable names (e.g., --bg-primary).
Adopt the OKLCH Color Space: Logically design highly accessible contrast ratios (7:1 or higher) that satisfy WCAG 2.1 AAA using a perceptually uniform color space.
Thoroughly implement anti-FOUC measures: Completely eliminate screen flickering on initial load through SSR and cookie integration, or by using blocking inline scripts inside the <head>.
Optimize media and assets: Master filter: brightness(), currentColor, and <picture> tags to harmonize non-text elements with the dark theme.

It is precisely these meticulous considerations—going beyond mere “color inversion”—that can be called the prerequisites of a modern blog that provides an excellent, eye-friendly reading experience cherished by users for a long time. For developers looking to introduce dark mode, please be sure to refer to the design patterns in this article.