Tailwind CSS on kenji.blog

Настройка темы Hugo: Как внедрить Tailwind CSS

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

Введение: Мощная синергия генератора статических сайтов Hugo и Tailwind CSS

В современной веб-разработке фронтенда баланс между производительностью и удобством разработки (DX: Developer Experience) является одной из важнейших задач в любом проекте. Комбинация Hugo, который может похвастаться самой высокой скоростью сборки в мире среди генераторов статических сайтов (SSG), и Tailwind CSS, принесшего инновационную парадигму utility-first, является одним из идеальных решений этой проблемы.

Hugo написан на языке Go и обладает потрясающей производительностью, позволяющей завершить сборку даже для сайтов с тысячами страниц всего за несколько секунд или миллисекунд. С другой стороны, Tailwind CSS ускоряет процесс дизайна за счет прямого использования в HTML огромного количества предопределенных утилитарных классов (таких как flex, text-center, mt-4), что устраняет необходимость постоянно переключаться между CSS и HTML файлами.

В этой статье мы подробно и досконально рассмотрим процесс интеграции Tailwind CSS в тему Hugo, а также создание продвинутого конвейера ресурсов (Hugo Pipes) с использованием PostCSS — от основ архитектуры до математической оптимизации производительности.

1. Эволюция utility-first CSS и компонентно-ориентированного подхода

Прежде чем перейти к шагам по интеграции Tailwind CSS, очень полезно глубоко понять историю и эволюцию философии дизайна CSS, стоящей за тем, почему мы должны использовать Tailwind CSS.

Ограничения традиционного дизайна CSS (BEM и OOCSS)

В прошлом в веб-разработке лучшей практикой считалось использование семантических имен классов. Например, при создании компонента карточки 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. Кроме того, благодаря компилятору JIT (Just-In-Time) Tailwind в продакшн CSS файл извлекаются только те классы, которые фактически используются, что сводит размер файла CSS к минимуму.

2. Архитектура Hugo Pipes и PostCSS

Чтобы интегрировать Tailwind CSS в Hugo, необходимо понять конвейер обработки ресурсов, называемый Hugo Pipes. Hugo Pipes — это мощная функция, которая позволяет Hugo выполнять всю обработку ресурсов внутри себя, включая компиляцию Sass/SCSS, сборку и минификацию JavaScript, а также выполнение PostCSS, который мы будем использовать.

PostCSS — это инструмент для преобразования CSS с помощью плагинов JavaScript. Сам Tailwind CSS фактически работает как плагин для PostCSS.

Механизм преобразования AST (Абстрактного синтаксического дерева) с помощью PostCSS

Понимание того, как PostCSS обрабатывает CSS, очень полезно при устранении неполадок. Следующая диаграмма Mermaid показывает конвейер, в котором PostCSS читает CSS-файл, преобразует его через плагины и выводит финальный CSS.

flowchart TD
A["Сырой CSS (styles.css)"] -->|Parser| B["AST (Абстрактное синтаксическое дерево)"]
B --> C["Плагин 1: Tailwind CSS"]
C --> D["Плагин 2: Autoprefixer"]
D --> E["Плагин N: cssnano"]
E -->|Stringifier| F["Скомпилированный и оптимизированный CSS"]

Parser (Парсер): Анализирует входящую необработанную строку CSS и преобразует ее в AST (абстрактное синтаксическое дерево), структуру данных, которой можно управлять программно.
Plugins (Плагины):
- Tailwind CSS: Сканирует файлы шаблонов (HTML или Markdown) и добавляет используемые утилитарные классы в качестве узлов в AST. Он также разворачивает директивы @tailwind.
- Autoprefixer: Обращается к базе данных Can I Use и при необходимости добавляет вендорные префиксы (например, -webkit-, -moz-) к свойствам AST.
Stringifier (Генератор строк): Преобразует готовое AST обратно в строку CSS, понятную браузеру, и выводит ее.

3. Настройка среды и предварительные условия

Давайте перейдем к фактическим шагам по установке. Сначала убедитесь, что у вас установлено необходимое программное обеспечение.

Обязательные требования

Hugo Extended Version: Обязательно нужна Extended версия, которая включает в себя возможности обработки Sass/SCSS и встроенную интеграцию PostCSS, а не обычный Hugo. Выполните следующую команду в терминале и убедитесь, что строка extended присутствует в информации о версии.
1 2 3

