Tailwind CSS on kenji.blog

Personnalisation du thème Hugo : Comment intégrer Tailwind CSS

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

Introduction : La puissante synergie entre le générateur de site statique Hugo et Tailwind CSS

Dans le développement Web front-end moderne, concilier les performances et l’expérience de développement (DX : Developer Experience) est l’une des priorités majeures de tout projet. L’association de Hugo, qui possède l’une des vitesses de compilation les plus rapides au monde parmi les générateurs de sites statiques (SSG), et de Tailwind CSS, qui a introduit le paradigme novateur du “utility-first” (utilitaire d’abord), constitue sans doute l’une des réponses ultimes à ce défi.

Hugo est écrit en Go et présente des performances exceptionnelles, permettant de compiler un site de plusieurs milliers de pages en quelques secondes, voire en millisecondes. D’autre part, Tailwind CSS permet d’accélérer l’itération du design en éliminant les allers-retours entre les fichiers CSS et HTML grâce à l’écriture directe d’innombrables classes utilitaires prédéfinies (flex, text-center, mt-4, etc.) dans le code HTML.

Cet article explique de manière approfondie et détaillée comment intégrer Tailwind CSS à un thème Hugo, et comment construire un pipeline d’assets avancé (Hugo Pipes) en utilisant PostCSS, depuis les bases de l’architecture jusqu’à l’optimisation mathématique des performances.

1. L’évolution du CSS “utility-first” et l’approche orientée composants

Avant de passer aux instructions d’intégration de Tailwind CSS, il est très utile de comprendre pourquoi nous devrions utiliser Tailwind CSS, ainsi que l’histoire et l’évolution de la philosophie de conception CSS qui se cache derrière.

Les limites de la conception CSS traditionnelle (BEM et OOCSS)

Autrefois dans le développement Web, l’utilisation de noms de classes sémantiques était considérée comme la meilleure pratique. Par exemple, pour créer un composant de carte, le code HTML et le CSS étaient séparés comme suit :

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">Titre</h2>
 <p class="card__description">La description va ici.</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;
}
/* La suite contient d'autres styles détaillés */

Une conception basée sur BEM (Block Element Modifier) comme celle-ci fonctionne bien lorsque le projet est de petite taille, mais a tendance à causer les problèmes suivants :

Épuisement et fatigue liés au nommage : À chaque fois que vous créez un composant similaire, vous devez penser à un nouveau nom de classe (ex. card-news, card-featured, etc.).
Gonflement du CSS : Le nombre de lignes de CSS augmente à chaque ajout de fonctionnalité. Le CSS existant est rarement supprimé par peur de ne pas savoir “où il est utilisé”, ce qui conduit à l’accumulation de code mort.
Changement de contexte : Puisque la structure HTML et les styles CSS sont gérés dans des fichiers séparés, le nombre d’allers-retours entre les onglets dans l’éditeur augmente de manière exponentielle.

Le changement de paradigme avec Tailwind CSS

Tailwind CSS résout ces problèmes en utilisant l’approche de la “combinaison de classes utilitaires”. Le composant de carte ci-dessus ressemblerait à ceci si vous utilisiez 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">Titre</h2>
 <p class="mt-2 text-gray-600">La description va ici.</p>
 </div>
</div>

Étant donné que les noms de classe eux-mêmes représentent des valeurs de style spécifiques (p-6 équivaut à padding: 1.5rem;, etc.), vous pouvez prévoir le résultat final du rendu simplement en regardant le HTML. De plus, le compilateur JIT (Just-In-Time) de Tailwind extrait uniquement les classes réellement utilisées dans le fichier CSS de production, ce qui réduit considérablement la taille du fichier CSS.

2. L’architecture de Hugo Pipes et PostCSS

Pour intégrer Tailwind CSS dans Hugo, il est nécessaire de comprendre le pipeline de traitement des assets appelé Hugo Pipes. Hugo Pipes est une fonctionnalité puissante qui permet de gérer tous les traitements liés aux assets directement dans Hugo, comme la compilation de Sass/SCSS, le bundle et la minification JavaScript, et l’exécution de PostCSS que nous utiliserons ici.

PostCSS est un outil permettant de transformer le CSS à l’aide de plugins JavaScript. Tailwind CSS lui-même fonctionne en réalité comme un plugin PostCSS.

Le mécanisme de transformation AST (Abstract Syntax Tree) avec PostCSS

Comprendre comment PostCSS traite le CSS est extrêmement utile lors de la résolution de problèmes. Le diagramme Mermaid ci-dessous montre le pipeline par lequel PostCSS lit un fichier CSS, le transforme via des plugins et produit le CSS final.

