Implémentation axée sur les jetons

Les jetons portent les décisions visuelles réutilisables. Le CSS porte la façon dont ces décisions se composent dans un composant, une page ou un état. Cette frontière évite qu’une correction de composant crée silencieusement un deuxième système visuel.

Placer les décisions réutilisables dans les jetons#

Ajoutez un jeton avant de modifier une valeur qui devrait se répéter ou porter un rôle nommé :

• les couleurs, y compris les surfaces de syntaxe et de code
• les familles de polices, les tailles typographiques, les graisses et les traitements de libellés
• l’espacement, les rayons, les bordures, les ombres et le mouvement
• les contraintes de mise en page nommées et les seuils adaptatifs

Nommez le rôle, pas le littéral actuel. color.code.background peut survivre à un nouveau thème de code; color.dark-green ne peut pas expliquer sa raison d’être.

Garder la géométrie locale dans le CSS#

Le CSS peut garder une valeur lorsqu’elle décrit une relation locale plutôt qu’une décision réutilisable. Par exemple : un pourcentage dans une formule de grille, un décalage optique d’icône ou une expression min() ou clamp() composée à partir de jetons.

Ne promouvez pas chaque nombre mécaniquement. Promouvez la décision lorsqu’un autre composant pourrait raisonnablement avoir besoin du même rôle.

Vérification#

Exécutez npm run tokens:update après avoir modifié les valeurs sources des jetons. La commande régénère le CSS et les données Hugo des jetons, puis vérifie les deux sorties. npm run tokens:check refuse aussi les littéraux de couleur hexadécimaux bruts dans assets/css/site.css; ajoutez un jeton sémantique au lieu de contourner la règle.

tailwind.tokens.cjs est généré depuis l’API publique des jetons, donc les utilitaires approuvés de couleur, police, graisse, taille et approche se résolvent par des variables de jetons générées sans deuxième association manuelle. npm run tokens:check refuse les utilitaires de palette non gouvernés et les valeurs typographiques arbitraires brutes. Utilisez les valeurs arbitraires seulement pour une géométrie locale documentée; une valeur visuelle réutilisable appartient dans tokens/core.tokens.json, même lorsqu’une classe utilitaire peut l’exprimer plus vite.

Ordre de migration#

Migrez d’abord les décisions répétées les plus visibles : les couleurs brutes, les traitements de libellés partagés, les rayons, la décoration des liens, puis les contraintes adaptatives. Chaque migration doit préserver le rendu, mettre à jour les données de référence des jetons et être vérifiée sur les deux sites.