Un jeton de couleur brute nomme la couleur elle-même : --blue-500, --gray-900. Un jeton sémantique nomme la fonction de la couleur : --primary, --background, --muted-foreground. Les composants peuvent alors ignorer les teintes littérales de la marque. Un bouton stylisé avec bg-primary text-primary-foreground fonctionnera avec du vert sauge, du 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 celui sur lequel repose le thémage de Tailwind. Avec des jetons sémantiques, la refonte du thème d'une application peut se limiter à un seul bloc :root. Les classes codées en dur telles que bg-gray-900 et text-white transforment ce même changement en une recherche complexe dans toute la base de code.

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 un contraste suffisant. Chaque paire doit tout de même être vérifiée dans les deux modes.

Une palette minimale de trois couleurs laisse 25 décisions non définies : états de survol, texte atténué, bordures, anneaux de focus, séries de graphiques, mode sombre. Un système complet les nomme toutes. Les kits Identity Forge définissent ces 28 rôles, regroupés par fonction, pour le mode clair et sombre :

• Surfaces : background / foreground, card / card-foreground, popover / popover-foreground. La page, les panneaux surélevés et les couches flottantes, chacune 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.
• Discret et neutre : 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 de champs de formulaire et indicateur de focus.
• Données : chart-1, chart-2, chart-3, chart-4, chart-5. Cinq couleurs de série distinctes respectant la marque pour que les graphiques ne se rabattent pas sur une palette par défaut générique.

Ci-dessous se trouve le kit gratuit ambient-sage entièrement rendu à partir de ces jetons. La rangée d'échantillons contient --primary, --secondary, --accent et les 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 :

Vous pouvez définir les 28 rôles à la main, mais il est fastidieux de maintenir l'équilibre et l'accessibilité entre le mode clair et sombre. Chaque kit Identity Forge les fournit complets dans 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.json

Les jetons constituent également la moitié d'un DESIGN.md : les valeurs auxquelles le brief écrit fait référence. Ensemble, ils sont ce que vous donnez à un agent de codage pour que son interface reste cohérente.