flowchart TD
A["CSS brut (styles.css)"] -->|Parseur| B["AST (Arbre de syntaxe abstraite)"]
B --> C["Plugin 1 : Tailwind CSS"]
C --> D["Plugin 2 : Autoprefixer"]
D --> E["Plugin N : cssnano"]
E -->|Stringifier| F["CSS compilé et optimisé"]

Parseur : Analyse la chaîne CSS brute en entrée et la convertit en AST (Arbre de syntaxe abstraite), une structure de données manipulable par le programme.
Plugins :
- Tailwind CSS : Analyse les fichiers de modèle (HTML ou Markdown) et ajoute les classes utilitaires utilisées sous forme de nœuds à l’AST. Il développe également les directives @tailwind.
- Autoprefixer : Consulte la base de données Can I Use et ajoute les préfixes vendeurs nécessaires (-webkit-, -moz-, etc.) aux propriétés de l’AST.
Stringifier : Convertit l’AST transformé en une chaîne CSS compréhensible par le navigateur pour sa sortie.

3. Configuration de l’environnement et prérequis

Passons maintenant aux étapes d’intégration concrètes. Tout d’abord, nous vérifierons si les logiciels nécessaires sont installés.

Prérequis

Hugo Extended Version : Vous avez besoin de la version Extended de Hugo, et non de la version standard, car elle inclut des fonctionnalités de traitement Sass/SCSS et une intégration native de PostCSS. Exécutez la commande suivante dans le terminal et assurez-vous que la chaîne extended est présente dans les informations de version.
1 2 3

hugo version # Sortie attendue : # hugo v0.121.2-4146... windows/amd64 BuildDate=... VendorInfo=gohugoio +extended
Node.js et npm : Les dépendances comme Tailwind CSS et PostCSS fonctionnent sur Node.js. Assurez-vous que Node.js (version LTS recommandée) est installé.
1 2

node -v npm -v

Installation des paquets npm

Initialisez npm dans le répertoire racine de votre projet (là où se trouve le fichier de configuration de Hugo hugo.toml) et installez les paquets nécessaires.

1
2
3
4
5


# Génération de package.json
npm init -y

# Installation de Tailwind CSS, PostCSS et Autoprefixer en tant que dépendances de développement
npm install -D tailwindcss postcss postcss-cli autoprefixer

[!IMPORTANT] Si postcss-cli n’est pas installé, une erreur peut survenir lorsque Hugo appelle PostCSS en interne. Assurez-vous de l’installer car Hugo Pipes utilise postcss-cli en interne.

4. Création des fichiers de configuration (PostCSS & Tailwind CSS)

Une fois l’installation des paquets terminée, créez deux fichiers de configuration importants qui contrôlent le comportement du projet. Placez-les dans le répertoire racine du projet.

Création de tailwind.config.js

Exécutez la commande suivante dans le terminal pour générer le fichier de configuration par défaut.

1

npx tailwindcss init

Ouvrez le fichier tailwind.config.js généré dans votre éditeur et configurez la propriété content. C’est une étape très importante. Tailwind analyse les fichiers aux chemins spécifiés ici et extrait les classes utilisées. Spécifiez précisément les fichiers de disposition (layouts) et de contenu en fonction de la structure du projet 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 = {
 // Spécifie les cibles d'analyse en fonction de la structure du répertoire Hugo
 content: [
 "./content/**/*.md",
 "./content/**/*.html",
 "./layouts/**/*.html",
 "./assets/**/*.js",
 // Si vous utilisez un thème, vous devez également inclure le répertoire du thème
 // "./themes/mon-theme/layouts/**/*.html",
 ],
 theme: {
 extend: {
 // Les extensions de couleurs personnalisées ou de polices se font ici
 colors: {
 'brand-primary': '#3490dc',
 'brand-secondary': '#ffed4a',
 },
 fontFamily: {
 'sans': ['Helvetica Neue', 'Arial', 'Hiragino Kaku Gothic ProN', 'Meiryo', 'sans-serif'],
 }
 },
 },
 plugins: [
 // Ajoutez des plugins officiels si nécessaire (ex. plugin Typography)
 // require('@tailwindcss/typography'),
 ],
}

Création de postcss.config.js

Ensuite, créez postcss.config.js à la racine du projet pour définir quels plugins PostCSS exécuter et dans quel ordre.

1
2
3
4
5
6


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

Avec cette configuration, lorsque Hugo appellera PostCSS, le traitement de Tailwind CSS sera effectué en premier, suivi de l’ajout des préfixes vendeurs par Autoprefixer.

5. Construction du pipeline d’assets CSS dans Hugo

