Design 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.

Software Architecture Basics: What is Clean Architecture?

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

In modern software development, building a “resilient system” against change is a permanent challenge. Changes in business requirements, the rise of new frameworks, UI revamps, database migrations. For all these changes, an architecture that can flexibly adapt without rebuilding the entire system is required. One answer to this is Clean Architecture, advocated by Robert C. Martin (commonly known as Uncle Bob).

In this article, we will delve into the essence of Clean Architecture through its history, purpose, details of the 4 layers, the Dependency Rule, and specific implementation examples. We will provide a very deep and detailed technical explanation.

1. Problems with Traditional Architectures and the History of Clean Architecture

Historically, software architecture has experienced various paradigm shifts. In early systems, business logic, UI, and data access code were tightly coupled (so-called spaghetti code). Later, to achieve the Separation of Concerns, 3-tier architecture (presentation layer, business logic layer, data access layer) became popular.

However, the traditional 3-tier architecture had a major problem. That is, “the domain (business logic) depends on the database and frameworks”.

For example, when the business logic layer directly calls the data access layer (like ORM), changes to the database schema or ORM propagate to the business logic. In other words, a contradiction arose where the “business rules”, which are the most important and should not be changed, depended on the “infrastructure”, where technical changes are most likely to occur.

As solutions to this, architectures like the following have been devised:

Hexagonal Architecture (Ports and Adapters) - Alistair Cockburn
Onion Architecture - Jeffrey Palermo
DCI (Data, Context and Interaction) - James Coplien, Trygve Reenskaug
BCE (Boundary-Control-Entity) - Ivar Jacobson

All these architectures have the same objective. That is the “Separation of Concerns”. It is to divide the software into layers, making each independently testable and independent of external agents (UI, DB, frameworks).

Robert C. Martin integrated the concepts of these excellent architectures and summarized them into a single, practical rule, naming it “Clean Architecture”.

2. Objectives and Characteristics of Clean Architecture

Systems that adopt Clean Architecture have the following characteristics:

Independent of Frameworks: The architecture does not depend on the existence of some library of feature-laden software. This allows you to use frameworks as “tools”, rather than having to cram your system into their limited constraints.
Testable: The business rules can be tested without the UI, database, web server, or any other external element.
Independent of UI: The UI can change easily, without changing the rest of the system. For example, a Web UI could be replaced with a console UI without changing the business rules.
Independent of Database: You can swap out Oracle or SQL Server for Mongo, BigTable, CouchDB, or something else. Your business rules are not bound to the database.
Independent of any external agency: In fact, your business rules simply don’t know anything at all about the outside world.

3. The 4 Layers of Clean Architecture

Clean Architecture is generally represented by concentric circles. The closer to the center, the more the software becomes higher-level policies (highly abstract business rules). The further outwards, the more it becomes mechanisms (concrete details).

graph TD
subgraph "External Interfaces (Frameworks & Drivers)"
A["Web"]
B["UI"]
C["Database"]
D["External APIs"]
end
subgraph "Interface Adapters"
E["Controllers"]
F["Gateways"]
G["Presenters"]
end
subgraph "Application Business Rules (Use Cases)"
H["Use Case Interactors"]
end
subgraph "Enterprise Business Rules (Entities)"
I["Entities"]
end
A --> E
B --> E
C --> F
D --> F
E --> H
F --> H
G --> H
H --> I

3.1. Entities

Entities encapsulate Enterprise wide business rules. An entity can be an object with methods, or it can be a set of data structures and functions. It doesn’t matter so long as the entities could be used by many different applications in the enterprise. They are the most general and high-level rules. If you don’t have an enterprise, and are just writing a single application, then these entities are the business objects of the application. They are the least likely to change when something external changes. For example, you would not expect these objects to be affected by a change to page navigation or security.

3.2. Use Cases

The Use Case layer contains Application Business Rules. It encapsulates and implements all of the use cases of the system. Use cases orchestrate the flow of data to and from the entities, and direct those entities to use their enterprise wide business rules to achieve the goals of the use case. We do not expect changes in this layer to affect the entities. We also do not expect this layer to be affected by changes to externalities such as the database, the UI, or any of the common frameworks. The use cases are completely isolated from such concerns.

3.3. Interface Adapters

