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

Bases de l'architecture logicielle : Qu'est-ce que la Clean Architecture ?

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

Dans le développement logiciel moderne, la construction d’un « système résilient aux changements » est un défi éternel. Changements des exigences métier, émergence de nouveaux frameworks, refonte de l’interface utilisateur (UI), migration de base de données. Face à tous ces changements, on recherche une architecture capable de s’adapter avec souplesse sans avoir à reconstruire le système entier. L’une des réponses à ce besoin est la Clean Architecture, proposée par Robert C. Martin (surnommé Oncle Bob, Uncle Bob).

Dans cet article, nous explorerons l’essence de la Clean Architecture à travers son histoire, son objectif, les détails de ses 4 couches, la règle de dépendance, ainsi que des exemples concrets d’implémentation. Nous fournirons une explication technique très approfondie et détaillée.

1. Les problèmes des architectures traditionnelles et l’histoire de la Clean Architecture

Historiquement, l’architecture logicielle a connu divers changements de paradigme. Dans les premiers systèmes, le code de la logique métier, de l’UI et de l’accès aux données était fortement couplé (ce qu’on appelle du code spaghetti). Par la suite, dans le but d’appliquer la séparation des préoccupations (Separation of Concerns), l’architecture en 3 tiers (couche de présentation, couche de logique métier, couche d’accès aux données) s’est popularisée.

Cependant, l’architecture en 3 tiers traditionnelle présentait un problème majeur : « le domaine (la logique métier) finit par dépendre de la base de données et des frameworks ».

Par exemple, si la couche de logique métier appelle directement la couche d’accès aux données (comme un ORM), un changement de schéma de base de données ou d’ORM se répercute sur la logique métier. En d’autres termes, il y avait une contradiction où les « règles métier », qui sont les plus importantes et ne devraient pas changer, dépendaient de « l’infrastructure », qui est la plus susceptible de subir des modifications techniques.

Pour résoudre ce problème, les architectures suivantes ont été conçues :

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

Toutes ces architectures ont le même objectif : la « séparation des préoccupations ». Il s’agit de diviser le logiciel en couches, où chacune peut être testée indépendamment et reste indépendante des agents externes (UI, base de données, frameworks).

Robert C. Martin a intégré les concepts de ces excellentes architectures et les a regroupés sous une seule règle pratique qu’il a nommée la « Clean Architecture ».

2. Objectifs et caractéristiques de la Clean Architecture

Un système qui adopte la Clean Architecture possède les caractéristiques suivantes :

Indépendant des frameworks (Independent of Frameworks) : L’architecture ne dépend pas de l’existence de bibliothèques logicielles riches en fonctionnalités. Cela permet d’utiliser les frameworks comme des « outils » et vous évite d’avoir à contraindre le système aux limites de ces frameworks.
Testable : Les règles métier peuvent être testées sans l’interface utilisateur (UI), la base de données, le serveur web ou tout autre élément externe.
Indépendant de l’interface utilisateur (Independent of UI) : L’UI peut changer facilement sans modifier le reste du système. Par exemple, une UI Web pourrait être remplacée par une UI console sans changer les règles métier.
Indépendant de la base de données (Independent of Database) : Vous pouvez remplacer Oracle ou SQL Server par Mongo, BigTable, CouchDB ou autre. Vos règles métier ne sont pas liées à la base de données.
Indépendant de tout agent externe (Independent of any external agency) : En fait, vos règles métier ne connaissent absolument rien du monde extérieur.

3. Les 4 couches (Layers) de la Clean Architecture

La Clean Architecture est généralement représentée par des cercles concentriques. Plus on se rapproche du centre, plus le logiciel contient des politiques de haut niveau (règles métier abstraites). Plus on s’éloigne vers l’extérieur, plus on trouve les mécanismes (détails concrets).

graph TD
subgraph "External Interfaces (Frameworks & Drivers)"
A["Web"]
B["UI"]
C["Base de données"]
D["APIs externes"]
end
subgraph "Interface Adapters"
E["Contrôleurs"]
F["Passerelles"]
G["Présentateurs"]
end
subgraph "Application Business Rules (Use Cases)"
H["Interacteurs de Cas d'Utilisation"]
end
subgraph "Enterprise Business Rules (Entities)"
I["Entités"]
end
A --> E
B --> E
C --> F
D --> F
E --> H
F --> H
G --> H
H --> I

3.1. Entités (Entities)

Les entités encapsulent les règles métier de l’entreprise à grande échelle (Enterprise Business Rules). Une entité peut être un objet avec des méthodes, ou un ensemble de structures de données et de fonctions. Ce sont les règles les plus générales et de plus haut niveau, réutilisables dans plusieurs applications différentes au sein de l’entreprise. Même si vous ne créez qu’une seule application, ces entités constituent les objets métier de l’application. Elles ne sont en aucun cas affectées par un changement externe (comme un changement de navigation dans les pages ou un changement de sécurité).