Une fois la configuration terminée, nous allons enfin intégrer Tailwind CSS dans le thème Hugo.

5-1. Création du fichier CSS point d’entrée

Créez un fichier CSS qui servira de point d’entrée dans le répertoire assets/css/ (créez-le s’il n’existe pas). Nous le nommerons main.css.

Chemin du fichier : assets/css/main.css

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


/* Chargement des styles de base de Tailwind (CSS reset, etc.) */
@tailwind base;

/* Chargement des classes de composants */
@tailwind components;

/* Chargement des classes utilitaires */
@tailwind utilities;

/* Vous pouvez ajouter votre propre CSS personnalisé ici si nécessaire,
 mais il est recommandé d'utiliser extend de tailwind.config.js autant que 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. Modification du fichier de disposition (head.html)

Ensuite, nous allons écrire le pipeline pour charger le fichier CSS ci-dessus depuis un modèle Hugo et le traiter avec PostCSS. Généralement, vous modifierez le modèle partiel qui définit la balise <head> (par exemple, layouts/partials/head.html).

Chemin du fichier : 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>

 <!-- Récupère assets/css/main.css -->
 {{ $css := resources.Get "css/main.css" }}

 <!-- Définition des options pour PostCSS -->
 {{ $options := dict "inlineImports" true }}
 {{ $css = $css | resources.PostCSS $options }}

 <!-- Pipeline d'optimisation des assets pour l'environnement de production -->
 {{ if hugo.IsProduction }}
 <!-- 1. Minification (compression) -->
 {{ $css = $css | minify }}
 <!-- 2. Fingerprint (ajout de hachage pour le contournement du cache) -->
 {{ $css = $css | fingerprint "sha512" }}
 <!-- 3. Sortie de la balise avec SRI (Subresource Integrity) -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}" integrity="{{ $css.Data.Integrity }}" crossorigin="anonymous">
 {{ else }}
 <!-- Dans l'environnement de développement, sortie sans compression (priorité à la vitesse de build) -->
 <link rel="stylesheet" href="{{ $css.RelPermalink }}">
 {{ end }}
</head>

Explication du pipeline et diagramme Mermaid

Illustrons la série d’étapes de traitement que le code modèle Go ci-dessus effectue sur le fichier CSS.

flowchart TD
A["assets/css/main.css"] -->|resources.Get| B["Espace mémoire de Hugo"]
B -->|resources.PostCSS| C["Processus PostCSS + Tailwind JIT"]
C --> D{"hugo.IsProduction ?"}
D -- "Oui (Environnement de production)" --> E["minify (Suppression des espaces et sauts de ligne)"]
E --> F["fingerprint (Calcul de hachage)"]
F --> G["public/css/main.[hash].css (Avec SRI)"]
D -- "Non (Environnement de développement)" --> H["public/css/main.css"]

resources.Get : Recherche le fichier spécifié dans le répertoire assets et le charge en tant qu’objet ressource en mémoire.
resources.PostCSS : Applique le traitement de Tailwind CSS et Autoprefixer au code source CSS en se référant à postcss.config.js à la racine du projet. En environnement de développement (hugo server), le mode JIT est activé, générant rapidement uniquement les classes nécessaires lors de la modification des fichiers.
minify : Supprime les espaces blancs et les commentaires inutiles pour minimiser la taille du fichier lors de la compilation pour l’environnement de production (ex. hugo --environment production).
fingerprint : Calcule un hachage SHA basé sur le contenu du fichier et l’ajoute au nom du fichier (ex. main.ab12cd...css). Cela permet de réaliser un “cache busting” (contournement du cache), s’assurant que le nouveau fichier est chargé lors d’une mise à jour du CSS, tout en utilisant le puissant cache du navigateur.
integrity : Utilise la valeur de hachage calculée par le Fingerprint pour générer un attribut SRI afin de prévenir toute falsification depuis un CDN ou autre.

6. Analyse mathématique des performances dans l’optimisation CSS

L’un des plus grands avantages de l’adoption de Tailwind CSS est la minimisation extrême de la taille du fichier CSS distribué. Analysons quantitativement l’impact de cela sur les performances Web (en particulier le First Contentful Paint : FCP) à l’aide de modèles mathématiques.

Modèle de réduction de la taille des fichiers CSS

Avec les frameworks CSS traditionnels (comme Bootstrap), tous les styles, même ceux qui ne sont pas utilisés, sont chargés, ce qui tend à augmenter la taille du fichier $S_{original}$ (environ 150 Ko à 200 Ko). En supposant que $S_{purged}$ soit la taille après application du processus de purge (Purge) des classes inutilisées par le compilateur JIT de Tailwind CSS, et $R_{purge}$ le taux de réduction, on peut l’exprimer comme suit :

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

Dans un projet typique, $R_{purge}$ atteint près de $0.9$ (réduction de 90%), et $S_{purged}$ se limite à seulement 10 Ko - 20 Ko environ.

De plus, lors de la distribution, le serveur compresse les fichiers avec Brotli ou Gzip. Si le taux de compression est $R_{compress}$ (généralement autour de 0.7 - 0.8), la taille finale de la charge utile transmise sur le réseau, $S_{final}$, est calculée par la formule suivante :

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

Chemin de rendu critique et latence du réseau

Le temps nécessaire au navigateur pour afficher le premier contenu à l’écran (FCP) peut être approximé par la somme du temps de téléchargement HTML, du temps de téléchargement CSS et du temps de rendu.

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

Ici,

$RTT$ : Round Trip Time (Temps de latence aller-retour avec le serveur)
$BW$ : Bande passante du réseau (Bandwidth)

Dans les environnements où $BW$ est faible et $RTT$ est important (latence élevée) comme les réseaux mobiles, l’approche de Tailwind CSS qui réduit $S_{final}$ à quelques kilo-octets permet de rapprocher le terme $\frac{S_{final}}{BW}$ au plus près de zéro, ce qui est le moteur des scores spectaculaires obtenus (Google PageSpeed Insights, etc.).

7. Démarrage du serveur de développement et vérification du Hot Reload

Une fois toute la configuration terminée, démarrez le serveur de développement Hugo pour vérifier que Tailwind CSS fonctionne correctement.

1

hugo server -D

Accédez à http://localhost:1313/ dans votre navigateur et vérifiez que le site s’affiche. Ouvrez un fichier de contenu Markdown ou un modèle Hugo (les fichiers sous layouts/) et essayez d’ajouter une classe.

1
2
3
4
5


<!-- Exemple d'application de classes Tailwind pour un test -->
<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 est génial !</h1>
 <p class="mt-4 text-lg font-medium">Vérifiez que le rechargement à chaud (hot reload) s'applique instantanément.</p>
</div>

Au moment où vous sauvegardez le fichier, le puissant observateur de fichiers de Hugo coopère avec le compilateur JIT de Tailwind pour reconstruire le CSS en quelques millisecondes, et vous devriez ressentir le plaisir de voir votre navigateur se recharger automatiquement (hot reload).

Dépannage : Si les styles ne s’appliquent pas

Si les modifications ne s’appliquent pas, vérifiez les points suivants :

Paramétrage du chemin content dans tailwind.config.js Si le chemin des fichiers à analyser est incorrect, Tailwind ne pourra pas détecter les classes utilisées dans ces fichiers et ne les inclura pas dans le CSS en sortie. Surtout si vous utilisez un thème, assurez-vous de ne pas avoir oublié d’inclure le chemin du répertoire du thème.
Erreurs PostCSS Si une erreur telle que Error: failed to transform resource: PostCSS not found s’affiche dans les journaux du serveur Hugo du terminal, il est probable que npm install ne se soit pas exécuté correctement ou que postcss-cli soit manquant.
Effacer le cache Hugo Dans de rares cas, l’ancien CSS peut persister à cause du cache de Hugo. Arrêtez le serveur, démarrez-le avec hugo server --ignoreCache, ou essayez de supprimer le répertoire temporaire du système d’exploitation (comme /tmp/hugo_cache/).

8. Build pour l’environnement de production et améliorations avancées

Lors du déploiement de votre site sur un serveur de production (Netlify, Vercel, GitHub Pages, Cloudflare Pages, etc.), vous devez définir les variables d’environnement et exécuter le pipeline d’optimisation pour la production.

1
2


# Exemple de commande de build pour la production
NODE_ENV=production hugo --minify --environment production

L’ajout de l’indicateur --environment production exécute le bloc {{ if hugo.IsProduction }} dans head.html, déclenchant la minification CSS et l’ajout du Fingerprint.

Stylisation du Markdown avec le plugin Typography

Dans les sites de blogs et de documentation comme ceux créés avec Hugo, vous ne pouvez pas ajouter directement des classes aux éléments HTML purs (tels que <h1>, <p>, <ul>) générés à partir du Markdown. Le plugin Typography officiel de Tailwind est extrêmement utile dans de tels cas.

Installation du plugin

1

npm install -D @tailwindcss/typography

Ajout à tailwind.config.js

1
2
3
4
5
6


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

Application dans le modèle Il suffit d’ajouter la classe prose (et des variantes de couleur et de taille selon vos préférences) à l’élément conteneur qui affiche le corps de l’article pour appliquer de magnifiques styles par défaut.
1 2 3

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

Grâce à cela, il n’est plus du tout nécessaire d’écrire des sélecteurs CSS complexes à la main (.article-content h2 { ... }), et la modularité des composants est parfaitement préservée.

9. Conclusion : La réalisation d’un écosystème front-end hautement maintenable

Félicitations. Vous disposez maintenant d’un pipeline d’assets de développement Web parfait, combinant le moteur de génération de site statique ultra-rapide de Hugo, les capacités de stylisation modernes de Tailwind CSS et l’extensibilité de PostCSS.

Le point fort de cette architecture est que “la configuration ne se fait qu’une seule fois”. Une fois le pipeline construit, les développeurs peuvent créer des interfaces utilisateur complexes à une vitesse fulgurante en ajoutant simplement des classes utilitaires intuitives aux modèles HTML ou Markdown, sans avoir à ouvrir le moindre fichier CSS.

De plus, étant donné que la taille du CSS généré est toujours minimisée, cela contribue directement à l’amélioration des scores Core Web Vitals, ce qui est extrêmement avantageux du point de vue du SEO.

La combinaison de Hugo et Tailwind CSS restera sans doute l’une des “meilleures options” pour tout projet, des blogs techniques personnels aux sites d’entreprise à grande échelle. N’hésitez pas à tirer parti de cette chaîne d’outils puissante pour profiter d’une expérience de développement Web confortable !

Points clés de la conception CSS pour la prise en charge du mode sombre sur les blogs

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

Dans le développement web moderne, la prise en charge du mode sombre (Dark Mode) n’est plus une simple « fonctionnalité intéressante à avoir » (Nice to have), mais est devenue une « exigence essentielle » (Must have) pour améliorer l’expérience utilisateur (UX). Surtout pour les médias tels que les blogs et les sites de documentation, qui impliquent de longues périodes de lecture de texte, la prise en charge du mode sombre est extrêmement importante car elle réduit la fatigue oculaire des utilisateurs et diminue la consommation de batterie des appareils.

Dans cet article, nous explorerons en profondeur, du point de vue d’un ingénieur front-end, les défis techniques inévitables liés à l’intégration du mode sombre sur un blog, ainsi que les points clés d’une conception CSS hautement maintenable. Nous couvrirons tout ce qu’il faut savoir sur l’implémentation du mode sombre : l’utilisation des CSS Custom Properties (variables CSS), les contrôles JavaScript avancés et la collaboration SSR pour prévenir le FOUC (Flash of Unstyled Content), la conception des couleurs (RGB, HSL, et le plus récent OKLCH) pour assurer l’accessibilité (WCAG 2.1 AAA), et même des exemples de code pratiques utilisant Tailwind CSS.

1. Bases de la conception de thèmes avec les CSS Custom Properties (variables CSS)

Actuellement, l’approche la plus standard et la plus puissante pour implémenter le mode sombre est l’utilisation des CSS Custom Properties (variables CSS). Contrairement aux variables des préprocesseurs CSS comme Sass ($color) qui sont résolues de manière statique lors de la compilation, les variables CSS sont résolues et écrasées dynamiquement à l’exécution par le navigateur. Cela permet de modifier instantanément la palette de couleurs de l’ensemble de la page simplement en changeant de classe via JavaScript.

1.1 Définition d’un thème de couleurs de base

Tout d’abord, nous définissons la palette de couleurs du mode clair (par défaut) en utilisant la pseudo-classe :root. Ensuite, le modèle de conception classique consiste à écraser ces variables lorsqu’un attribut tel que [data-theme='dark'] (ou la classe .dark) est ajouté.

 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


/* Définition des variables pour le mode clair (par défaut) */
:root {
 --color-bg-primary: #ffffff;
 --color-bg-secondary: #f3f4f6;
 --color-text-primary: #111827;
 --color-text-secondary: #4b5563;
 --color-accent: #3b82f6;
 --color-border: #e5e7eb;
}