The Interface Adapters layer is a set of adapters that convert data from the format most convenient for the use cases and entities, to the format most convenient for some external agency such as the database or the web. For example, it is this layer that will wholly contain the MVC (Model-View-Controller) architecture of a GUI. The presenters, views, and controllers all belong in here. The models are likely just data structures that are passed from the controllers to the use cases, and then back from the use cases to the presenters and views. Similarly, data is converted, in this layer, from the form most convenient for entities and use cases, into the form most convenient for whatever persistence framework is being used. No code inward of this circle should know anything at all about the database.

3.4. Frameworks & Drivers

The outermost layer is generally composed of frameworks and tools such as the database, the web framework, etc. Generally you don’t write much code in this layer other than glue code that communicates to the next circle inwards. This layer is where all the details go. The web is a detail. The database is a detail. We keep these things on the outside where they can do little harm.

4. The Dependency Rule

There is a overriding rule that makes Clean Architecture work, which must never be broken. That is “The Dependency Rule”.

Source code dependencies must point only inward, toward higher-level policies.

Nothing in an inner circle can know anything at all about something in an outer circle. In particular, the name of something declared in an outer circle must not be mentioned by the code in an inner circle. That includes functions, classes, variables, or any other named software entity. By the same token, data formats used in an outer circle should not be used by an inner circle, especially if those formats are generated by a framework in an outer circle. We don’t want anything in an outer circle to impact the inner circles.

graph LR
A["Frameworks & Drivers"] -->| Depends on | B["Interface Adapters"]
B -->| Depends on | C["Use Cases"]
C -->| Depends on | D["Entities"]
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

Expressed mathematically, if we define the layer index as $L_i$, where $i=0$ is Entities (innermost layer) and $i=3$ is Frameworks (outermost layer), when a dependency from layer $L_m$ to $L_n$ exists, the following inequality must always hold true:

$$ m > n $$

In other words, the dependency vector $\vec{D}$ always points towards the center.

5. Crossing Boundaries: Dependency Inversion Principle (DIP)

When trying to adhere to the Dependency Rule, you immediately face a major problem: “What if the use case needs to fetch data from the database?”

If the use case layer (inner) directly calls the interface adapter layer (the outer Repository implementation), the dependency points outward, violating the Dependency Rule.

What solves this problem is the “D” in the SOLID principles (Dependency Inversion Principle).

Definition of the Dependency Inversion Principle (DIP)

High-level modules should not depend on low-level modules. Both should depend on abstractions.
Abstractions should not depend on details. Details should depend on abstractions.

To achieve this, we define an interface (abstraction) in the use case layer, and implement that interface in the outer layer (interface adapter). The use case layer depends only on the interface it defined, and does not depend on the concrete implementation in the outer layer.

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 (Use Case)"
note for UserRepository "Inner Layer (Use Case)"
note for UserRepositoryImpl "Outer Layer (Interface Adapters)"

In the diagram above, the runtime control flow is UseCaseInteractor $\rightarrow$ UserRepositoryImpl. However, the source code dependency is UserRepositoryImpl $\rightarrow$ UserRepository (inward). By utilizing polymorphism, we were able to point the source code dependency in the opposite direction of the control flow. This is the reason it is called the “inversion” of dependency.

6. Concrete Implementation Example in TypeScript

Here, we show a simple implementation example of Clean Architecture (user registration feature) using TypeScript.

6.1. Entities

This is the central business rule.

 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
 ) {}

 // Entity-specific business rules (e.g., name length check)
 public isValid(): boolean {
 return this.name.length >= 3 && this.email.includes('@');
 }
}

6.2. Use Cases

In the use case layer, we define the input and output data structures (DTOs) and the repository interface to invert dependencies.

 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';

// Interface defined by the use case layer
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 {
 // Depends on an abstraction (interface). Does not depend on a concrete implementation.
 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');
 }

 // Calls the outer DB save process, but the dependency points inward (to the interface)
 await this.userRepository.save(newUser);

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

6.3. Interface Adapters

We create the concrete access process to the database (Repository implementation) and the Controller that processes HTTP requests.

 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';
// Assumes a DB client which is an outer layer (Driver)
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. Main Component (Dependency Injection: DI)

At application startup, we build (wire) all dependencies. This is called the 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. Initialize driver
const dbClient = new DatabaseClient(/* connection details */);

// 2. Initialize adapter (instantiate concrete class)
const userRepository = new PostgresUserRepository(dbClient);

// 3. Initialize use case (inject concrete class into interface = DI)
const registerUserUseCase = new RegisterUserUseCase(userRepository);

// 4. Initialize controller
const userController = new UserController(registerUserUseCase);

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

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

