Couleur sémantique vs couleur brute
Un token de couleur brute nomme la couleur elle-même : --blue-500, --gray-900. Un token sémantique nomme la fonction de la couleur : --primary, --background, --muted-foreground. Les composants peuvent ainsi ignorer les teintes littérales de la marque. Un bouton stylisé avec bg-primary text-primary-foreground fonctionnera avec un vert sauge, un rose vif ou un thème sombre, car le rôle reste fixe tandis que sa valeur change.
C'est le modèle popularisé par shadcn/ui et sur lequel s'appuie le thémage de Tailwind. Avec les tokens sémantiques, le changement de thème d'une application peut se limiter à un seul bloc :root. À l'inverse, des classes codées en dur comme bg-gray-900 et text-white transforment ce changement en une recherche fastidieuse dans tout le codebase.
La règle d'appariement du foreground
La plupart des rôles de base sont accompagnés d'un rôle -foreground associé pour le texte ou les icônes sur cette surface : --primary / --primary-foreground, --card / --card-foreground, --muted / --muted-foreground. Utilisez --primary-foreground sur --primary au lieu d'espérer que le foreground par défaut offre suffisamment de contraste. Chaque paire doit tout de même être vérifiée dans les deux modes.
Les 28 rôles nécessaires à un système complet
Une palette minimale de trois couleurs laisse 25 décisions sans réponse : états de survol, texte atténué, bordures, anneaux de focus, séries de graphiques, mode sombre. Un système complet les nomme tous. Les kits Identity Forge définissent ces 28 rôles, regroupés par fonction, pour les modes clair et sombre :
- Surfaces :
background/foreground,card/card-foreground,popover/popover-foreground. La page, les panneaux surélevés et les couches flottantes, chacun avec sa couleur de texte lisible. - Marque et emphase :
primary/primary-foreground,secondary/secondary-foreground,accent/accent-foreground. L'action principale, l'action secondaire et la mise en évidence. - Neutre et discret :
muted/muted-foreground. Arrière-plans atténués et texte secondaire. - État :
destructive/destructive-foreground,success/success-foreground,warning/warning-foreground. Erreurs, confirmations et avertissements. - Formulaire et focus :
border,input,ring. Séparateurs et contours, surfaces des champs de formulaire et indicateur de focus. - Données :
chart-1,chart-2,chart-3,chart-4,chart-5. Cinq couleurs de séries distinctes et conformes à la marque pour éviter que les graphiques ne retombent sur une palette générique.
L'importance de cinq couleurs de graphique
La visualisation de données est l'endroit où les systèmes sous-spécifiés échouent le plus visiblement : un tableau de bord avec trois couleurs de marque et un arc-en-ciel aléatoire pour son graphique à barres. Définir chart-1…5 dès le départ permet de maintenir les graphiques dans le même langage visuel que le reste de l'application.
Voir les rôles sur un kit réel
Voici ci-dessous le kit gratuit ambient-sage rendu entièrement à partir de ces tokens. La rangée d'échantillons correspond à --primary, --secondary, --accent et aux cinq rôles de graphique ; le bouton utilise --primary avec --primary-foreground ; les surfaces utilisent --background, --card et --muted. Rien ici n'est une couleur codée en dur :
Ambient Sage
Live renderRendered from the kit's actual tokens, fonts, and treatments
Typography
Plus Jakarta Sans
Color system
28 semantic roles, light + dark
Agent outputs
DESIGN.md, CSS, Tailwind, shadcn
Obtenir un ensemble complet de tokens
Vous pouvez définir les 28 rôles à la main, mais il est fastidieux de maintenir l'équilibre et l'accessibilité entre les modes clair et sombre. Chaque kit Identity Forge les fournit complets pour les deux modes, exportables en variables CSS, @theme Tailwind v3/v4, élément de registre shadcn ou JSON DTCG/W3C. Le moyen le plus rapide d'intégrer un ensemble complet dans un projet shadcn/ui :
npx shadcn add https://identityforge.io/r/ambient-sage.jsonLes tokens constituent également la moitié d'un DESIGN.md : les valeurs auxquelles le brief écrit fait référence. Ensemble, c'est ce que vous donnez à un agent de code pour que son UI reste cohérente.
FAQ
Que sont les design tokens de couleur sémantiques ?
Des variables de couleur nommées par rôle plutôt que par teinte : --primary, --background, --muted-foreground au lieu de --blue-500. Les composants sont stylisés selon le nom du rôle, donc le changement de thème ou le passage au mode sombre ne nécessite jamais de modifier les composants.
De combien de tokens de couleur un design system a-t-il besoin ?
Identity Forge utilise 28 rôles sémantiques : les surfaces avec leurs foregrounds, les rôles de marque et de couleurs atténuées, les couleurs d'état, les rôles de formulaire et cinq couleurs de graphique. Chaque rôle possède une valeur pour le mode clair et une pour le mode sombre.
Qu'est-ce que la convention -foreground ?
La plupart des rôles de base sont associés à un rôle -foreground pour le texte ou les icônes placés sur cette surface : --primary avec --primary-foreground. Cet appariement garantit un contraste lisible en modes clair et sombre, sans tâtonnement.
Comment exporter un ensemble complet de tokens sémantiques ?
Chaque kit Identity Forge exporte ses 28 rôles (clair + sombre) sous forme de variables CSS, de @theme Tailwind v3/v4, d'élément de registre shadcn ou de JSON DTCG/W3C. Pour shadcn/ui, la commande npx shadcn add https://identityforge.io/r/<slug>.json permet de les installer directement.