/* Écrasement des variables en mode sombre */
[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;
}

/* Application pratique */
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);
}

De cette façon, en séparant complètement la spécification de la disposition et de la typographie de celle de la couleur (thème), la maintenabilité du CSS est considérablement améliorée.

1.2 Utilisation de @media (prefers-color-scheme: dark)

Si le mode sombre est configuré au niveau du système d’exploitation (OS), il est souhaitable du point de vue de l’UX d’appliquer automatiquement le thème sombre dès la première visite de l’utilisateur sur le site Web. Cela est rendu possible par la requête multimédia (media query) @media (prefers-color-scheme: dark).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


/* Solution de repli lorsque le mode sombre est configuré dans l'OS */
@media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) {
 --color-bg-primary: #111827;
 --color-bg-secondary: #1f2937;
 --color-text-primary: #f9fafb;
 --color-text-secondary: #9ca3af;
 --color-accent: #60a5fa;
 --color-border: #374151;
 }
}

Avec cette syntaxe, à moins que l’utilisateur n’ait explicitement sélectionné le mode clair (data-theme='light'), le paramètre du mode sombre de l’OS est respecté et les variables sont écrasées.

2. Comprendre les espaces colorimétriques et l’accessibilité (WCAG 2.1 AAA)

Dans la conception des couleurs du mode sombre, il ne suffit pas de simplement « rendre le fond noir et le texte blanc ». Si le contraste est trop fort, cela peut provoquer un effet de halo, rendant la lecture difficile ; à l’inverse, si le contraste est trop faible, la visibilité en pâtit. Dans les directives pour l’accessibilité des contenus Web (WCAG - Web Content Accessibility Guidelines), les ratios de contraste pour assurer la visibilité sont strictement définis.

