LES JETONS QUI SURVIVENT

La plupart des systèmes de jetons de conception sont abandonnés au bout de deux ans, car ils codifient les valeurs visuelles du moment plutôt que l’intention sémantique qui les sous-tend. Un jeton nommé « blue-500 » reste à jamais associé à une valeur de bleu donnée ; un jeton nommé « accent-primary » survit à tout changement de couleur, car le prochain concepteur l’associera à l’équivalent « bleu » utilisé par le nouveau système.

La seule règle qui distingue les systèmes de jetons qui perdurent de ceux qui disparaissent : nommez les jetons en fonction de leur finalité, et non de leur apparence. accent-primary, surface-base, text-secondary, danger-bg. Jamais blue-500, gray-900, red-light. Le nom sémantique constitue le contrat ; la valeur n'est qu'un détail d'implémentation.

Couche 1 : primitives. Couleurs brutes, espacements, valeurs typographiques. bleu-50, bleu-100, bleu-200..., bleu-900. espace-1, espace-2..., espace-12. Ces éléments constituent l'échelle de base et changent rarement.

Couche 2 : sémantique. Des identifiants nommés en fonction de leur usage qui correspondent à des primitives. « accent-primary » correspond à « blue-500 », « accent-hover » à « blue-600 », « surface-base » à « gray-50 » et « text-primary » à « gray-900 ». Les composants font référence à ces identifiants, et jamais directement aux primitives.

Couche 3 : portée au niveau du composant. Jetons propres à chaque composant qui correspondent à des jetons sémantiques. « button-primary-bg » correspond à « accent-primary », « card-border » correspond à « border-subtle » et « nav-active-bg » correspond à « accent-emphasis ». Les composants utilisent ces jetons.

Lors d'une refonte de la marque, vous modifiez l'échelle des primitives et, éventuellement, la correspondance entre les éléments sémantiques et les primitives. Les jetons relevant du périmètre des composants restent inchangés. La nouvelle conception est déployée en quelques jours plutôt qu'en plusieurs mois.

Encode : couleur, espacement, typographie (familles de polices, tailles, graisses, hauteurs de ligne), rayon des bordures, ombre, durée et accélération des animations, largeurs des points de rupture.

Ne pas encoder : les valeurs spécifiques à la mise en page (largeur maximale de 1 280 dans le modèle d’article), les décalages de positionnement ponctuels, la chorégraphie d’animation propre à un seul composant. Ces éléments doivent figurer en ligne ; les encoder revient à créer un système qui se contredit lui-même.

Le test décisif : est-il plausible qu'un autre composant utilise cette même valeur ? Si oui, encodez-la. Si non, définissez-la en dur.

Propriétés CSS personnalisées au niveau de la limite des jetons. Définissez les primitives et la sémantique dans :root, puis remplacez-les dans [data-theme="dark"]. Les composants font référence aux jetons sémantiques, jamais aux primitives.

Des jetons accessibles en JS via un fichier TypeScript généré à partir de la même source. Des outils tels que Style Dictionary, Theo ou un petit générateur personnalisé produisent à la fois des variables CSS et des exportations TypeScript à partir d'une seule source JSON ou YAML. Grâce à cette source unique, les animations JS et les composants stylisés restent synchronisés avec les feuilles de style.

Documentez le système sur une seule page (une page Storybook ou une page /design sur le site lui-même) afin que les futurs contributeurs puissent le trouver. Les systèmes de jetons qui ne sont pas faciles à trouver finissent par être contournés en quelques mois par des personnes qui ignorent leur existence.