Revoir les changements de tokens dans Git

La couleur d’accent a changé un mardi, et personne ne l’avait décidé. La pull request s’intitulait « regenerate tokens after spacing fix » ; le fichier de tokens affichait quarante et une lignes modifiées, dont une qui re-pointait accent de brand-600 vers secondary-500. Le relecteur a vu un fichier généré et un build vert, et il a approuvé. Trois semaines plus tard, le marketing a demandé pourquoi les boutons d’inscription avaient une couleur différente sur les nouvelles captures d’écran. git log -p a retrouvé la ligne en une minute environ — c’est la comédie amère de l’histoire : l’historique était parfait, et la revue que cet historique existe précisément pour permettre a pris dix secondes que personne n’a passées.

Les design tokens ont leur place dans la gestion de versions parce qu’ils font se comporter les décisions de design comme du code : l’historique enregistre qui a changé la couleur d’accent, quand et — dans le message de commit — pourquoi ; une pull request devient un artefact de revue de design ; et un mauvais changement est un git revert plutôt qu’un chantier archéologique. Mais les bénéfices n’arrivent qu’avec de la discipline dans le flux de travail : des diffs gardés petits et stables, une checklist de revue qui lit les lignes de tokens comme des décisions de design, et les changements régénérés séparés des éditions à la main.

C’est le chapitre gouvernance de notre guide des design tokens : à quoi ressemble un diff de tokens, ce qu’un relecteur devrait lui demander, et les bonnes manières qui gardent un fichier généré relisable. Il suppose le schéma de projet où le fichier de tokens vit dans le dépôt et passe par la même porte que le code.

Pourquoi les design tokens ont-ils leur place dans la gestion de versions ?

La gestion de versions donne à n’importe quel fichier trois propriétés — un historique attribué, un changement contrôlé, un passé restaurable — et les tokens sont singuliers parmi les artefacts de design : ils peuvent réunir les trois. Les décisions de design ont sinon une provenance notoirement mince : la réponse à « pourquoi cette couleur d’accent est-elle de ce bleu ? » a tendance à vivre dans un fil de discussion abandonné, une vieille présentation ou la mémoire de quelqu’un. Une fois que la décision est une ligne dans un fichier versionné, le message de commit devient un endroit où la justification se trouve en permanence à côté du changement qu’elle explique — re-point accent to secondary for the promo quarter; revert after Q3 documente une décision de design de manière plus durable que ce que réussit la plupart de la documentation de design.

Le rollback, c’est la même propriété lue à l’envers. Un changement de marque qu’il faut annuler tient en un seul revert quand il a la forme d’un token ; sans le fichier, c’est une chasse à travers les feuilles de style pour chaque valeur qui a changé, des semaines après que quiconque se souvienne de les avoir changées.

La raison intuitive pour laquelle la revue fonctionne ici, et pas sur la plupart des artefacts de design : la revue dépend de la capacité à tenir un changement dans sa tête. Un changement dans un fichier de design est une image — le relecteur voit le nouvel état, pas le delta. Un changement de token est le delta : une poignée de lignes nommées. Les tokens compressent la couche de design jusqu’à une taille que la revue peut réellement traiter, et tout le reste de cet article s’appuie sur cette compression.

À quoi ressemble un diff de tokens ?

Voici un diff de six lignes, réduit à ses lignes modifiées et annoté avec les sections où elles se trouvent — un pas d’espacement resserré, une couleur d’accent re-pointée, un rôle sémantique ajouté :

@@ spacing @@
-"space-3":    { "$value": "16px", "$type": "dimension" }
+"space-3":    { "$value": "14px", "$type": "dimension" }
@@ semantic @@
-"accent":     { "$value": "{color.brand.600}",     "$type": "color" }
+"accent":     { "$value": "{color.secondary.500}", "$type": "color" }
+"text-promo": { "$value": "{color.neutral.900}",   "$type": "color" }
@@ semantic-dark @@
+"text-promo": { "$value": "{color.neutral.50}",    "$type": "color" }

Chaque ligne devrait déclencher une question de revue précise :