hugo version # Ожидаемый вывод: # hugo v0.121.2-4146... windows/amd64 BuildDate=... VendorInfo=gohugoio +extended
Node.js и npm: Зависимости, такие как Tailwind CSS и PostCSS, работают на Node.js. Убедитесь, что установлен Node.js (рекомендуется версия LTS).
1 2

node -v npm -v

Установка пакетов npm

Инициализируйте npm в корневом каталоге проекта (там, где находится файл конфигурации Hugo hugo.toml) и установите необходимые пакеты.

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 не установлен, могут возникнуть ошибки при вызове PostCSS из Hugo. Обязательно установите его, так как Hugo Pipes внутренне использует postcss-cli.

4. Создание конфигурационных файлов (PostCSS и Tailwind CSS)

После завершения установки пакетов создайте два важных конфигурационных файла, которые будут управлять поведением проекта. Разместите их в корневом каталоге проекта.

Создание 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.config.js, который определяет, какие плагины и в каком порядке будет выполнять PostCSS.

1
2
3
4
5
6


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

Благодаря этой настройке, когда Hugo вызывает PostCSS, сначала применяется Tailwind CSS, а затем Autoprefixer добавляет вендорные префиксы.

5. Создание конвейера ресурсов CSS в Hugo

После завершения настроек пришло время интегрировать Tailwind CSS в тему Hugo.

5-1. Создание CSS файла точки входа

Создайте CSS-файл, который послужит точкой входа, в каталоге assets/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 можно добавить здесь, но
 рекомендуется использовать extend в tailwind.config.js по мере возможности */
@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)

Далее загрузите вышеуказанный CSS-файл из шаблона Hugo и напишите конвейер для его обработки с помощью PostCSS. Обычно редактируется частичный шаблон (например, layouts/partials/head.html), который определяет содержимое тега <head>.

Путь к файлу: 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"]
B -->|resources.PostCSS| C["Процесс PostCSS + Tailwind JIT"]
C --> D{"hugo.IsProduction ?"}
D -- "Да (Продакшн)" --> E["minify (удаление пробелов и переносов строк)"]
E --> F["fingerprint (вычисление хеша)"]
F --> G["public/css/main.[hash].css (с SRI)"]
D -- "Нет (Разработка)" --> H["public/css/main.css"]

resources.Get: Ищет указанный файл в каталоге assets и загружает его как объект ресурса в память.
resources.PostCSS: Применяет обработку Tailwind CSS и Autoprefixer к исходному коду CSS, ссылаясь на postcss.config.js в корне проекта. В среде разработки (hugo server) работает режим JIT, быстро генерирующий только необходимые классы при изменении файлов.
minify: При сборке для продакшна (например, hugo --environment production) удаляет ненужные пробелы и комментарии, сводя к минимуму размер файла.
fingerprint: Вычисляет SHA-хеш на основе содержимого файла и добавляет его к имени файла (например, main.ab12cd...css). Это позволяет использовать мощное кэширование браузера и одновременно обеспечивает «сброс кэша» — надежную загрузку нового файла при обновлении CSS.
integrity: Выводит атрибут SRI с использованием хеш-значения, вычисленного Fingerprint, для предотвращения подделки данных при доставке через CDN и т. д.

6. Математический анализ производительности при оптимизации CSS

Одним из самых больших преимуществ внедрения Tailwind CSS является минимизация размера доставляемого CSS-файла. Давайте с помощью математической модели количественно проанализируем, как это влияет на производительность веб-сайта (особенно на First Contentful Paint: FCP).

Модель уменьшения размера CSS файла

В традиционных CSS-фреймворках (например, Bootstrap) размер файла $S_{original}$ обычно велик (около 150-200 КБ), поскольку загружаются все стили, включая неиспользуемые. Если обозначить размер файла после удаления неиспользуемых классов (Purge) компилятором JIT Tailwind CSS как $S_{purged}$, и коэффициент уменьшения как $R_{purge}$, то это можно выразить следующей формулой:

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

В типичном проекте $R_{purge}$ достигает почти $0.9$ (уменьшение на 90%), а $S_{purged}$ составляет всего лишь 10-20 КБ.

