Starter de design tokens au format DTCG (clair et sombre)

Ce starter s’adresse aux designers UI et aux développeurs front-end qui lancent un design system ou un nouveau projet et ne veulent pas partir d’une page blanche. Il fournit des fondations prêtes à l’emploi au format DTCG (Design Tokens Community Group du W3C) : couleurs, espacements, tailles, rayons, bordures, ombres, animation et typographie, en mode clair et en mode sombre. Les mêmes tokens sont déjà exportés en variables CSS et en thème Tailwind CSS v4, et un fichier AGENTS.md donne aux agents IA de code les règles à suivre pour ne jamais écrire de valeur en dur. Vous gardez une seule source, les fichiers JSON, et vous régénérez le reste.

• 168 tokens au total : 137 primitives et 31 tokens sémantiques, présents dans chacun des 2 modes (clair et sombre) avec le même chemin et le même type.
• Primitives (tokens/primitives.tokens.json) :
  • 5 rampes de couleur (neutral, blue, red, green, amber), soit 57 couleurs ;
  • espacements et tailles de contrôle, d’icône et de conteneur, sur une échelle de 4 px ;
  • rayons, épaisseurs de trait, bordures et ombres ;
  • durées et courbe d’animation ;
  • familles de police, graisses et 13 styles typographiques, du titre d’accroche au code.
• Tokens sémantiques (tokens/light.tokens.json et tokens/dark.tokens.json) : fond, surfaces, texte, bordures, accent, états danger, success, warning et info, anneau de focus, tuile inverse, ombre et voile. Ce sont des alias vers les primitives : ils changent de valeur avec le mode, vos composants ne changent pas.
• 35 paires texte et fond vérifiées en contraste dans chaque mode, listées dans AGENTS.md avec leur ratio en clair et en sombre.
• Règles pour agents IA (AGENTS.md) : n’utiliser que des tokens, préférer le sémantique au primitif, rester sur l’échelle de 4 px, appliquer les styles typographiques, ne poser du texte que sur les paires autorisées, laisser le mode sombre aux tokens, et la marche à suivre pour ajouter un token.
• Documentation (docs/index.html) : une page de référence qui affiche chaque token en clair et en sombre, avec des exemples de boutons, de champs, de cartes et d’alertes construits uniquement avec les tokens.

Fichiers du starter :

AGENTS.md
tokens/primitives.tokens.json
tokens/light.tokens.json
tokens/dark.tokens.json
tokens/theme.resolver.json
css/tokens.css
tailwind/theme.css
style-dictionary/light.json
style-dictionary/dark.json
docs/index.html

Fabrication et IA

Les fichiers de tokens, les exports et la documentation ont été produits avec un assistant d’IA, puis relus et contrôlés : validation du schéma DTCG, cohérence des alias et des deux modes, échelle de 4 px, contraste des 35 paires de couleurs et build reproductible. Le starter ne contient aucune image générée par IA.

• DTCG 2025.10 JSON : les fichiers tokens/*.tokens.json sont la source. Chaque token porte son $type, sa $value et une $description qui dit où l’utiliser ; les tokens sémantiques renvoient aux primitives par un alias entre accolades. Ils se lisent avec les outils qui prennent en charge le format DTCG.
• DTCG Resolver 2025.10 : tokens/theme.resolver.json charge les primitives, puis applique le mode choisi (clair par défaut, ou sombre). Extrait du fichier :

"modifiers": {
  "theme": {
    "description": "Colour theme.",
    "contexts": {
      "light": [{ "$ref": "light.tokens.json" }],
      "dark": [{ "$ref": "dark.tokens.json" }]
    },
    "default": "light"
  }
}

• Variables CSS (css/tokens.css) : le mode clair est dans :root. Le mode sombre s’applique quand le système le demande, sauf si la page pose data-theme="light" sur la balise html ; data-theme="dark" force le sombre. Dans vos composants, il suffit d’écrire color: var(--color-text) ou background: var(--color-surface).
• Thème Tailwind CSS v4 (tailwind/theme.css) : à importer après tailwindcss. Il remplace la palette, les espacements, les rayons, les ombres et l’échelle typographique par défaut, si bien que seules les classes issues des tokens existent (bg-surface, text-text-muted, rounded-md…). La variante dark: suit data-theme="dark".
• Style Dictionary 5 : deux configurations, style-dictionary/light.json et style-dictionary/dark.json, qui lisent les fichiers DTCG et écrivent leurs variables CSS dans build/.
• Documentation HTML : une page autonome, lisible sans défilement horizontal de 375 à 1 440 px de large, en clair comme en sombre.
• AGENTS.md : un fichier Markdown que les agents IA de code lisent avant d’écrire une interface.

Les polices Geist et Geist Mono (licence SIL OFL 1.1) sont référencées par les tokens, pas incluses dans les fichiers : la documentation les charge depuis un service de polices en ligne. Le starter ne contient pas de fichier de variables pour un outil de design dans cette version.

Le starter est livré sous licence commerciale : vous pouvez l’utiliser dans vos projets personnels et professionnels, y compris pour vos clients et dans les produits que vous vendez, mais pas revendre ni redistribuer les fichiers, même gratuitement.

• Design tokens : ce que change vraiment le nouveau standard W3C DTCG
• Écrire les règles de design que les agents IA suivent

1.0.0 (10 novembre 2026) : première version.