2.1 Formule de calcul du ratio de contraste des WCAG

Le ratio de contraste (Contrast Ratio) $CR$ dans les WCAG est défini de la manière suivante en utilisant la luminance relative (Relative Luminance) de la couleur de fond et de la couleur de premier plan.

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

Ici, $L_{lighter}$ est la luminance relative de la couleur la plus claire, et $L_{darker}$ est la luminance relative de la couleur la plus sombre (les valeurs vont de 0.0 à 1.0). Pour atteindre le niveau AAA des WCAG 2.1, un ratio de contraste de 7:1 ou plus est requis pour le texte normal, et de 4.5:1 ou plus pour le texte de grande taille.

La luminance relative $L$ est calculée à partir des valeurs RGB de l’espace colorimétrique sRGB avec la formule complexe suivante.

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

Chaque composante ($R, G, B$) utilise une valeur normalisée obtenue en divisant la valeur d’origine sur 8 bits ($R_{sRGB}$) par 255, puis subit la conversion suivante pour lever la correction gamma.

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

Il est difficile d’effectuer ce calcul manuellement, mais en utilisant des outils de conception de couleurs, on peut sélectionner mécaniquement des couleurs qui répondent à un ratio de contraste de 7:1 ($CR \ge 7.0$).

2.2 HSL vs RGB vs OKLCH

