Thème Astro de documentation de design system : pages de tokens générées depuis le format DTCG, composants et guide de contribution, bilingue

Ce thème s’adresse aux équipes et aux designers qui ont déjà leurs design tokens et veulent publier la documentation de leur design system sur leur propre site, en français et en anglais, plutôt que dans un service de documentation hébergé. Il est construit avec Astro et lit vos fichiers au format DTCG 2025.10 au moment de la construction : les pages couleurs, typographie, espacements, rayons et bordures, ombres et mouvement se génèrent à partir de vos tokens, avec leurs valeurs en clair et en sombre, leurs alias, leurs variables CSS et les contrastes de vos paires de couleurs. Vous écrivez en Markdown les pages de composants, les guides (dont le guide de contribution) et les notes de version.

Le site construit n’envoie aucun JavaScript au navigateur. Le thème ne reprend pas automatiquement le contenu d’une documentation existante : un guide explique comment le recopier en gardant vos anciennes adresses.

• 7 gabarits de page, en français et en anglais : accueil, page de fondation générée depuis les tokens, index des composants, page de composant, guide, notes de version et page introuvable bilingue.
• 6 pages de fondations générées depuis vos fichiers DTCG : couleurs, typographie, espacements, rayons et bordures, ombres, mouvement. Chaque token y apparaît avec sa valeur dans chaque contexte, son alias, sa variable CSS et un aperçu. L’accueil de la démo présente 6 cartes de fondations.
• Une page de composant complète : exemples rendus avec vos tokens et leur code HTML, anatomie, à faire et à éviter, accessibilité, tokens utilisés avec un lien vers leur ligne, questions fréquentes. Un chemin de token inconnu dans une page de composant fait échouer la construction.
• Les contrastes de vos paires de couleurs, calculés à la construction selon les critères WCAG et affichés sur la page des couleurs, pour chaque contexte.
• /tokens.css : les variables CSS de votre design system, claires et sombres, prêtes à brancher dans vos propres projets.
• 2 langues d’origine : le français à la racine, l’anglais sous /en, avec des paires hreflang réciproques entre traductions. Une page sans traduction n’en émet pas. Le code accepte d’autres langues.
• Un seul fichier de configuration, theme.config.ts : adresse du site, langue par défaut, nom du site, motifs de permaliens par type de page et par langue, éditeur pour les données structurées, fichiers de tokens, préfixe des variables CSS, fondations, paires de contraste, police et feuille de style des exemples.
• La mécanique pour les moteurs de recherche, produite par une seule table de routes : URL canoniques sans barre oblique finale, paires hreflang, plan de site qui écarte les pages noindex, robots.txt et données structurées JSON-LD (WebSite, WebPage, CollectionPage, TechArticle, FAQPage, BreadcrumbList).
• Des redirections dans un seul fichier, redirects.json, écrites dans dist/_redirects, avec une page de repli pour chaque adresse redirigée.
• Des contrôles en ligne de commande : npm run check:tokens lit vos fichiers DTCG sans construire le site (alias, cycles, types, contrastes, tokens cités par les composants) ; npm run check:seo vérifie canoniques, paires hreflang, plan de site, JSON-LD, liens internes et redirections ; npm run check:coverage liste les anciennes URL que le nouveau site ne servirait ni ne redirigerait.
• Des guides en français et en anglais : branchement de vos tokens (docs/tokens.fr.md, docs/tokens.en.md) et départ d’un service de documentation hébergé (docs/migration.fr.md, docs/migration.en.md).
• Un design system de démonstration inventé, Lisière, dans les deux langues : 168 tokens (137 primitives et 31 rôles sémantiques), 181 variables CSS, 17 paires de contraste, 8 composants, 6 fondations et 4 guides, dont « Contribuer ». La démo construite compte 44 pages HTML, dont 40 pages indexables en 20 paires de traductions, et redirects.json y contient 3 redirections d’exemple. Remplacez tout le contenu par le vôtre.
• La version 1.0.0, avec son journal des modifications, et 148 fichiers au total.

Fichiers du thème :

