Conventions de nommage des jetons

Des noms de jetons incohérents rendent impossible toute prédiction de leur fonction sans lire leur valeur. Une convention de nommage claire et prévisible constitue la base d'un système de jetons évolutif.

Un modèle courant : [category]-[property]-[variant]. Exemples : color-text-primary, color-text-secondary, spacing-inset-sm. Chaque segment précise progressivement la signification.

Évitez les noms de palette comme blue-500 dans les composants. Utilisez des noms sémantiques : color-action-default, color-feedback-error. Les noms sémantiques restent valables lorsque les couleurs de la marque changent, sans mise à jour des composants.

Ajoutez l'état à la fin : color-button-bg-default, color-button-bg-hover, color-button-bg-disabled. Des suffixes d'état cohérents rendent les ensembles de jetons prévisibles et complets.

Utilisez systématiquement des tailles de vêtement (xs, sm, md, lg, xl) ou des échelles numériques (100, 200...900). Les échelles numériques permettent d'insérer des valeurs intermédiaires ; les tailles de vêtement sont plus lisibles pour les petits ensembles.

Pour les systèmes comportant plusieurs marques ou produits, préfixez les jetons avec un espace de noms : brand-a-color-primary contre brand-b-color-primary. Les espaces de noms empêchent les collisions lors de la fusion d'ensembles de jetons.

La notation kebab correspond directement aux propriétés personnalisées CSS : color-text-primary devient --color-text-primary. Les jetons en camelCase nécessitent une transformation ; ceux en notation kebab n'en nécessitent pas.

Les bons noms s'expliquent d'eux-mêmes : spacing-stack-md (espacement vertical entre des éléments empilés, moyen) exprime l'intention sans commentaire. Les noms médiocres comme s3 nécessitent une documentation externe pour être compris.

Une fois les jetons utilisés, les renommages constituent des changements incompatibles. Utilisez des alias d'obsolescence : conservez l'ancien nom, mais faites-le pointer vers le nouveau jeton. Accordez aux utilisateurs une période de migration avant de supprimer les jetons obsolètes.

Vérifiez les noms des jetons au moyen de règles personnalisées dans Style Dictionary ou d'un script d'intégration continue. Rejetez les jetons qui ne correspondent pas au modèle de nommage. Un contrôle automatisé empêche la dérive du nommage à mesure que le système se développe.

Publiez un guide de nommage contenant des exemples de noms corrects et incorrects. Organisez un bref atelier afin que les équipes de conception et d'ingénierie s'accordent sur les conventions avant le développement du système. La cohérence nécessite une compréhension commune, pas seulement de la documentation.

Pourquoi les jetons de composant doivent-ils utiliser des noms sémantiques plutôt que des noms de palette comme « blue-500 » ?

Une convention cohérente de nommage des jetons, fondée sur des modèles catégorie-propriété-variante, des noms sémantiques, des suffixes d’état et des préfixes d’espace de noms, rend les systèmes de jetons prévisibles, explicites et résistants aux changements de marque, sans modifier le code des composants.