3.2. Cas d’utilisation (Use Cases)

La couche des cas d’utilisation contient les règles métier spécifiques à l’application (Application Business Rules). C’est ici que sont encapsulés et mis en œuvre tous les cas d’utilisation du système. Les cas d’utilisation orchestrent le flux de données vers et depuis les entités, et dirigent ces entités pour utiliser leurs règles métier globales afin d’atteindre les objectifs du système. Les modifications apportées à cette couche ne doivent pas affecter les entités. De plus, cette couche ne doit pas être affectée par des changements externes tels que la base de données, l’UI ou les frameworks. Les cas d’utilisation sont totalement isolés de ces préoccupations.

3.3. Adaptateurs d’interface (Interface Adapters)

La couche des adaptateurs d’interface est un ensemble d’adaptateurs qui convertissent les données du format le plus pratique pour les cas d’utilisation et les entités vers le format le plus pratique pour les agents externes tels que la base de données ou le Web. Par exemple, dans le monde du Web, c’est ici que se trouvent les éléments de l’architecture MVC (Model-View-Controller) d’une GUI. Les contrôleurs prennent les entrées de l’utilisateur et les transmettent aux cas d’utilisation, et les présentateurs reçoivent la sortie des cas d’utilisation et la formatent pour la vue (UI). C’est également le rôle de cette couche de convertir les données dans un format compréhensible par la base de données (comme le SQL). Aucun code à l’intérieur de cette couche ne devrait rien savoir de la base de données.

3.4. Frameworks et Pilotes (Frameworks & Drivers)

La couche la plus externe est composée d’outils tels que la base de données, le framework Web, etc. En général, on n’écrit pas beaucoup de code ici, si ce n’est du code de liaison (« glue code ») pour communiquer avec les cercles intérieurs. C’est dans cette couche que tous les détails sont conservés. Le Web est un détail. La base de données est un détail. Nous gardons ces éléments à l’extérieur pour qu’ils fassent le moins de dégâts possible.

4. La Règle de Dépendance (The Dependency Rule)

Il existe une règle fondamentale et absolue pour que la Clean Architecture fonctionne. C’est la « Règle de Dépendance (The Dependency Rule) ».

Les dépendances du code source ne doivent pointer que vers l’intérieur (vers les politiques de plus haut niveau).

Rien dans un cercle intérieur ne doit connaître quoi que ce soit d’un cercle extérieur. En particulier, le nom d’un élément (fonction, classe, variable, etc.) déclaré dans un cercle extérieur ne doit pas être mentionné par le code dans un cercle intérieur. De même, les formats de données utilisés dans un cercle extérieur ne doivent pas être utilisés par un cercle intérieur, en particulier si ces formats sont générés par un framework d’un cercle extérieur.

graph LR
A["Frameworks et Pilotes"] -->| Dépend de | B["Adaptateurs d'interface"]
B -->| Dépend de | C["Cas d'utilisation"]
C -->| Dépend de | D["Entités"]
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

Exprimé mathématiquement, si nous définissons l’indice de la couche comme $L_i$, où $i=0$ est l’entité (la couche la plus interne) et $i=3$ le framework (la couche la plus externe), si une dépendance existe d’une couche $L_m$ à $L_n$, l’inégalité suivante doit toujours être vérifiée :

$$ m > n $$

En d’autres termes, le vecteur de dépendance $\vec{D}$ pointe toujours vers le centre.

5. Franchir les frontières : Le Principe d’Inversion des Dépendances (DIP)

En essayant de respecter la règle de dépendance, on se heurte rapidement à un problème majeur : « Que faire si un cas d’utilisation a besoin de récupérer des données depuis la base de données ? »

Si la couche des cas d’utilisation (à l’intérieur) appelle directement la couche des adaptateurs d’interface (l’implémentation du Repository à l’extérieur), la dépendance pointerait vers l’extérieur, ce qui violerait la règle de dépendance.

La solution à ce problème réside dans le « D » des principes SOLID (Dependency Inversion Principle : le Principe d’Inversion des Dépendances).

Définition du Principe d’Inversion des Dépendances (DIP)

Les modules de haut niveau ne doivent pas dépendre des modules de bas niveau. Les deux doivent dépendre d’abstractions.
Les abstractions ne doivent pas dépendre des détails. Les détails doivent dépendre des abstractions.

Pour y parvenir, on définit une interface (abstraction) dans la couche des cas d’utilisation, et on l’implémente dans la couche externe (les adaptateurs d’interface). La couche des cas d’utilisation ne dépend que de l’interface qu’elle a elle-même définie, et non de l’implémentation concrète externe.

