Guide : Les variables CSS (Custom Properties) expliquées

Prérequis

• Niveau : bases CSS (sélecteurs, propriétés courantes).
• Outils : VS Code + un navigateur moderne (DevTools onglet Computed → variables visibles).
• Temps estimé : 30 à 45 min.

Pourquoi les variables CSS ?

Avant les Custom Properties, changer la couleur principale d’un site demandait un find & replace dans toute la feuille de style. Avec les variables CSS, vous changez une ligne et tout suit. Bonus : elles sont modifiables en JavaScript et s’adaptent à la cascade — chose impossible avec Sass.

Les variables CSS : un outil révolutionnaire

Les variables CSS (ou Custom Properties) vous permettent de stocker des valeurs réutilisables dans votre feuille de styles. Changez une variable, et toutes les propriétés qui l’utilisent se mettent à jour automatiquement.

Syntaxe de base

/* Déclarer des variables (dans :root = global) */
:root {
    --couleur-principale: #667eea;
    --couleur-secondaire: #764ba2;
    --couleur-texte: #333333;
    --couleur-fond: #f8f9fa;
    --police: 'Segoe UI', sans-serif;
    --rayon-bordure: 8px;
    --ombre: 0 4px 15px rgba(0, 0, 0, 0.1);
    --espacement: 20px;
    --largeur-max: 1200px;
}

/* Utiliser les variables avec var() */
body {
    font-family: var(--police);
    color: var(--couleur-texte);
    background: var(--couleur-fond);
}

.bouton {
    background: var(--couleur-principale);
    border-radius: var(--rayon-bordure);
    padding: var(--espacement);
    box-shadow: var(--ombre);
}

.conteneur {
    max-width: var(--largeur-max);
    margin: 0 auto;
    padding: 0 var(--espacement);
}

Valeur de secours (fallback)