Кроме того, при доставке файлы сжимаются на стороне сервера с помощью Brotli или Gzip. Если коэффициент сжатия равен $R_{compress}$ (обычно около 0.7-0.8), конечный размер полезной нагрузки $S_{final}$, передаваемой по сети, вычисляется по следующей формуле:

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

Критический путь рендеринга и сетевая задержка

Время до того момента, когда браузер отрисует первый контент на экране (FCP), можно приблизительно оценить как сумму времени загрузки HTML, времени загрузки CSS и времени рендеринга.

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

Где:

$RTT$ : Round Trip Time (время круговой задержки связи с сервером)
$BW$ : Пропускная способность сети (Bandwidth)

В средах, таких как мобильные сети, где $BW$ ограничена, а $RTT$ велико (высокая задержка), подход Tailwind CSS, позволяющий сократить $S_{final}$ до нескольких килобайт, сводит член $\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 — это потрясающе!</h1>
 <p class="mt-4 text-lg font-medium">Убедитесь, что горячая перезагрузка применяется мгновенно.</p>
</div>

Как только вы сохраните файл, мощный наблюдатель файлов Hugo и компилятор JIT Tailwind будут работать вместе, чтобы за миллисекунды перестроить CSS. Вы должны ощутить удовольствие от автоматической перезагрузки браузера (горячей перезагрузки).

Устранение неполадок: если стили не применяются

Если изменения не отображаются, проверьте следующие пункты:

Настройка путей content в tailwind.config.js Если пути к сканируемым файлам указаны неверно, Tailwind не сможет обнаружить используемые в них классы и не выведет их в CSS. Особенно если вы используете тему, убедитесь, что пути к каталогу темы не пропущены.
Ошибки PostCSS Если в журнале сервера Hugo в терминале появляется ошибка типа Error: failed to transform resource: PostCSS not found, возможно, npm install не был выполнен корректно или отсутствует postcss-cli.
Очистка кэша Hugo В редких случаях кэш Hugo может стать причиной того, что останется старый CSS. Остановите сервер и запустите его с помощью hugo server --ignoreCache или попробуйте удалить временный каталог ОС (например, /tmp/hugo_cache/).

8. Сборка для продакшна и дальнейшие улучшения

При развертывании сайта на рабочем сервере (Netlify, Vercel, GitHub Pages, Cloudflare Pages и т. д.) необходимо настроить переменные окружения и запустить конвейер оптимизации для продакшна.

1
2


# Пример команды для продакшн сборки
NODE_ENV=production hugo --minify --environment production

Добавление флага --environment production приведет к выполнению блока {{ if hugo.IsProduction }} в head.html, где будет выполнена минификация CSS и добавление Fingerprint.

Стилизация Markdown с помощью плагина Typography

На сайтах блогов или документации, таких как Hugo, вы не можете напрямую добавлять классы к чистым HTML-элементам (таким как <h1>, <p>, <ul>), сгенерированным из Markdown. В таких случаях очень полезен официальный плагин Typography от Tailwind.

Установка плагина

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.

Преимущество этой архитектуры в том, что «настраивать нужно только один раз». Как только конвейер будет создан, разработчики смогут создавать сложные пользовательские интерфейсы с невероятной скоростью, просто прописывая интуитивно понятные утилитарные классы в шаблонах HTML или Markdown, даже не открывая CSS-файл.

Кроме того, поскольку размер выходного CSS всегда минимизирован, это напрямую улучшает оценки Core Web Vitals и очень выгодно с точки зрения SEO.

Комбинация Hugo и Tailwind CSS, несомненно, останется одним из «лучших выборов» для любого проекта, от личного технического блога до крупного корпоративного сайта. Обязательно воспользуйтесь этим мощным набором инструментов и наслаждайтесь комфортной веб-разработкой!

Ключевые моменты CSS-проектирования для поддержки темного режима в блоге

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

В современной веб-разработке поддержка темного режима (Dark Mode) превратилась из просто «приятного дополнения» (Nice to have) в «обязательное требование» (Must have) для улучшения пользовательского опыта (UX). В частности, для медиа, предполагающих длительное чтение текста, таких как блоги и сайты с документацией, важность поддержки темного режима крайне высока, поскольку он снижает нагрузку на глаза пользователей и уменьшает расход заряда батареи устройств.