classDiagram
class UseCaseInteractor {
- UserRepository repository
+ execute()
}
class UserRepository {
<<Interface>>
+ findById(id)
+ save(user)
}
class UserRepositoryImpl {
+ findById(id)
+ save(user)
}
UseCaseInteractor --> UserRepository : "Dépend de"
UserRepositoryImpl ..|> UserRepository : "Implémente"
note for UseCaseInteractor "Couche interne (Cas d'utilisation)"
note for UserRepository "Couche interne (Cas d'utilisation)"
note for UserRepositoryImpl "Couche externe (Adaptateurs d'interface)"

Dans le diagramme ci-dessus, le flux de contrôle (Control Flow) à l’exécution est UseCaseInteractor $\rightarrow$ UserRepositoryImpl. Cependant, la dépendance du code source (Source Code Dependency) est UserRepositoryImpl $\rightarrow$ UserRepository (vers l’intérieur). En utilisant le polymorphisme, nous avons pu diriger la dépendance du code source dans la direction opposée au flux de contrôle. C’est pour cela qu’on l’appelle l’inversion des dépendances.

6. Exemple d’implémentation concrète en TypeScript

Voici un exemple simple d’implémentation de la Clean Architecture en TypeScript (une fonctionnalité d’inscription d’utilisateur).

6.1. Entités (Entities)

Il s’agit des règles métier les plus centrales.

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

 // Règles métier spécifiques à l'entité (ex: vérification de la longueur du nom, etc.)
 public isValid(): boolean {
 return this.name.length >= 3 && this.email.includes('@');
 }
}

6.2. Cas d’utilisation (Use Cases)

Dans la couche des cas d’utilisation, nous définissons les structures de données d’entrée et de sortie (DTO) ainsi que l’interface du Repository pour inverser les dépendances.

 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
60


// src/application/repositories/UserRepository.ts
import { User } from '../../domain/entities/User';

// Interface définie par la couche des cas d'utilisation
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 {
 // Dépend d'une abstraction (interface). Ne dépend pas d'une implémentation concrète.
 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');
 }

 // Appelle le processus de sauvegarde en base de données à l'extérieur,
 // mais la dépendance pointe vers l'intérieur (vers l'interface)
 await this.userRepository.save(newUser);

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

6.3. Adaptateurs d’interface (Interface Adapters)

Nous créons ici le processus d’accès concret à la base de données (l’implémentation du Repository) et le Controller qui gère les requêtes HTTP.

 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';
// On suppose que c'est un client de base de données de la couche externe (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. Composant principal (Injection de dépendances : DI)

