Le format de tokens DTCG expliqué

DTCG est le format d’échange JSON pour les design tokens défini par le Design Tokens Community Group. Chaque token est un objet portant une $value et un $type ; l’imbrication crée des groupes ; des chaînes comme {color.brand.600} référencent d’autres tokens ; et les types composites regroupent des propriétés liées — un token de typographie porte la famille, la taille, la graisse et l’interligne comme une seule valeur. Un fichier dans ce format se lit de la même façon pour tout outil qui le prend en charge, ce qui est la raison d’être du format.

Cet article parcourt l’anatomie sur des exemples réels, nomme les types qui valent la peine d’être connus, puis va au-delà du minimum de la spécification : ce que contient réellement un fichier de tokens généré complet, et la discipline qui garde un fichier sain quand outils et humains l’éditent tous les deux. C’est le chapitre sur le format de notre guide des design tokens.

À quoi ressemble un fichier DTCG ?

Un exemple élagué mais structurellement fidèle :

{
  "color": {
    "$description": "Palette generated from one blue seed.",
    "brand": {
      "600": {
        "$value": "#2563eb",
        "$type": "color",
        "$description": "Core brand step — oklch(0.546 0.215 262.9)"
      }
    }
  },
  "semantic": {
    "accent": { "$value": "{color.brand.600}", "$type": "color" }
  },
  "type": {
    "body-md": {
      "$type": "typography",
      "$value": {
        "fontFamily": "Inter",
        "fontSize": "16px",
        "fontWeight": 400,
        "lineHeight": "24px"
      }
    }
  }
}

Cinq mécanismes portent l’essentiel du format :

$value — ce que le token stocke. La seule propriété obligatoire.
$type — comment interpréter la valeur : "16px" est-il une dimension ou une chaîne ? Le type répond aux questions que le JSON brut ne peut pas résoudre.
Des groupes par imbrication. Des objets simples regroupent les tokens, et le chemin devient le nom : color.brand.600. Les groupes peuvent porter un $type dont héritent leurs tokens, c’est pourquoi les vrais fichiers le définissent souvent une seule fois par section.
$description — de la documentation qui voyage avec le token, jusque dans les docs et exports générés, au lieu de vivre dans un wiki qui dérive.
Des références. Une $value égale à "{color.brand.600}" fait d’un token l’alias d’un autre — le mécanisme à partir duquel la couche sémantique est construite.

La pièce restante est $extensions : un espace nommé (namespaced) pour des données spécifiques à un outil, afin qu’un outil puisse annoter les tokens sans entrer en collision avec la spécification ou avec d’autres outils.

Quels types de tokens comptent en pratique ?

Les types primitifs que vous rencontrerez réellement : color, dimension (des longueurs comme 23px ou 1.5rem), fontFamily, fontWeight, number et duration. Au-dessus se trouvent les types composites, où la valeur d’un token est un objet de sous-valeurs liées : typography (l’exemple ci-dessus), shadow (couleur, décalages, flou, étalement), border et transition.

Les composites existent parce que certains styles ne sont corrects qu’en tant que bundle. Un body-md qui porterait une taille mais pas son interligne laisserait la moitié du style à ce que le contexte se trouve hériter ; le composite fait du bundle l’unité de réutilisation. En termes de volume, la plupart des fichiers sont dominés par des tokens color et dimension, avec une poignée de composites assurant le gros du travail typographique.

Pourquoi un format standard compte-t-il ?

À cause du problème d’échange. Avant un format partagé, les outils de design et les pipelines de build inventaient chacun leur propre dialecte JSON, et déplacer des tokens entre deux d’entre eux exigeait un adaptateur — avec N outils, cela approche N² adaptateurs, chacun étant un endroit où les valeurs peuvent être mal traduites. Un standard réduit les adaptateurs : écrivez le fichier une fois, et tout outil conforme peut le consommer.