В этой статье мы глубоко погрузимся в технические проблемы, которых не избежать при внедрении темного режима в блог, и ключевые моменты CSS-проектирования с высокой степенью поддерживаемости с точки зрения фронтенд-инженера. Мы охватим все аспекты реализации темного режима: использование CSS Custom Properties (CSS-переменных), продвинутое управление JavaScript и интеграцию с SSR для предотвращения FOUC (Flash of Unstyled Content), цветовой дизайн (RGB, HSL и новейший OKLCH) для обеспечения доступности (WCAG 2.1 AAA), а также практические примеры кода с использованием Tailwind CSS.

1. Основы проектирования тем с использованием CSS Custom Properties (CSS-переменных)

В настоящее время наиболее стандартным и мощным методом реализации темного режима является подход с использованием CSS Custom Properties (CSS-переменных). В отличие от переменных в CSS-препроцессорах, таких как Sass ($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)

Если темный режим установлен на уровне ОС, с точки зрения UX желательно автоматически применять темную тему с момента первого посещения веб-сайта. Это достигается с помощью медиа-запроса @media (prefers-color-scheme: dark).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


/* Фолбэк, если в настройках ОС выбран темный режим */
@media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
 }
}

При таком написании переменные переопределяются с учетом настроек темного режима ОС, если только пользователь явно не выбрал светлый режим (data-theme='light').

2. Понимание цветового пространства и доступность (WCAG 2.1 AAA)

При цветовом проектировании для темного режима недостаточно просто «сделать фон черным, а текст белым». Если контраст слишком сильный, это вызовет ореол и усложнит чтение, а если контраст слишком низкий, пострадает видимость. В Web Content Accessibility Guidelines (WCAG) строго определен коэффициент контрастности для обеспечения видимости.

2.1 Формула расчета коэффициента контрастности WCAG

Коэффициент контрастности (Contrast Ratio) $CR$ в WCAG определяется следующим образом с использованием относительной яркости (Relative Luminance) цвета фона и цвета переднего плана.

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

Здесь $L_{lighter}$ — относительная яркость более светлого цвета, а $L_{darker}$ — относительная яркость более темного цвета (диапазон значений от 0.0 до 1.0). Для достижения уровня AAA по стандарту WCAG 2.1 требуется коэффициент контрастности не менее 7:1 для обычного текста и не менее 4.5:1 для крупного текста.

Относительная яркость $L$ рассчитывается по следующей сложной формуле из значений RGB в цветовом пространстве sRGB.

$$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. Однако они имеют серьезный недостаток с точки зрения «перцептивной однородности» (perceptual uniformity).

RGB: Это механические три основных цвета света, и людям сложно интуитивно вносить коррективы вроде «сделать светлее» или «сделать темнее».
HSL: Использует оттенок (Hue), насыщенность (Saturation) и светлоту (Lightness), но «светлота (L)» в HSL не совпадает с воспринимаемой яркостью человеческим глазом. Например, чистый желтый и чистый синий со светлотой 50% в HSL численно имеют одинаковую яркость, но человеческому глазу желтый кажется значительно ярче.
OKLCH: Это новейшее цветовое пространство, введенное в CSS Color Module Level 4. Оно состоит из светлоты (Lightness — перцептивной яркости), насыщенности (Chroma) и оттенка (Hue), и полностью соответствует зрительным характеристикам человека (перцептивно однородно).

Используя OKLCH, вы можете сохранять ту же перцептивную яркость (Lightness) даже при изменении оттенка (Hue), что делает создание цветовой палитры для темного режима чрезвычайно предсказуемым и безопасным.

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


/* Пример определения CSS-переменных с использованием OKLCH */
: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

В SPA, таких как React или Vue (или статических сайтах с помощью SSG), распространена практика сохранения пользовательских настроек в localStorage и их чтения с помощью JavaScript для переключения темы. Однако если этот процесс выполняется в useEffect в React или аналогичном хуке, возникают следующие проблемы:

Браузер отрисовывает HTML/CSS светлого режима.
Загружается и выполняется JS-бандл.
Из localStorage считывается настройка dark.
В HTML добавляется класс dark, и экран внезапно темнеет (мерцание).

Лучшая практика для полного предотвращения FOUC и предотвращения ошибок гидратации — это сохранение пользовательских настроек темы в document.cookie и возврат HTML с соответствующими классами, добавленными на этапе серверного рендеринга (SSR).