Au démarrage de l’application, nous construisons toutes les dépendances (câblage). C’est ce qu’on appelle la Racine de Composition (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. Initialisation du Driver
const dbClient = new DatabaseClient(/* Informations de connexion */);

// 2. Initialisation de l'Adaptateur (Instanciation de la classe concrète)
const userRepository = new PostgresUserRepository(dbClient);

// 3. Initialisation du Cas d'Utilisation (Injection de la classe concrète dans l'interface = DI)
const registerUserUseCase = new RegisterUserUseCase(userRepository);

// 4. Initialisation du Contrôleur
const userController = new UserController(registerUserUseCase);

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

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

De cette manière, le « script de démarrage » situé dans la couche la plus externe prend en charge les détails désagréables (l’instanciation des classes concrètes) et ne transmet que des interfaces propres aux couches internes, isolant ainsi complètement la logique métier du monde extérieur.

7. Considérations mathématiques sur le couplage et la cohésion

En génie logiciel, le couplage (Coupling) et la cohésion (Cohesion) sont des métriques utilisées pour évaluer la qualité d’une architecture.

Le couplage $C$ représente la force de dépendance entre les modules. Si le module $A$ dépend du module $B$, en posant le nombre total de dépendances du système à $N_{dep}$ et le nombre de modules à $N_{mod}$, l’un des indicateurs de la complexité peut s’exprimer ainsi :

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

Dans la Clean Architecture, l’application du principe DIP permet d’orienter les flèches de dépendance physique vers des abstractions. L’instabilité (Instability : $I$), c’est-à-dire la fréquence de modification d’une abstraction (interface), est conçue pour être très faible.

L’instabilité $I$ est calculée par la formule suivante (définie par Robert C. Martin) :

$C_e$ (Efferent Coupling) : Couplage sortant (le nombre d’éléments dont dépend le composant)
$C_a$ (Afferent Coupling) : Couplage entrant (le nombre d’éléments dépendant du composant)

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

Si $I = 0$, le composant est totalement stable (il ne dépend de rien, mais d’autres dépendent de lui).
Si $I = 1$, le composant est totalement instable (personne ne dépend de lui, et il dépend d’autres composants).

La « couche des entités » de la Clean Architecture a un $C_e = 0$ (ne dépend pas de l’extérieur), donc $I = 0$. C’est la couche la plus stable. À l’inverse, la « couche UI » ou la « couche DB » ont un $C_a \approx 0$ et un $C_e > 0$, donc $I \approx 1$. Ce sont des couches facilement modifiables (couches instables).

Le SDP (Stable Dependencies Principle : Principe de Dépendances Stables), qui est un principe fondamental de l’architecture, stipule que « les dépendances doivent pointer vers des composants plus stables (ceux dont le $I$ est plus petit) ». Les cercles concentriques de la Clean Architecture sont justement la visualisation de ce SDP, où l’architecture est conçue pour que les dépendances aillent de l’extérieur ($I=1$) vers l’intérieur ($I=0$).

8. Stratégie de test et Clean Architecture

L’un des plus grands avantages de la Clean Architecture est la facilité de test. Les couches étant séparées, il est possible d’écrire des tests adaptés à chaque couche de manière indépendante.

8.1. Test des entités (Test Unitaire)

Puisqu’il s’agit d’une logique pure sans aucune dépendance externe, ni base de données ni mock ne sont nécessaires. C’est le test le plus fiable et le plus rapide à exécuter.

8.2. Test des cas d’utilisation (Test Unitaire avec Mocks)

Comme toutes les dépendances externes telles que les repositories sont définies sous forme d’interfaces, il suffit d’injecter (DI) des mocks pour les tests ou des implémentations en mémoire (Fake) lors des tests. Il n’est pas nécessaire de lancer une vraie base de données. Cela permet de tester rapidement les branchements complexes et la gestion des exceptions de la logique métier.

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


// Exemple de test de cas d'utilisation (en supposant l'utilisation de Jest)
test('L\'inscription avec une adresse e-mail existante doit générer une erreur', async () => {
 // Création d'un Fake Repository
 const mockRepo: UserRepository = {
 findByEmail: async (email) => new User('1', 'Test', email, new Date()), // Retourne un utilisateur existant
 save: async (user) => {}
 };

 const useCase = new RegisterUserUseCase(mockRepo);

 // Exécution du cas d'utilisation et assertion de l'erreur
 await expect(useCase.execute({ name: 'Bob', email: 'test@example.com' }))
 .rejects
 .toThrow('User already exists');
});

8.3. Test des adaptateurs (Test d’Intégration)

La classe d’implémentation du Repository est testée en se connectant réellement à la base de données pour vérifier que le SQL est correct. Le test du Controller vérifie la partie qui reçoit la requête HTTP et renvoie le JSON. Ici, on ne procède pas à une validation détaillée de la logique métier, mais on vérifie seulement si la « conversion » et la « communication » sont correctes.

9. Les inconvénients de la Clean Architecture et quand l’adopter

Bien qu’elle semble être une solution universelle, la Clean Architecture n’est pas une balle d’argent. Elle présente des inconvénients (compromis) tels que :

Augmentation des coûts d’apprentissage initiaux et des coûts de développement : Le nombre de fichiers et d’interfaces (abstractions) augmente considérablement. Il y aura beaucoup de « code de la plaque de base (boilerplate) » tel que le reconditionnement des DTO.
Surdimensionnée pour les petits projets : Adopter cette architecture pour un prototype construit en quelques jours ou pour un outil à usage unique soumis à peu de changements représente souvent un coût inutile. Elle est également inadaptée pour une simple API ne gérant que des opérations CRUD.

Quand l’adopter :

Les produits dont la maintenance et l’exploitation sont prévues sur le long terme (plusieurs années).
Les systèmes où les règles métier sont complexes et font l’objet de changements de spécifications fréquents.
Lorsque vous souhaitez répartir le travail au sein d’une grande équipe de développement (front-end, back-end, infrastructure, etc.).
Lorsque vous souhaitez la combiner avec le Domain-Driven Design (DDD) pour modéliser des domaines métier complexes.

10. Résumé

La Clean Architecture est une philosophie de conception visant à protéger le cœur du système, c’est-à-dire les « règles métier », contre les « détails » tels que l’UI, la base de données ou les frameworks.

En son cœur se trouvent la règle de dépendance et le Principe d’Inversion des Dépendances (DIP). En les appliquant correctement, les logiciels deviennent flexibles face aux changements, plus faciles à tester, et peuvent maintenir leur valeur sur le long terme.

L’important n’est pas de reproduire aveuglément la structure de répertoires de la Clean Architecture, mais de comprendre l’essence de « pourquoi diviser de cette façon » et « vers où pointent les flèches de dépendance », afin de l’appliquer correctement en fonction de la taille et de la complexité de votre propre projet.

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

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.