Le statut mérite d’être dit honnêtement : la spécification du format DTCG est un brouillon d’un groupe communautaire du W3C, pas encore un standard achevé. L’outillage a largement convergé vers elle en amont de la standardisation formelle — un schéma courant pour les formats qui résolvent un problème aigu — mais les détails peuvent encore bouger, c’est pourquoi cet article est signalé comme un article à revérifier au fil du temps.

Que contient un vrai fichier de tokens généré ?

Les exemples de la spécification sont volontairement minimaux — trois tokens et un groupe. Un fichier qui décrit un vrai design system est une expérience de lecture différente, et l’ordre de ses sections vous révèle l’architecture du système. L’export de Scale Composer est l’exemple travaillé ici ; de haut en bas, il porte :

$description — une ligne indiquant ce qu’est le fichier et d’où il vient.
meta — des faits au niveau du fichier, dont l’unité dans laquelle le système est exprimé (px ou rem).
scale — les trois paramètres partagés (base, ratio, notes par intervalle) dont dérivent à la fois la typographie et l’espacement.
Ancres du système — le petit ensemble de valeurs fixes auxquelles le reste du système est épinglé.
color — les rampes générées, hex à côté d’OKLCH.
spacing — les paliers nommés.
typography — l’ensemble des rôles composites, de la légende au display.
semantic et semantic-dark — les correspondances rôle-vers-valeur, une par thème, toutes deux générées à partir des mêmes couleurs de départ.
layout — les points de rupture et les largeurs de conteneur.
$metadata — la comptabilité en fin de fichier.

Lu dans l’ordre, cela donne : d’abord les paramètres, puis la matière brute, puis le sens, puis le sens par thème, puis la structure au niveau de la page. Un lecteur qui connaît l’ordre des sections peut répondre à « où vivrait X ? » sans chercher. Ouvrez un fichier généré dans la vue d’export de Scale Composer — les sections exactement dans cet ordre, avec les valeurs en direct : changez un paramètre d’échelle et regardez les sections dérivées se régénérer.

La vue d'export de Scale Composer affichant un fichier de tokens DTCG généré complet : sections description, meta, scale, color, spacing, typography, semantic et semantic-dark

Que se passe-t-il quand outils et humains éditent le même fichier ?

C’est la question de format à laquelle la spécification ne peut pas répondre à votre place, parce qu’elle relève du workflow. Un fichier de tokens réellement utilisé a deux sortes d’auteurs : un générateur qui possède les sections qu’il dérive, et des humains qui ajoutent ce dont le générateur ne sait rien — un groupe de composants, des $extensions propres au projet, une rampe supplémentaire importée d’ailleurs.

La règle qui rend cela sûr : un outil devrait préserver ce qu’il ne possède pas. Quand un générateur réécrit un fichier, les sections qu’il n’a pas créées doivent passer intactes. Le chemin d’import de Scale Composer maintient cela comme une propriété testée — chargez un fichier DTCG existant, ajustez, réexportez, et l’aller-retour laisse intactes les sections qu’il ne génère pas ; enregistrer, charger puis enregistrer à nouveau produit le même fichier. La conséquence est pratique plutôt que théorique : vos sections ajoutées à la main survivent à la régénération, donc adopter un générateur ne signifie pas lui abandonner le fichier entier. Sans la règle, la première régénération supprime silencieusement le travail — et une suppression silencieuse dans un fichier aussi central coûte cher à remarquer trop tard.

Lisez votre propre export

Les formats cessent d’être intimidants la première fois que vous lisez un fichier qui vous appartient. Chargez un fichier DTCG existant dans Scale Composer — ou exportez-en un nouveau — parcourez les sections en regard de la liste ci-dessus, trouvez où $type est hérité d’un groupe, suivez une {reference} jusqu’à sa cible, puis réexportez et faites un diff : les sections que vous n’avez pas touchées reviennent inchangées.