• À la racine : README.md, README.en.md, CHANGELOG.md, package.json, package-lock.json, .nvmrc, theme.config.ts, astro.config.mjs, tsconfig.json et redirects.json.
• tokens/ : les fichiers DTCG de la démo, à remplacer par les vôtres.
• src/content/ : composants, fondations, guides, pages et descriptions des tokens, un dossier par langue.
• src/examples/ : les exemples HTML des composants.
• src/components/, src/layouts/, src/lib/ (dont le lecteur DTCG), src/pages/ et src/styles/ : le code du thème.
• public/ : la feuille de style des exemples.
• integrations/ : écriture de _redirects, de _headers et chargement de la police des exemples.
• scripts/ : les contrôles en ligne de commande.
• docs/ : guides de branchement des tokens et de migration en français et en anglais, export d’exemple.

Le texte de la licence, LICENCE.txt, est à la racine de l’archive téléchargée.

Fabrication et IA

Le code du thème (gabarits Astro, lecteur DTCG, CSS, scripts de contrôle), le design system de démonstration et les guides ont été produits avec un assistant d’IA, puis relus et contrôlés avant la mise en vente : construction sur deux versions de Node, vérification des types, contrôles SEO, accessibilité en clair et en sombre, contrastes recalculés indépendamment et absence de défilement horizontal. Aucune image n’a été générée par IA.

• Prérequis : Node 22.23.4 ou plus récent, la version minimale d’Astro 7. Le fichier .nvmrc indique la version de développement du thème (24).
• Astro 7, sortie entièrement statique, sans aucun JavaScript côté client (0 Ko) : les seules balises <script> portent les données JSON-LD.
• DTCG 2025.10 pour les tokens : fichier resolver ou fichier de tokens seul, ensembles, modificateurs et alias, lus par un lecteur sans dépendance. Un alias orphelin, un cycle ou un type inconnu fait échouer la construction et check:tokens en nommant le fichier et le token.
• Markdown pour le contenu, avec un frontmatter strict : un champ inconnu fait échouer la construction en nommant le fichier.
• TypeScript pour la configuration et le code du thème.
• CSS sans framework : l’habillage du thème repose sur son propre jeu de tokens (préfixe --dsd-), séparé de ceux de votre design system. Les modes clair et sombre suivent le réglage du système du visiteur.
• Polices : Bricolage Grotesque et Martian Mono pour le thème, Geist pour les exemples de la démo (à remplacer par la police de votre design system), sous licence SIL Open Font License 1.1, référencées par npm. Aucun fichier de police dans l’archive, aucune requête vers un service de polices externe.
• Hébergement : tout hébergeur statique qui sert composants/bouton.html à l’adresse /composants/bouton. S’il lit _redirects et _headers, il les applique ; sinon, la page de repli écrite pour chaque adresse redirigée n’est pas une redirection 301 : avant une migration, recopiez chaque ligne de redirects.json dans les règles de redirection de votre hébergeur. L’adaptateur Node d’Astro n’est pas pris en charge dans la version 1.0.0.

À savoir avant l’achat :

• Le thème lit des fichiers DTCG 2025.10 : il ne convertit pas d’autres formats de tokens.
• Il n’importe pas une documentation existante : le guide de migration explique l’inventaire des anciennes URL, l’export, la correspondance des champs et le contrôle de couverture, mais vous reprenez le contenu vous-même.
• Après une modification dans tokens/, relancez npm run dev : le serveur de développement ne recharge pas les fichiers de tokens.
• Non inclus : recherche, bouton de copie du code, bouton clair/sombre, plusieurs versions du design system en parallèle, synchronisation Figma, rendu de composants d’un framework (React, Vue), flux RSS (notes de version comprises), importeur automatique de contenu, $extends des groupes DTCG, redirections à joker.

Le thème est vendu avec la licence commerciale : vous pouvez l’utiliser et le modifier pour documenter votre design system et ceux de vos clients, mais pas revendre, partager ni redistribuer ses fichiers, même modifiés, ni les publier comme thème ou modèle réutilisable, dépôt public compris. Les polices gardent leur propre licence.

• Pour comprendre le format que le thème lit : ce que change le standard W3C DTCG pour les design tokens.
• Pour situer ce qu’une documentation ajoute à une bibliothèque de composants : UI kit et design system, les différences.

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