Importer vos tokens existants sans rien perdre

Avant de confier un fichier auquel vous tenez à un outil de tokens, faites une expérience : importez le fichier, ne changez rien, exportez-le, puis comparez le résultat à l’original. Le test complet prend environ cinq minutes, et le diff sert de référence de moralité à l’outil — il montre exactement ce que l’outil considère comme sien et ce qu’il réécrit en silence.

Importer des design tokens sans rien perdre se résume à une propriété : un outil bien élevé possède les sections qu’il génère et préserve tout le reste, de sorte que enregistrer→charger→enregistrer soit un point fixe — le fichier qui ressort est le fichier qui est entré, sauf là où vous avez demandé un changement. Un outil doté de cette propriété peut être adopté de façon incrémentale ; un outil qui en est dépourvu impose une migration du tout ou rien. Cet article couvre la mécanique de fichier de l’import et du ré-export ; les fondamentaux plus larges vivent dans notre guide des design tokens.

Pourquoi l’import de tokens fait-il peur ?

Parce qu’un vrai fichier de tokens est rarement seulement ce qu’un outil a généré. Laissez un fichier vivre un an en production et il accumule du travail fait main : des tokens de composant que quelqu’un a ajoutés pour une exception légitime, des blocs $extensions portant des métadonnées de plateforme, les durées d’animation d’un collègue dont aucun générateur n’a le moindre modèle. Cette accumulation, c’est le fichier qui fait son travail — une seule source, qui grandit avec le système.

Le scénario redouté, c’est un outil naïf face à ce fichier. Un import naïf lit les parties que l’outil comprend ; un export naïf régénère tout le fichier à partir de ce qui a été lu. Import → export → la moitié du fichier disparue : la section d’animation, les extensions, les exceptions ajoutées à la main — tout ce que l’outil n’a pas modélisé, supprimé par omission plutôt que par intention. Les équipes qui vivent cela une fois apprennent à tenir l’outil à l’écart du vrai fichier et à maintenir les tokens à la main — ce qui abandonne discrètement l’essentiel de ce à quoi l’outillage servait.

En quoi consiste le contrat d’aller-retour ?

Trois clauses. Premièrement, la propriété est sectorielle : l’outil déclare quelles parties du fichier il génère — les rampes de couleur, l’échelle typographique, les couches sémantiques — et traite tout le reste comme territoire étranger. Deuxièmement, la préservation est littérale : les sections étrangères passent inchangées, pas « re-sérialisées mais équivalentes ». Troisièmement, la sortie est canonique : l’outil écrit ses propres sections sous une seule forme et un seul ordre stables, si bien que deux exports ne diffèrent que là où les décisions diffèrent et que les diffs restent révisables.

L’expérience d’ouverture vérifie les trois d’un coup. Enregistrer→charger→enregistrer devrait être un point fixe — un état que l’opération renvoie sur lui-même, au sens emprunté aux mathématiques (point fixe) — et l’aller-retour de Scale Composer est testé précisément ainsi : un fichier importé se ré-exporte avec ses sections intouchées intactes, et l’ordre canonique maintient chaque diff ultérieur au minimum.

À quoi ressemble une section préservée à travers un cycle réel ?

Prenez un fichier avec une section générée et une section ajoutée à la main :

{
  "color": {
    "brand": {
      "600": { "$type": "color", "$value": "#2563eb" }
    }
  },
  "motion": {
    "duration-fast": { "$type": "duration", "$value": "150ms" },
    "duration-slow": { "$type": "duration", "$value": "400ms" }
  }
}

La section color est le territoire du générateur ; motion est le travail fait main d’un collègue — un outil de couleur et d’échelle n’a aucune notion de durées. Importez le fichier, redérivez la palette à partir d’une nouvelle couleur de départ, exportez. Les entrées color.brand changent : brand-600 garde son nom et stocke une nouvelle valeur à la place de l’ancien #2563eb — oklch(0.546 0.215 262.9) — avec la rampe redérivée autour, et le diff contient ces lignes et rien d’autre. motion revient inchangé, les deux durées intactes, toujours à sa place.

Exécutez ce cycle sur un fichier importé dans Scale Composer — chargez un fichier DTCG qui porte des sections que l’outil ne génère pas, ajustez la couleur de départ, et exportez : les sections de couleur se redérivent tandis que les sections ajoutées à la main traversent intactes.

Que devriez-vous auditer avant de confier votre fichier à un outil ?

Quatre vérifications, ordonnées par ce qu’elles attrapent :

1. L’aller-retour à vide. Importez, ne changez rien, exportez, comparez. Les différences acceptables vivent uniquement dans les sections que l’outil génère (re-sérialisation canonique) ; un diff qui touche quoi que ce soit d’autre, c’est l’outil qui vous dit ce qu’il finira par dévorer.
2. La survie de $extensions. L’emplacement désigné du format DTCG pour les métadonnées propres aux outils et aux plateformes est précisément le contenu qu’un importeur négligent laisse tomber. Vérifiez que les vôtres sont passées intactes.
3. Les commentaires — honnêtement, il n’y en a aucun à perdre. DTCG, c’est du JSON, et JSON n’a pas de syntaxe de commentaire ; les notes qui comptent ont leur place dans les champs $description, qui font partie du format et survivent à tout outil conforme. Si votre workflow gardait des annotations à un endroit fragile, l’import est un bon moment pour les y migrer.
4. La stabilité de l’ordre. Exportez deux fois, puis exportez après un changement trivial. Si l’ordre des clés se mélange d’une exécution à l’autre, chaque diff futur enterrera le vrai changement sous des changements fantômes, et relire les modifications de tokens devient de l’archéologie aussi longtemps que le fichier vit.

Comment la préservation rend-elle l’adoption incrémentale ?

Parce qu’un outil qui préserve n’exige pas tout le fichier. Une équipe peut lui confier d’abord les sections de couleur — importer, redériver, exporter, relire un diff qui ne touche que la couleur — pendant que l’espacement et la typographie restent gérés à la main dans le même fichier. Le trimestre suivant, l’espacement. L’outil s’installe dans le fichier section par section, chaque étape étant un petit changement révisable plutôt qu’un événement de migration.

C’est le bénéfice pratique de la propriété de point fixe, et la raison intuitive pour laquelle elle compte : la confiance se construit en bornant le rayon d’explosion. Un outil qui ne sait que tout réécrire réclame une confiance totale dès le premier jour ; un outil qui préserve ne demande de la confiance que sur les sections que vous lui confiez, et les sections qu’il n’a pas encore méritées n’ont jamais été en danger. « Changer d’outil de tokens » cesse d’être une décision et devient une série d’expériences peu coûteuses et réversibles.

Faites le test avant d’avoir besoin d’y faire confiance

L’audit n’est pas un travail hypothétique — c’est cinq minutes et un diff. Faites le test enregistrer→charger→enregistrer dans Scale Composer — importez un fichier de tokens, exportez-le tel quel et comparez ; puis faites un changement délibéré et confirmez que le diff est exactement ce changement et rien de plus.