Architecture des jetons

Cette page est la référence d’implémentation du système de jetons. Fondations > Jetons > Introduction explique le vocabulaire et l’intention; cette page décrit la source, les transformations, les sorties, les consommateurs et les vérifications qui rendent le système fiable.

Limite des responsabilités#

tokens/core.tokens.json est la source unique des décisions de conception partagées. Il contient les champs DTCG $value et $type, puis les métadonnées de gouvernance du site : category, kind, visibility, order, des descriptions bilingues et, au besoin, le contexte web ou brand.

Les composants et les gabarits consomment des jetons sémantiques. Ils ne possèdent pas les valeurs de couleur, d’espacement, de typographie, de rayons, d’ombres, de mouvement ou de points d’arrêt. Une valeur CSS répétée est un signal pour ajouter ou réutiliser un jeton sémantique, non pour introduire une autre valeur locale.

kind classe l’intention; il ne résout pas les valeurs. Une référence DTCG comme {color.palette.signal-orange} est un alias. L’outillage de données résout les alias, détecte les références inconnues et les cycles, puis fournit resolved_value à la documentation et aux vérifications de contraste.

Sources et collections#

Style Dictionary lit intentionnellement seulement core.tokens.json. Les collections de thèmes sont des remplacements ciblés par sélecteur; les traiter comme des sources Style Dictionary additionnelles créerait des collisions de noms. scripts/generate-theme-tokens.mjs possède donc leur transformation plus petite et explicite.

outputReferences: true préserve un alias sémantique dans le CSS généré lorsqu’une propriété personnalisée CSS peut référer à une autre propriété générée. Cette option ne crée pas d’alias : une valeur source $value doit contenir une référence DTCG pour que cette relation existe.

Graphe de build#

flowchart TD
    CORE["tokens/core.tokens.json"]
    LIGHT["tokens/themes/light.tokens.json"]
    DARK["tokens/themes/dark.tokens.json"]
    SD["Style Dictionary\ntokens:build"]
    DATA["generate-token-data\ntokens:data"]
    TW["generate-tailwind-tokens\ntokens:tailwind"]
    THEME["generate-theme-tokens\ntokens:themes"]
    DIAGRAM["generate-diagram-tokens\ntokens:diagrams"]
    CSS["assets/css/generated/tokens.css"]
    YML["data/brand/tokens.yml"]
    TWC["tailwind.tokens.cjs"]
    THEME_CSS["assets/css/generated/themes.css"]
    JSON["static/tokens/diagram.json"]
    HUGO["Hugo + PostCSS\npaquet du site"]
    DOCS["Tableaux de référence"]
    EXTERNAL["Mermaid et outils de diagrammes"]
    CHECK["tokens:check + CI"]

    CORE --> SD --> CSS --> HUGO
    CORE --> DATA --> YML --> DOCS
    CORE --> TW --> TWC --> HUGO
    CORE --> DIAGRAM --> JSON --> EXTERNAL
    LIGHT --> THEME --> THEME_CSS --> HUGO
    DARK --> THEME
    CORE --> CHECK
    LIGHT --> CHECK
    DARK --> CHECK
    CSS --> CHECK
    YML --> CHECK
    TWC --> CHECK
    THEME_CSS --> CHECK
    JSON --> CHECK

npm run tokens:update exécute chaque générateur puis vérifie le résultat. Les sorties générées sont validées avec leur source afin que la révision et le déploiement voient le même état.

Artefacts générés et consommateurs#

Hugo charge le CSS généré principal et celui des thèmes avant la feuille de style traitée du site. Tailwind lit le pont généré pour les couleurs publiques, le type, l’espacement, les rayons, les ombres, le mouvement et les points d’arrêt. CSS ne peut pas utiliser de propriétés personnalisées dans les conditions de media queries; les valeurs de points d’arrêt générées sont donc intentionnellement littérales dans la configuration Tailwind.

Les tableaux de documentation sont rendus depuis le YAML généré; leur prose ne duplique jamais l’inventaire des jetons. Le guide des diagrammes utilise les valeurs claires résolues exportées en JSON pour Mermaid, OmniGraffle, draw.io et XMind.

Thèmes et sélection à l’exécution#

Les collections claire et sombre remplacent les mêmes chemins sémantiques : encre, papier, ligne, accent et l’échelle neutre. La géométrie et le comportement restent dans les jetons principaux, à moins qu’un mode les change réellement.

Le gabarit de base définit data-theme avant le chargement de la feuille de style. Il utilise la valeur enregistrée bhdicaire-theme lorsqu’une personne a choisi un mode; sinon, il suit prefers-color-scheme. Le sélecteur de thème est une amélioration progressive qui modifie l’attribut et enregistre un choix explicite. Les composants lisent seulement les variables sémantiques; aucun ne choisit lui-même un thème.

Validation et routine de changement#

Lorsqu’on ajoute ou modifie un jeton :

1. Modifiez tokens/core.tokens.json; choisissez un type DTCG, un rôle sémantique, des métadonnées et la visibilité public ou internal.
2. Utilisez un alias lorsque le sens devrait survivre à un changement de palette ou d’échelle. Ne faites pas remonter les primitives de palette dans le CSS de composant.
3. Ajoutez des remplacements clairs et sombres correspondants seulement lorsque la couleur sémantique doit différer par mode.
4. Exécutez npm run tokens:update, examinez les changements générés, puis utilisez le jeton public dans le CSS, Tailwind, un composant ou une page de documentation pilotée par des données.
5. Exécutez npm run lint et npm run lint:build avant de valider.

N’écrivez pas une valeur d’affichage répétée en dur, ne créez pas de branche de thème propre à un composant, n’utilisez pas une primitive de palette interne directement hors de l’implémentation des jetons et ne maintenez pas à la main des valeurs que l’export de diagrammes peut fournir.