• space-3, 16px → 14px. Une primitive — le changement se propage à tous les consommateurs. Qui lit space-3 ? Si la réponse est le padding des cartes, les écarts de liste et les rangées de formulaire, le resserrement se lit-il comme voulu dans tous les cas, ou visait-il un seul écran surchargé ? Une primitive éditée pour corriger un seul composant est une odeur de token classique ; la correction ciblée vit au niveau du composant, pas dans le pas partagé.
• accent, re-pointée. Une sémantique — ciblée, mais porteuse : quels composants consomment accent, et le texte posé sur l’accent franchit-il toujours son plancher de contraste face au nouveau remplissage ? Une ligne dans le diff, une re-vérification complète derrière elle. Plus une question de processus : ce re-pointage est-il bien ce que le titre de la PR dit que la PR fait ?
• text-promo, ajoutée deux fois. Un nouveau rôle : est-ce un vrai travail qu’un deuxième consommateur utilisera un jour, ou un cas unique qui a sa place plus près de son composant ? Le nom respecte-t-il les conventions ? Il apparaît dans les deux sections de thème — bien ; une sémantique présente uniquement en clair est un bug de mode sombre à retardement.

Remarquez ce que le relecteur n’a jamais demandé : si le JSON se parse. Les machines vérifient la syntaxe avant que la revue ne commence ; tout le travail du relecteur, c’est l’ensemble des questions de design qu’aucun linter ne peut poser.

Ouvrez dans Scale Composer le fichier d’où viennent ces lignes — le fichier de tokens canonique tel qu’il vit dans un dépôt, les sections dans un ordre stable, portant les mêmes noms que ceux qu’affiche le diff.

Que doit vérifier la revue d’une pull request de tokens ?

Quatre vérifications couvrent l’essentiel :

1. Rayon d’impact. Quelle couche a changé ? Un changement de primitive se propage à tout ce qui la référence, directement ou via des alias — une édition d’une ligne peut être le plus gros changement de la release. Un re-pointage sémantique est ciblé : les consommateurs de ce seul rôle. Lisez la couche d’abord ; elle fixe la profondeur dont le reste de la revue a besoin.
2. Contraste, pour chaque ligne de couleur. Tout remplissage modifié ou rôle de texte re-pointé signifie re-vérifier les paires auxquelles il participe — une ligne ici, parce que la vérification du contraste est une discipline à part entière ; c’est dans la revue qu’elle est planifiée.
3. Cohérence de nommage. Confrontez les nouveaux tokens aux conventions du projet au dernier moment où c’est peu coûteux : avant le merge, un renommage est un commentaire de revue ; après le merge, c’est un changement cassant pour chaque consommateur.
4. Pas d’orphelins. Un nouveau token devrait être consommé par quelque chose, sinon il part comme une spéculation que quelqu’un devra faire correspondre par le nom plus tard. Un token supprimé ne devrait être référencé par rien — une {reference} pendante est un échec au prochain export, trouvé maintenant ou trouvé plus tard.

Comment garder les diffs générés lisibles ?

Les fichiers générés ont un mode de défaillance particulier en revue : si l’outil réordonne les clés ou reformate à chaque sauvegarde, chaque diff est une réécriture, et les relecteurs apprennent à survoler — c’est exactement ainsi qu’est passée la couleur d’accent du mardi. Trois disciplines l’empêchent :

• Sérialisation stable. L’outil doit écrire le fichier de la même façon à chaque fois. Scale Composer sérialise de manière canonique — ordre de sections stable, ordre de clés stable ; sauvegarder, charger puis re-sauvegarder est un point fixe testé — donc un changement d’une seule valeur produit un diff d’environ une ligne, et quarante et une lignes modifiées signifient quarante et une décisions plutôt que du bruit.
• Séparez la régénération des éditions à la main. Un commit qui re-dérive le système (« re-derive after seed change ») et un commit qui ajoute une section à la main appellent des modes de revue différents — le premier est relu pour ses paramètres, le second ligne par ligne. Les mélanger enterre le jugement dans le bruit.
• Des messages de commit qui énoncent la décision. « tighten space-3 to 14px — density pass on forms » se lit comme une justification de design un an plus tard ; « update tokens » ne se lit comme rien.

Une frontière est délibérée : Scale Composer n’a pas de vue de diff. Le diff, c’est le travail de git — le travail de l’outil est de garder le fichier diffable, ce qui explique pourquoi la sérialisation canonique est la fonctionnalité et pas une interface de diff.

Faites passer le prochain changement par la revue

Le flux de travail se justifie tout seul la première fois qu’un diff attrape quelque chose. Réajustez une valeur dans Scale Composer et exportez — resserrez un pas d’espacement ou re-pointez un rôle, écrasez le fichier committé, et lisez ce que git diff vous montre : tout le changement en quelques lignes stables, prêt pour les quatre questions d’un relecteur.