Implémenter le mode sombre avec Claude Code

Commencer par le risque produit

Implémenter le mode sombre avec Claude Code ne signifie pas demander à Claude Code de rendre l’écran plus joli. Le but est d’améliorer une interface réelle sans casser la conversion, la lisibilité, l’accessibilité ou le mobile. En production, les détails comptent: état vide, chargement, erreur, focus clavier, textes longs, publicités, blocs de code et position du CTA.

À lire avec claude code design system, claude code accessibility, claude code code review. Les références officielles sont Claude Code docs, MDN prefers-color-scheme, MDN color-scheme, WCAG contrast. La demande à Claude Code doit préciser l’objectif, les limites, les use case, les pitfall et la vérification.

Prompt conseillé

Implémente cette amélioration avec le plus petit changement sûr.
Respecte les composants, les design tokens et les routes existantes.
Couvre use case, pitfall, accessibilité, mobile et états d'erreur.
Retourne du code copiable et une review checklist.

Use case checklist

Pages d’atterrissage et articles où le lecteur doit voir l’étape suivante sans pression.
Dashboards SaaS avec chargement, état vide, erreur et succès.
Achat, inscription et demande de rendez-vous où le bouton principal reste prioritaire.
Revue en équipe, avec code et critères de vérification fournis par Claude Code.

Code d’implémentation

:root {
  color-scheme: light;
  --color-page: #ffffff;
  --color-surface: #f8fafc;
  --color-text: #0f172a;
  --color-muted: #475569;
  --color-border: #dbe3ef;
  --color-link: #2563eb;
  --color-focus: #f59e0b;
}

[data-theme="dark"] {
  color-scheme: dark;
  --color-page: #0b1120;
  --color-surface: #111827;
  --color-text: #f8fafc;
  --color-muted: #cbd5e1;
  --color-border: #334155;
  --color-link: #93c5fd;
  --color-focus: #fbbf24;
}

body {
  background: var(--color-page);
  color: var(--color-text);
}

:focus-visible {
  outline: 3px solid var(--color-focus);
  outline-offset: 3px;
}

const storageKey = "theme";
const root = document.documentElement;
const stored = localStorage.getItem(storageKey);
const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
const theme = stored === "light" || stored === "dark" ? stored : prefersDark ? "dark" : "light";

root.dataset.theme = theme;

type Theme = "light" | "dark" | "system";

export function ThemeToggle({ value, onChange }: { value: Theme; onChange: (theme: Theme) => void }) {
  return (
    <fieldset aria-label="Theme">
      {(["light", "dark", "system"] as const).map((theme) => (
        <button
          key={theme}
          type="button"
          aria-pressed={value === theme}
          onClick={() => onChange(theme)}
        >
          {theme}
        </button>
      ))}
    </fieldset>
  );
}

Éviter le scintillement de thème (le flash de couleur au tout début)

Le premier piège du mode sombre est ce « scintillement » : à l’ouverture de la page, on voit un instant l’écran clair avant qu’il ne passe au sombre. En anglais on parle de FOUC (Flash of Unstyled Content) ou de flash de thème. La cause est que le thème est basculé en JavaScript après l’affichage du HTML. Si vous ajoutez data-theme seulement après le chargement du CSS ou de React, la couleur initiale (souvent claire) reste visible pendant ce délai d’attente.

La parade est d’exécuter de façon synchrone, avant le corps (dans le <head>), un très court script qui décide du thème. Comme ci-dessous, en ne regardant que le réglage sauvegardé et celui de l’appareil, on fige data-theme avant que l’écran ne soit peint.

<script>
  (function () {
    var stored = localStorage.getItem("theme");
    var prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
    var theme = stored === "light" || stored === "dark" ? stored : prefersDark ? "dark" : "light";
    document.documentElement.dataset.theme = theme;
  })();
</script>

