Architecture de jetons multi-thèmes et multimarques

Un thème modifie le mode de couleur d’une même marque (versions claire et sombre d’un même produit). Une marque correspond à une identité visuelle différente : les mêmes composants du système de conception sont rendus avec des couleurs, une typographie et des espacements différents pour servir différents produits ou clients. Les deux utilisent la même architecture de jetons, mais à des niveaux d’abstraction différents.

Les jetons primitifs constituent la palette complète des valeurs brutes disponibles pour le système. Ils incluent chaque nuance de couleur (color-blue-50 à color-blue-900), chaque unité d’espacement et chaque taille de police. Les jetons primitifs ne sont jamais utilisés directement dans les composants : ils sont uniquement référencés par les jetons sémantiques. La palette est définie une seule fois et partagée entre tous les thèmes et toutes les marques.

Les jetons sémantiques expriment une intention : color-background-page, color-text-primary, color-action-primary. Chaque jeton sémantique fait référence à une valeur de jeton primitif appropriée au thème actuel. Les composants sont construits exclusivement à partir de jetons sémantiques. C’est à ce niveau que la thématisation a lieu.

Dans le thème clair : color-background-page fait référence à color-white, color-text-primary fait référence à color-gray-900 et color-action-primary fait référence à color-blue-500. Ces correspondances sont définies dans un fichier de jetons propre au thème, qui remplace la couche sémantique pour le contexte clair.

Dans le thème sombre : color-background-page fait référence à color-gray-950, color-text-primary fait référence à color-gray-50 et color-action-primary fait référence à color-blue-400 (légèrement plus clair pour assurer le contraste sur les arrière-plans sombres). Seules les correspondances sémantiques changent : la palette primitive et tous les composants restent inchangés.

La marque A utilise le bleu comme couleur principale (color-action-primary: {color-blue-500}). La marque B utilise le vert (color-action-primary: {color-green-500}). Le composant bouton lit var(--color-action-primary) : il ignore complètement la marque active. Les remplacements propres aux marques modifient uniquement les correspondances des jetons sémantiques, jamais le code des composants.

Les propriétés personnalisées CSS rendent le changement de thème à l’exécution très simple. Stockez le thème actuel dans un attribut de données : document.documentElement.setAttribute('data-theme', 'dark'). Les règles CSS remplacent les jetons sémantiques sous [data-theme="dark"]. Le navigateur résout immédiatement toutes les références var() vers les nouvelles valeurs : aucun nouveau rendu JavaScript n’est nécessaire.

Pour différentes marques déployées séparément, utilisez une thématisation à la compilation : générez des fichiers CSS de jetons distincts pour chaque marque avec Style Dictionary, puis chargez la feuille CSS correspondant à la bonne marque au démarrage de l’application. Cette approche convient lorsque la marque est déterminée au moment du déploiement (domaines, sous-domaines ou instances en marque blanche différents), et non lors d’une interaction avec l’utilisateur.

Un système prenant en charge plusieurs marques et plusieurs thèmes nécessite une matrice à deux dimensions : Marque A claire, Marque A sombre, Marque B claire, Marque B sombre. Les propriétés personnalisées CSS gèrent cela élégamment avec des sélecteurs imbriqués : [data-brand="a"][data-theme="dark"] remplace les jetons sémantiques pour cette combinaison précise. Quatre combinaisons correspondent à quatre blocs CSS, et non à quatre bases de code.

À mesure que le système de conception évolue, des jetons sont ajoutés, renommés ou supprimés. Versionnez les jetons dans le même dépôt que le code. Lorsqu’un jeton devient obsolète, conservez son ancien nom comme alias pointant vers le nouveau pendant un cycle de publication, ajoutez un commentaire indiquant son obsolescence et mettez à jour le code qui l’utilise. Coordonnez les changements de jetons entre la conception et l’ingénierie au moyen d’un journal des modifications structuré.

La gouvernance définit qui peut ajouter ou modifier des jetons et quel processus de revue est requis. Les jetons primitifs nécessitent l'approbation de l'équipe de conception. Les jetons sémantiques nécessitent une revue de la conception et de l'ingénierie. Les jetons de composant peuvent être gérés par le propriétaire du composant. Sans cette gouvernance, des jetons en double apparaissent et la garantie de « source unique de vérité » est compromise.

Les thèmes modifient les modes de couleur au sein d'une marque ; les marques correspondent à des identités visuelles différentes. Les jetons primitifs constituent la palette brute, tandis que les jetons sémantiques expriment une signification et permettent la thématisation. Les composants utilisent uniquement des jetons sémantiques. Le mode sombre et les remplacements liés à la marque ne modifient que les correspondances des jetons sémantiques : les composants restent inchangés. La thématisation à l'exécution utilise des propriétés personnalisées CSS avec des sélecteurs [data-theme] ; la définition de la marque à la compilation génère un fichier CSS distinct pour chaque marque. La gouvernance des jetons et la gestion des versions assurent la cohérence du système au fil de son évolution.