Les propriétés personnalisées CSS pour les thèmes : héritage, valeurs de repli et @property

Ce que c'est

Une propriété personnalisée est toute déclaration dont le nom commence par -- ; var(--name, fallback) substitue sa valeur dans une autre déclaration. Le guide MDN indique que les propriétés personnalisées suivent la cascade et héritent du parent, que var() ne peut apparaître qu'à l'intérieur de valeurs de propriété (pas dans les sélecteurs, les noms de propriété ni les conditions de media queries et de container queries), et qu'une substitution invalide se comporte différemment d'un CSS invalide ordinaire : au lieu de rejeter la déclaration, le navigateur utilise la valeur initiale ou héritée de la propriété. @property enregistre une propriété personnalisée avec une syntax, un indicateur inherits et une initial-value, ce qui la rend typée et animable.

Pourquoi c'est important

La gestion des thèmes (couleurs de marque, densité, mode sombre, style par client) devient une question de redéfinition d'une poignée de propriétés sur un périmètre (:root, [data-theme="dark"], la racine d'un composant) au lieu de dupliquer des règles. Comme les valeurs vivent dans la cascade, elles peuvent être définies depuis des styles en ligne, depuis JavaScript avec style.setProperty, et par sous-arbre, et toute règle qui les lit se met à jour immédiatement.

Comment l'appliquer

• Définir deux couches : des jetons bruts (--blue-600: #2563eb) et des rôles sémantiques (--color-accent: var(--blue-600)) ; les composants ne consomment que les rôles, les thèmes ne redéfinissent que les rôles.
• Définir les valeurs par défaut sur :root et les surcharger sur un élément de périmètre ; éviter les valeurs par défaut au niveau des composants qui deviennent discrètement les valeurs réelles.
• Utiliser l'argument de repli pour les propriétés qu'une page hôte peut ne pas définir (var(--btn-bg, #333)) ; la page var() documente les replis imbriqués.
• Enregistrer avec @property les propriétés qui doivent s'animer ou être sûres côté type, et leur donner une initial-value ; les propriétés non enregistrées ne sont pas typées et s'animent de façon discrète.
• Préfixer les noms lors de la distribution de composants (--acme-btn-bg) ; toutes les propriétés personnalisées partagent un même espace de noms dans la cascade.
• Ne stocker des nombres sans unité que si chaque consommateur les multiplie (calc(var(--gap) * 1px)) ; une valeur est substituée comme des tokens, pas convertie.

Pièges

La règle de substitution invalide est silencieuse : color: var(--size) avec --size: 16px donne la couleur héritée, pas une erreur, et le repli n'aide pas car la variable est bien définie. Les propriétés personnalisées ne peuvent pas piloter les conditions de media queries, donc les points de rupture restent littéraux. Une propriété définie sur :root est héritée par tout, ce qui est pratique pour les thèmes et source de confusion pour l'état local d'un composant ; garder l'état local sur la racine du composant. Les valeurs définies par JavaScript sont des chaînes et ne sont pas validées avant utilisation.

Où var() est résolu

Une propriété personnalisée est substituée sur l'élément où elle est déclarée, au moment du calcul de la valeur, et les descendants héritent du résultat. --color-accent: var(--blue-600) sur :root hérite donc comme la couleur résolue, et redéfinir --blue-600 sur [data-theme="dark"] ou sur la racine d'un composant ne change pas --color-accent à cet endroit ; l'alias conserve la valeur calculée à :root. Les thèmes doivent redéfinir les propriétés de rôle (--color-accent) dans leur périmètre, ou redéclarer les alias en même temps qu'une palette différente. Le symptôme de cette erreur, un thème local dont les couleurs restent celles de la racine, ressemble à un problème de spécificité mais n'en est pas un.