L’essentiel est de garder ce script léger et de le faire tourner avant le rendu du corps. Si vous y mettez un traitement lourd ou l’initialisation de React, le scintillement revient. Avec Astro ou Next.js aussi, traitez ce petit script à part pour figer le thème sans attendre l’hydratation du framework (le processus qui, côté navigateur, anime le HTML produit côté serveur). Le serveur ne peut pas connaître le réglage de l’appareil : au premier passage, respectez le réglage de l’appareil ; dès que l’utilisateur bascule, sauvegardez dans localStorage pour donner la priorité à son choix la fois suivante.

Rendre contraste, images et ombres lisibles aussi en sombre

Inverser les couleurs ne suffit pas à finir un mode sombre. Un contraste qui suffisait sur écran clair peut devenir insuffisant sur fond sombre. Vérifiez le rapport de contraste entre le texte et le fond avec pour repère le 4,5:1 minimum indiqué par WCAG. En particulier, le texte secondaire gris clair, les placeholders et les boutons désactivés deviennent vite illisibles sur fond sombre.

Les images et les ombres demandent aussi un ajustement. Un logo ou une icône conçus pour le blanc perdent leurs contours sur fond sombre. Pour un PNG transparent, posez une couleur de fond ou préparez une variante sombre. Une ombre efficace en gris foncé sur fond clair devient presque invisible sur fond sombre. Une limite qui reposait sur l’ombre se réexprime mieux avec un trait comme --color-border, et la structure reste lisible dans les deux thèmes.

Élément	Hypothèse en clair	Ajustement en sombre
Texte secondaire	Gris clair suffit	Monter la luminosité pour garantir le contraste
Logo et icônes	Fond blanc supposé	Poser un fond ou remplacer par une variante sombre
Ombre	Limite exprimée par un gris foncé	La réexprimer avec un trait (border)
Couleurs d’état	Vert et rouge vifs	Baisser la saturation et ajouter une icône

Enfin, revoyez aussi les couleurs des graphiques, des schémas et des statuts (succès en vert, alerte en rouge). Les couleurs très saturées scintillent et se lisent mal sur fond sombre : préparez des teintes plus posées pour le sombre. Ne transmettez pas l’état par la seule couleur ; ajoutez une icône ou un libellé pour atteindre aussi les lecteurs à contraste faible ou daltoniens. Quand vous faites relire par Claude Code, faites-lui chercher concrètement « les endroits où le contraste chute sur fond sombre », « les images supposant le blanc » et « les limites exprimées par une ombre » : il y aura moins d’oublis.

Pitfall checklist

Optimiser uniquement la capture d’écran peut dégrader le parcours réel.
Dépendre seulement de la couleur ou du mouvement réduit l’accessibilité.
Ne pas tester à 375px peut créer un débordement horizontal.
Oublier les données vides, les longs libellés et le réseau lent provoque des bugs.
Laisser Claude Code modifier des fichiers sans rapport rend la revue difficile.

Vérification

Demandez une seconde passe de review. Claude Code doit lister fichiers modifiés, risques, vérifications navigateur et contrôles manuels. Ensuite ouvrez la page en largeur mobile, vérifiez l’absence d’overflow, le défilement des blocs de code, le CTA et le focus clavier.

Angle monétisation

Ce sujet touche les annonces, cartes produit, liens de consultation, tarifs et formulaires. Pour l’appliquer dans un vrai dépôt, la page formation et conseil Claude Code transforme cette méthode en processus répétable.

Notes de revue supplémentaires

Comparez les captures avant/après et vérifiez CTA, annonces, texte, formulaires et blocs de code.
Demandez à Claude Code ce qui peut être supprimé, quels noms ne suivent pas le projet et quelles hypothèses sont risquées.
Avant déploiement, testez mobile, desktop, clavier, réseau lent, données vides et rechargement.

Note de test réel

J’ai testé le flux en trois temps: implémentation, review, contrôle mobile. Le diff reste lisible et les problèmes d’accessibilité apparaissent avant le déploiement.