/* Si la variable n'existe pas, utilise la valeur de secours */
.element {
    color: var(--couleur-titre, #000000);
    padding: var(--padding-custom, 16px);
}

Variables locales (scope)

/* Variables globales */
:root {
    --couleur-principale: #667eea;
}

/* Variables locales : n'existent que dans ce composant */
.carte-danger {
    --couleur-principale: #e53935;
    background: var(--couleur-principale);  /* Rouge */
    color: white;
}

.carte-succes {
    --couleur-principale: #43a047;
    background: var(--couleur-principale);  /* Vert */
    color: white;
}

/* Le reste du site garde #667eea */

Cas pratique : Système de thèmes

:root {
    --bg: #ffffff;
    --text: #1a1a1a;
    --card-bg: #f5f5f5;
    --accent: #667eea;
}

/* Thème sombre */
[data-theme="dark"] {
    --bg: #1a1a2e;
    --text: #e0e0e0;
    --card-bg: #16213e;
    --accent: #818cf8;
}

/* Thème vert */
[data-theme="nature"] {
    --bg: #f1f8e9;
    --text: #2e7d32;
    --card-bg: #e8f5e9;
    --accent: #43a047;
}

/* Un seul CSS pour tous les thèmes ! */
body { background: var(--bg); color: var(--text); }
.card { background: var(--card-bg); }
a { color: var(--accent); }

Cas pratique : Composant bouton flexible

.btn {
    --btn-bg: var(--couleur-principale);
    --btn-color: white;
    --btn-size: 16px;
    --btn-padding: 10px 24px;
    --btn-radius: 8px;
    
    background: var(--btn-bg);
    color: var(--btn-color);
    font-size: var(--btn-size);
    padding: var(--btn-padding);
    border-radius: var(--btn-radius);
    border: none;
    cursor: pointer;
    transition: opacity 0.3s;
}

.btn:hover { opacity: 0.85; }

/* Variantes : juste changer les variables */
.btn-outline {
    --btn-bg: transparent;
    --btn-color: var(--couleur-principale);
    border: 2px solid var(--couleur-principale);
}

.btn-large {
    --btn-size: 20px;
    --btn-padding: 16px 40px;
}

.btn-pill {
    --btn-radius: 50px;
}

.btn-danger {
    --btn-bg: #e53935;
}

Variables CSS + calc() = puissance

:root {
    --base-size: 16px;
    --ratio: 1.25;
}

/* Échelle typographique automatique */
h1 { font-size: calc(var(--base-size) * var(--ratio) * var(--ratio) * var(--ratio)); }
h2 { font-size: calc(var(--base-size) * var(--ratio) * var(--ratio)); }
h3 { font-size: calc(var(--base-size) * var(--ratio)); }
p  { font-size: var(--base-size); }

/* Espacement proportionnel */
:root {
    --space-unit: 8px;
}
.mt-1 { margin-top: var(--space-unit); }           /* 8px */
.mt-2 { margin-top: calc(var(--space-unit) * 2); }  /* 16px */
.mt-3 { margin-top: calc(var(--space-unit) * 3); }  /* 24px */
.mt-4 { margin-top: calc(var(--space-unit) * 4); }  /* 32px */

Modifier les variables avec JavaScript

// Lire une variable CSS
const couleur = getComputedStyle(document.documentElement)
    .getPropertyValue('--couleur-principale');

// Modifier une variable CSS
document.documentElement.style.setProperty('--couleur-principale', '#e53935');

// Exemple : sélecteur de couleur
document.getElementById('couleur-picker').addEventListener('input', (e) => {
    document.documentElement.style.setProperty('--couleur-principale', e.target.value);
    // Tout le site change de couleur en temps réel !
});

Variables CSS vs Sass : comparaison

Erreurs fréquentes

Variable qui ne s’applique pas

Cause : oubli des deux tirets -- ou utilisation hors d’un sélecteur (les variables doivent vivre dans une règle, en général :root).
Solution : vérifiez la déclaration et utilisez les DevTools (onglet Computed) pour voir la valeur effective.

Pas de fallback → propriété ignorée

Cause : color: var(--couleur-titre); sans fallback ; si la variable n’existe pas, la déclaration est invalide et la couleur par défaut s’applique.
Solution : ajoutez un fallback : color: var(--couleur-titre, #000);.

Variables modifiées en JS qui « disparaissent »

Cause : on les déclare sur document.body mais on les lit depuis document.documentElement (ou inversement).
Solution : centralisez-les sur :root (= document.documentElement) et utilisez setProperty sur le même élément.

Confusion avec les variables Sass

Cause : on écrit $couleur au lieu de --couleur.
Solution : Sass est compilé statiquement, CSS est dynamique. Pour des thèmes ou JS, choisissez les variables CSS.

Exercice pratique

Variables CSS dynamiques avec JavaScript

L’avantage majeur des variables CSS sur les variables SASS est qu’elles vivent dans le DOM au moment de l’exécution. JavaScript peut donc les lire et les modifier dynamiquement, ce qui ouvre des cas d’usage impossibles avec les préprocesseurs. Le pattern de base : lire et écrire via style.setProperty et getComputedStyle.

// Lire la valeur courante d'une variable
const valeur = getComputedStyle(document.documentElement)
  .getPropertyValue('--primary');

// Modifier la variable globalement
document.documentElement.style.setProperty('--primary', '#ff6b6b');

// Modifier la variable sur un élément spécifique
element.style.setProperty('--accent', '#feca57');

Trois cas d’usage dominent en 2026. Premier cas : thème dark/light via une classe sur html qui change toutes les variables couleurs en un seul ajout/retrait de classe. Deuxième cas : customisation utilisateur dans une dashboard où l’utilisateur peut ajuster la couleur d’accent ou la taille de police, persistée en localStorage. Troisième cas : animations data-driven où une variable CSS pilote la position ou la taille d’un élément, mise à jour en JavaScript au scroll ou au mouvement de souris.

Système de design tokens : la structure recommandée

Pour un projet sérieux, organiser les variables CSS en couches hiérarchiques évite le chaos. Première couche : tokens primitifs, les valeurs brutes (couleurs hex, tailles px, durées ms). Deuxième couche : tokens sémantiques qui donnent du sens (texte-primaire, fond-surface, action-positive). Troisième couche : tokens componentisés, spécifiques à un composant (button-padding, card-radius).

:root {
  /* Primitive tokens */
  --color-blue-500: #2563eb;
  --color-gray-100: #f3f4f6;
  --space-4: 1rem;

  /* Semantic tokens */
  --color-primary: var(--color-blue-500);
  --color-surface: var(--color-gray-100);

  /* Component tokens */
  --button-bg: var(--color-primary);
  --button-padding: var(--space-4);
}

Cette structure permet de re-skiner toute l’application en modifiant uniquement la couche sémantique, sans toucher aux composants. C’est le pattern adopté par les design systems matures (GitHub Primer, Adobe Spectrum, Atlassian Design System) — il vaut largement les 30 minutes nécessaires à le mettre en place sur un nouveau projet.

Variables CSS et calcul : utiliser calc()

Les variables CSS s’utilisent dans calc(), ce qui permet des relations dynamiques entre valeurs. Par exemple, définir une taille de base et calculer toutes les autres tailles en dérivant : --text-lg: calc(var(--text-base) * 1.25). Quand vous changez --text-base, toute l’échelle typographique se rééquilibre automatiquement. Idem pour les espacements, les largeurs, les durées d’animation.

Trois bonnes pratiques. Premièrement, déclarer une variable de base par dimension (taille, espace, durée) plutôt qu’une multitude de valeurs absolues. Deuxièmement, utiliser des ratios harmoniques (1.125, 1.25, 1.333) pour les échelles typographiques plutôt que des progressions linéaires arbitraires. Troisièmement, vérifier régulièrement que calc() donne bien le résultat attendu — un oubli d’unité (calc(100% - 16) au lieu de calc(100% - 16px)) casse silencieusement le calcul.

Penser dès le départ aux variables comme à un contrat partagé entre développeurs et designers facilite la collaboration et limite les allers-retours sur des détails de couleur ou d’espacement.

Adaptation au contexte ouest-africain

Pour un développeur basé à Dakar, Abidjan, Bamako ou Cotonou qui maintient plusieurs sites WordPress ou applications PHP/Node, les variables CSS centralisent le thème dans un seul fichier. Cela permet de proposer plusieurs variantes de marque (charte couleur A pour client X, charte B pour client Y) en réutilisant 95 % du CSS et en ne dupliquant que les déclarations :root. Économie nette de 60 à 80 % de temps sur les projets clients en série.

Côté performance, les variables CSS sont gratuites côté navigateur — elles n’ajoutent aucun overhead à l’exécution par rapport à des valeurs en dur. Sur une 4G ouest-africaine, le gain vient principalement de la taille du fichier CSS final : un thème via variables CSS pèse 30 à 50 % moins que le même thème écrit avec des valeurs dupliquées partout. Pour les patterns décoratifs avancés, voir aussi le guide des pseudo-éléments CSS.

Variables CSS vs SASS : laquelle utiliser en 2026

SASS et les variables CSS coexistent sans se contredire. Le choix dépend du contexte. SASS est résolu à la compilation : les variables sont remplacées par leurs valeurs dans le CSS final, donc invisible côté navigateur. Cela permet d’utiliser SASS pour les valeurs structurelles (breakpoints, fonctions de conversion, mixins) et les variables CSS pour les valeurs thématiques (couleurs, typographie, espacements adaptables au runtime).

Concrètement en 2026, la combinaison gagnante est : SASS pour la logique de compilation (mixins, fonctions, imports modulaires, breakpoints), variables CSS pour le système de design tokens runtime (thèmes, customisation utilisateur, dark mode). Ne pas opposer les deux outils — ils résolvent des problèmes différents et se complètent.

Cascade et héritage : la portée des variables CSS

Les variables CSS suivent les règles de cascade et d’héritage CSS standards. Une variable déclarée sur :root est globale (accessible partout). Une variable déclarée sur un sélecteur plus spécifique (par exemple .dark-mode) écrase la valeur globale uniquement à l’intérieur de cet élément et ses descendants. Cette portée hiérarchique est puissante mais piégeuse — il faut comprendre comment les variables se propagent dans le DOM.

Trois patterns à connaître. Premier pattern : déclarer toutes les variables thème sur :root puis les surcharger localement sur un composant. Deuxième pattern : utiliser @media (prefers-color-scheme: dark) pour basculer automatiquement les variables selon les préférences système de l’utilisateur. Troisième pattern : isoler un composant avec ses propres variables locales pour éviter les fuites de styles.

Compatibilité navigateurs et fallbacks

Les variables CSS sont supportées par tous les navigateurs modernes depuis 2017. En 2026, vous pouvez les utiliser sans aucune réticence — Chrome, Firefox, Safari, Edge mobile et desktop les supportent à 100 %. Internet Explorer 11 ne les supporte pas, mais comme IE 11 a été abandonné par Microsoft en 2022, ce n’est plus une contrainte sauf cas particulier (administration française avec parc legacy obligatoire).

Pour les rares cas de fallback, la syntaxe var(--primary, #2563eb) donne une valeur par défaut si la variable n’est pas définie. Cela permet aussi de définir une cascade de fallbacks : var(--primary, var(--brand, #2563eb)) essaie --primary, puis --brand, puis utilise la valeur en dur. Pratique pour gérer les composants qui héritent partiellement d’un thème parent.

Outils et inspection des variables dans les DevTools

Chrome et Firefox affichent les variables CSS courantes dans le panneau Elements → Computed. Vous voyez toutes les variables disponibles sur l’élément sélectionné, leur valeur calculée, et leur source (de quel sélecteur elles proviennent). Cliquez sur une valeur pour la modifier en direct et voir le résultat sans recharger la page — c’est l’outil le plus rapide pour itérer sur un thème.

Lectures complémentaires avec des outils dédiés, des extensions comme VisBug (Chrome, gratuit) permettent d’éditer les variables CSS directement sur la page avec un panneau dédié. Pour les designers qui ne veulent pas toucher au code, Open Props propose une bibliothèque pré-faite de plus de 200 variables CSS bien pensées (couleurs, échelle typographique, espacements, ombres, bordures), à intégrer en une ligne dans n’importe quel projet.

Pour les équipes qui produisent plusieurs sites par an, formaliser le système de design tokens dès le premier projet et le réutiliser dans les suivants donne une cohérence visuelle de marque qui se voit immédiatement face à un concurrent qui réinvente sa charte à chaque livraison.

Pour creuser ce sujet

• Animations CSS sans JavaScript
• Maîtriser CSS Flexbox
• CSS Grid Layout
• Référence : MDN — Utiliser les Custom Properties
• Spécification : W3C — CSS Custom Properties for Cascading Variables Module