Lors de la création de palettes de couleurs, les formats RGB ou HSL étaient autrefois dominants. Cependant, ceux-ci présentent un défaut majeur en termes d’« uniformité perceptuelle ».

RGB : Il s’agit des trois couleurs primaires de la lumière mécanique, ce qui rend difficile pour les humains de faire des ajustements intuitifs comme « éclaircir » ou « assombrir ».
HSL : Il utilise la teinte (Hue), la saturation (Saturation) et la luminosité (Lightness), mais la « luminosité (L) » du HSL ne correspond pas à la luminosité perçue par l’œil humain. Par exemple, un jaune pur et un bleu pur avec une luminosité de 50 % en HSL ont la même luminosité numériquement, mais le jaune paraît infiniment plus lumineux à l’œil humain.
OKLCH : C’est le dernier espace colorimétrique introduit récemment dans CSS Color Module Level 4. Composé de la luminosité perceptuelle (Lightness), de la chromaticité/saturation (Chroma) et de la teinte (Hue), il correspond parfaitement aux caractéristiques visuelles humaines (uniformité perceptuelle).

L’utilisation d’OKLCH permet de conserver la même luminosité perceptuelle (Lightness) même si l’on change la teinte (Hue), ce qui rend la génération d’une palette de couleurs pour le mode sombre extrêmement prévisible et sûre.

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


/* Exemple de définition de variables CSS utilisant OKLCH */
:root {
 /* Mode clair avec une luminosité de base élevée et une saturation modérée */
 --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"] {
 /* En mode sombre, il suffit d'inverser la luminosité pour maintenir facilement le contraste perceptuel */
 --bg-base: oklch(0.20 0.02 250);
 --text-base: oklch(0.95 0.01 250);
 --primary-brand: oklch(0.75 0.15 250); /* Légèrement plus clair pour assurer la visibilité en mode sombre */
}

En adoptant ainsi l’OKLCH, vous pouvez construire simplement une logique qui garantit un ratio de contraste constant (au niveau WCAG AAA) à travers plusieurs thèmes.

3. Prévention du FOUC (Flash of Unstyled Content) et hydratation SSR