In this way, by making the outermost “startup script” take on the dirty details (instantiating concrete classes) and passing only clean interfaces to the inner layers, the business logic is completely isolated from the outside world.

7. Mathematical Considerations of Coupling and Cohesion

In software engineering, Coupling and Cohesion are metrics used to evaluate the quality of architecture.

Coupling $C$ represents the strength of dependencies between modules. If Module $A$ depends on Module $B$, assuming the total number of dependencies in the system is $N_{dep}$ and the number of modules is $N_{mod}$, one of the metrics indicating complexity can be expressed as follows:

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

In Clean Architecture, applying DIP makes the physical dependency arrows point towards abstractions. The frequency of change of abstractions (interfaces), known as Instability ($I$), is designed to be very low.

Instability $I$ is calculated by the following formula (defined by Robert C. Martin):

$C_e$ (Efferent Coupling): Outward coupling (number of things you depend on)
$C_a$ (Afferent Coupling): Inward coupling (number of things depending on you)

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

When $I = 0$, the component is completely stable (depends on nothing, but is depended upon by others).
When $I = 1$, the component is completely unstable (is not depended upon, but depends on others).

The “Entities layer” in Clean Architecture has $C_e = 0$ (does not depend outward), so $I = 0$. That is, it is the most stable layer. Conversely, layers like “UI” or “DB” have $C_a \approx 0$ and $C_e > 0$, so $I \approx 1$, making them easily changeable (unstable) layers.

An important architectural principle, SDP (Stable Dependencies Principle), states that “dependencies must point in the direction of stability (components with smaller $I$)”. The concentric circles of Clean Architecture are exactly a visualization of this SDP, designed so that dependencies flow from the outside ($I=1$) to the inside ($I=0$).

8. Testing Strategy and Clean Architecture

One of the greatest benefits of Clean Architecture is ease of testing. Because the layers are separated, you can write tests tailored to each layer independently.

8.1. Testing Entities (Unit Test)

Because they contain pure logic with absolutely no external dependencies, neither a DB nor mocks are needed. They provide the most reliable tests that can be executed fastest.

8.2. Testing Use Cases (Unit Test with Mocks)

Since all external dependencies such as repositories are defined as interfaces, you simply need to inject (DI) mocks or in-memory implementations (Fakes) during testing. There is no need to spin up an actual database. This allows you to rapidly test complex branches and exception handling in the business logic.

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


// Example of Use Case testing (assuming Jest)
test('should throw an error when trying to register with an existing email', async () => {
 // Create a Fake repository
 const mockRepo: UserRepository = {
 findByEmail: async (email) => new User('1', 'Test', email, new Date()), // Returns an existing user
 save: async (user) => {}
 };

 const useCase = new RegisterUserUseCase(mockRepo);

 // Execute use case and assert error
 await expect(useCase.execute({ name: 'Bob', email: 'test@example.com' }))
 .rejects
 .toThrow('User already exists');
});

8.3. Testing Adapters (Integration Test)

The repository implementation classes actually connect to the database to test if the SQL is correct. Controller tests receive HTTP requests and test the part that returns JSON. Here, we do not verify the details of the business logic, but merely ensure that the “conversion” and “communication” are correct.

9. Disadvantages of Clean Architecture and When to Adopt It

Although Clean Architecture seems like a panacea, it is not a silver bullet. There are disadvantages (trade-offs) as follows:

Increase in initial learning cost and development cost: The number of files and interfaces (abstractions) increases significantly. There is a lot of “boilerplate code” such as repacking DTOs.
Overkill for small projects: For prototypes built in a few days or one-off tools where changes rarely occur, adopting this architecture often results in unnecessary costs. It is also unsuitable for simple APIs that only perform CRUD operations.

When to adopt:

Products expected to be maintained and operated over a long period (several years or more).
Systems with complex business rules where specification changes occur frequently.
When you want to divide labor in a large development team (frontend, backend, infrastructure, etc.).
When you want to model a complex business domain by combining it with Domain-Driven Design (DDD).

10. Summary

Clean Architecture is a design philosophy intended to protect the core of a system, the “business rules”, from “details” such as UI, databases, and frameworks.

At its core are The Dependency Rule and the Dependency Inversion Principle (DIP). By applying these correctly, software becomes resilient to change, easy to test, and can maintain its value over a long period.

What’s important is not blindly imitating the directory structure of Clean Architecture, but understanding the essence of “why we divide it this way” and “where the dependency arrows point”, and applying it appropriately according to the scale and complexity of your own project.

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