Следующая диаграмма последовательности иллюстрирует идеальный процесс инициализации темы с использованием Cookie.

sequenceDiagram
participant User as "Пользователь"
participant Browser as "Браузер ОС"
participant Server as "Сервер SSR"
participant DOM as "Клиентский DOM"
User->>Browser: "Запрос страницы"
Browser->>Server: "GET-запрос с Cookie (theme=dark)"
Server-->>Browser: "Возврат HTML с <html data-theme='dark'>"
Browser->>DOM: "Рендеринг начального HTML (Без FOUC)"
DOM->>DOM: "Выполнение скрипта гидратации"
alt "Cookie отсутствует (Первый визит)"
DOM->>Browser: "Проверка OS prefers-color-scheme"
Browser-->>DOM: "Результат matchMedia (например, dark)"
DOM->>DOM: "Установка data-theme='dark' через блокирующий инлайн-скрипт"
end

Для блогов, которые используют только SSG (генерацию статических сайтов) и где SSR невозможен (например, Hugo, Gatsby, статический экспорт Astro), необходимо разместить блокирующий инлайн-скрипт JavaScript внутри тега <head> для добавления класса непосредственно перед отрисовкой 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: по умолчанию, что делает реализацию темного режима чрезвычайно простой. Вы настраиваете свойство darkMode в конфигурационном файле (tailwind.config.js).

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


// tailwind.config.js
module.exports = {
 // 'media' (зависит от настроек ОС) или 'class' (переключается вручную)
 darkMode: 'class',
 theme: {
 extend: {
 colors: {
 /* Расширение цветовой палитры Tailwind с использованием CSS-переменных */
 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 : "Применяет утилитарные классы"

4.2 Реализация на чистом SCSS/CSS (Использование примесей/Mixin)

В проектах, которые не используют Tailwind, а пишут собственные SCSS, стили темного режима инкапсулируются с помощью @mixin.

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


/* Определение SCSS Mixin */
@mixin dark-mode {
 /* Поддерживает как атрибут [data-theme='dark'], так и настройки ОС */
 [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) изображений, вы можете заставить их естественным образом сливаться с пользовательским интерфейсом темной темы.

 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>
 <!-- Показывать это пользователям с настройками ОС в темном режиме -->
 <source srcset="/img/logo-dark.png" media="(prefers-color-scheme: dark)">
 <!-- По умолчанию (светлый режим) -->
 <img src="/img/logo-light.png" alt="Логотип сайта">
</picture>

※ Однако этот метод не связан с ручным переключением через localStorage и т.д. (он зависит только от настроек ОС). Поэтому, если вы реализуете ручное переключение, вам нужно либо динамически переписывать атрибут src изображений с помощью JS, либо переключать display: none с помощью CSS-классов.

5.3 Использование `currentColor` для SVG-иконок

Самый элегантный способ работы с инлайн-SVG, используемыми для иконок, — это связать цвет заливки с цветом текста родительского элемента. Задайте currentColor для атрибутов fill или stroke в SVG.

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. Заключение: К устойчивому проектированию темного режима

Чтобы реализовать качественный темный режим в блоге или веб-приложении, необходимо CSS-проектирование, охватывающее следующие ключевые моменты:

Использование CSS Custom Properties: Избегайте жесткого кодирования (хардкода) цветов и абстрагируйте их в семантические имена переменных (например, --bg-primary).
Принятие цветового пространства OKLCH: Логическое проектирование высокодоступного коэффициента контрастности (7:1 или выше), соответствующего WCAG 2.1 AAA, в перцептивно однородном цветовом пространстве.
Строгие меры предотвращения FOUC: Полное устранение мерцания экрана при начальной загрузке путем связывания SSR и Cookie или блокирующего инлайн-скрипта в <head>.
Оптимизация медиа и ассетов: Использование filter: brightness(), currentColor и тегов <picture>, чтобы нетекстовые элементы гармонировали с темной темой.

Можно сказать, что эти тщательные соображения, выходящие за рамки простого «инвертирования цветов», являются отличительной чертой современного блога, который обеспечивает превосходный опыт чтения, любим пользователями в течение долгого времени и меньше утомляет глаза. Разработчикам, которые собираются внедрять темный режим, обязательно стоит использовать паттерны проектирования из этой статьи в качестве справочного материала.