Ce qui préoccupe le plus les développeurs dans la prise en charge du mode sombre, c’est le problème de scintillement de l’écran appelé FOUC (Flash of Unstyled Content).

3.1 Le piège du basculement de thème par JS côté client

Dans les SPA comme React ou Vue (ou les sites statiques via SSG), il est courant d’enregistrer les paramètres de l’utilisateur dans le localStorage et de les lire avec JavaScript pour basculer de thème. Cependant, si ce processus est effectué via useEffect dans React par exemple, les problèmes suivants se produisent.

Le navigateur rend le HTML/CSS du mode clair.
Le bundle JS est chargé et exécuté.
Le paramètre dark est lu depuis le localStorage.
La classe dark est ajoutée au HTML, et l’écran s’assombrit soudainement (scintillement).

La meilleure pratique pour prévenir complètement le FOUC et éviter les erreurs d’hydratation consiste à enregistrer le paramètre de thème de l’utilisateur dans document.cookie et à renvoyer le HTML avec les classes appropriées ajoutées lors du rendu côté serveur (SSR).

Le diagramme de séquence ci-dessous illustre le flux idéal d’initialisation du thème à l’aide de cookies.

sequenceDiagram
participant User as "Utilisateur"
participant Browser as "Navigateur OS"
participant Server as "Serveur SSR"
participant DOM as "Client DOM"
User->>Browser: "Demande de page"
Browser->>Server: "Requête GET avec Cookie (theme=dark)"
Server-->>Browser: "Renvoie HTML avec <html data-theme='dark'>"
Browser->>DOM: "Rendu HTML initial (Aucun FOUC)"
DOM->>DOM: "Exécution du script d'hydratation"
alt "Cookie absent (Première visite)"
DOM->>Browser: "Vérifie OS prefers-color-scheme"
Browser-->>DOM: "Résultat matchMedia (ex. dark)"
DOM->>DOM: "Définit data-theme='dark' via script bloquant en ligne"
end

3.3 Ligne de défense via un script en ligne (Pour les sites statiques sans cookies)

Pour les blogs générés uniquement de manière statique (SSG) où le SSR est impossible (comme les exports statiques de Hugo, Gatsby ou Astro), il est indispensable de placer un script JavaScript en ligne s’exécutant de manière bloquante à l’intérieur de la balise <head>, qui ajoute la classe juste avant le rendu du DOM.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<!-- À placer à la fin de la balise <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>

Ce petit script bloque le rendu du navigateur et s’exécute immédiatement. Ainsi, au moment où l’écran est affiché, l’attribut data-theme est déjà configuré, ce qui permet de prévenir complètement le scintillement de l’écran (FOUC).

4. Approches d’implémentation avec Tailwind CSS et SCSS/CSS natif

Lors de l’intégration du mode sombre dans un projet réel, il est important de comprendre l’approche de chaque outil.

4.1 Le mode sombre dans Tailwind CSS

Tailwind CSS fournit par défaut une variante dark:, ce qui rend l’implémentation du mode sombre très facile. On configure la propriété darkMode dans le fichier de configuration (tailwind.config.js).

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


// tailwind.config.js
module.exports = {
 // 'media' (dépendant des paramètres OS) ou 'class' (basculable manuellement)
 darkMode: 'class',
 theme: {
 extend: {
 colors: {
 /* Extension de la palette de couleurs Tailwind à l'aide de variables CSS */
 primary: 'rgb(var(--color-primary) / <alpha-value>)',
 background: 'rgb(var(--color-background) / <alpha-value>)',
 }
 }
 }
}

Du côté HTML, il suffit d’ajouter les classes de la manière suivante.

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>

Cependant, écrire dark:bg-xxx pour tous les éléments peut causer une surcharge excessive des composants. Pour les blogs ou applications de grande envergure, il est recommandé d’adopter une conception hybride (conception de couleurs sémantiques) où les variables CSS servent de base, et Tailwind référence ces variables CSS.

Le diagramme de classes ci-dessous montre l’héritage des variables CSS et les couches d’application.

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 : "Applique les classes utilitaires"

4.2 Implémentation en Raw SCSS/CSS (Utilisation des Mixins)

Pour les projets qui n’utilisent pas Tailwind et écrivent leur propre SCSS, on utilise les @mixin pour encapsuler les styles du mode sombre.

 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


/* Définition du Mixin SCSS */
@mixin dark-mode {
 /* Supporte à la fois l'attribut [data-theme='dark'] et les paramètres de l'OS */
 [data-theme='dark'] & {
 @content;
 }
 @media (prefers-color-scheme: dark) {
 :root:not([data-theme='light']) & {
 @content;
 }
 }
}

/* Exemple d'utilisation */
.card {
 background-color: #ffffff;
 color: #333333;
 border: 1px solid #eeeeee;

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

Cette méthode est intuitive, mais la taille du fichier CSS compilé a tendance à s’alourdir (la requête multimédia est dupliquée pour chaque sélecteur). C’est pourquoi la tendance actuelle se tourne plutôt vers une conception axée sur les variables CSS (Custom Properties).

5. Optimisation du mode sombre pour les images (Image) et les SVG

Même si la conception des couleurs pour le texte et les arrière-plans est achevée, si les images et les icônes (SVG) placées comme contenu restent en mode clair, elles paraîtront éblouissantes et se détacheront trop en mode sombre. Leur optimisation est également essentielle.

5.1 Filtres CSS pour réduire la luminosité des images

Les images bitmap telles que les photos peuvent être trop lumineuses si elles sont affichées telles quelles en mode sombre. En utilisant la propriété CSS filter pour réduire légèrement la luminosité (brightness) et augmenter le contraste (contrast) de l’image, on peut la faire fondre naturellement dans l’interface du thème sombre.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[data-theme='dark'] img:not([src*=".svg"]) {
 /* Réduit la luminosité et augmente un peu le contraste */
 filter: brightness(0.8) contrast(1.1);
 transition: filter 0.3s ease;
}

[data-theme='dark'] img:hover {
 /* Restaure la luminosité d'origine au survol (si l'utilisateur veut voir les détails) */
 filter: brightness(1) contrast(1);
}

5.2 Remplacement d’images via la balise `<picture>`

Les images de logos ou les diagrammes explicatifs (comme les JPEG avec un fond blanc fixe) ne peuvent pas être gérés uniquement par des filtres. Dans ces cas-là, la bonne solution consiste à utiliser l’élément HTML <picture> et les requêtes multimédias (media queries) pour afficher un autre fichier image spécifique au mode sombre.

1
2
3
4
5
6


<picture>
 <!-- Affiché pour les utilisateurs ayant configuré leur OS en mode sombre -->
 <source srcset="/img/logo-dark.png" media="(prefers-color-scheme: dark)">
 <!-- Par défaut (mode clair) -->
 <img src="/img/logo-light.png" alt="Logo du site">
</picture>

※ Toutefois, cette méthode ne se synchronise pas avec les basculements manuels comme via localStorage (elle ne dépend que des paramètres de l’OS). Si vous implémentez un basculement manuel, vous devrez modifier dynamiquement la source src des images avec JS ou basculer un display: none via des classes CSS.

5.3 Prise en charge de `currentColor` pour les icônes SVG

La méthode la plus élégante pour les SVG en ligne utilisés pour des icônes est de lier leur couleur de remplissage à la couleur du texte de l’élément parent. Pour ce faire, spécifiez currentColor dans l’attribut fill ou stroke du SVG.

1
2
3
4


<!-- La valeur de la propriété color du CSS (ex: var(--text-primary)) est appliquée automatiquement -->
<svg viewBox="0 0 24 24" fill="currentColor">
 <path d="M12 2L2 22h20L12 2z" />
</svg>

Ainsi, lors du passage au mode sombre, si la couleur du texte de l’élément parent devient blanche, l’icône SVG passera aussi automatiquement à une teinte blanche.

6. Conclusion : Vers une conception durable du mode sombre

Pour implémenter un mode sombre de haute qualité sur un blog ou une application web, une conception CSS couvrant les points suivants est indispensable.

Utiliser les CSS Custom Properties : Éviter le codage en dur (hardcoding) des spécifications de couleurs et les abstraire dans des noms de variables sémantiques (ex: --bg-primary).
Adopter l’espace colorimétrique OKLCH : Concevoir de manière logique des ratios de contraste hautement accessibles (7:1 ou plus) répondant à la norme WCAG 2.1 AAA, au sein d’un espace colorimétrique perceptuellement uniforme.
Appliquer des mesures strictes contre le FOUC : Éliminer complètement les scintillements de l’écran lors du chargement initial grâce à l’association du SSR et des cookies, ou via des scripts bloquants en ligne dans le <head>.
Optimiser les médias et les ressources : Harmoniser les éléments autres que le texte avec le thème sombre en exploitant filter: brightness(), currentColor et la balise <picture>.

Ces attentions minutieuses, qui vont bien au-delà d’une simple « inversion de couleurs », constituent les conditions d’un blog moderne offrant une expérience de lecture (reading experience) supérieure, agréable pour les yeux et appréciée durablement par les utilisateurs. Développeurs sur le point d’introduire le mode sombre, n’hésitez pas à vous référer aux modèles de conception présentés dans cet article.