La documentation d’un design system ne meurt pas faute de moyens. Elle meurt parce qu’on la range ailleurs que là où vit le produit : dans un fichier Figma, dans Confluence, dans un Google Doc que plus personne n’ouvre. Six mois plus tard, il existe trois versions de la vérité, et aucune n’est juste.
Le docs-as-code, documenter dans des fichiers Markdown versionnés avec le code dans Git, n’est pas un caprice d’ingénieur. C’est souvent ce qui décide si un design system est adopté ou abandonné. Co-localiser la spécification et le composant, c’est empêcher la doc de dériver pendant que le produit avance.
Mais ce n’est pas une solution magique, et le promettre comme telle serait malhonnête. Demander à des designers de cloner un dépôt et de résoudre des conflits de fusion, c’est le meilleur moyen qu’ils cessent d’écrire. Cet article tranche : où le .md change tout, où il exclut et comment documenter comme on code sans transformer la doc en chasse gardée des développeurs.
La dette documentaire : pourquoi la doc d’un design system meurt
La doc obsolète en moins de six mois
La défaillance vient rarement d’un manque d’investissement initial. Elle vient d’un défaut d’intégration dans les cycles de production. Une doc traitée comme une tâche ponctuelle, livrée une fois puis oubliée, sombre dans l’obsolescence en quelques mois. Elle vieillit à la vitesse du code qu’elle est censée décrire, sauf que personne ne la met à jour au même rythme.
Brad Frost, l’auteur d’Atomic Design, le formule sans détour : une bibliothèque de motifs devient obsolète dès l’instant où elle cesse de refléter l’état réel des produits qu’elle sert. Passé ce point, sa maintenance dégénère en correctifs ponctuels et en ajustements ad hoc, jusqu’à l’abandon. La cause profonde est un choix de posture : traiter le design system comme un projet qui se termine, alors que c’est un produit qui vit aussi longtemps que ce qu’il alimente. Un design system pensé pour suivre les cycles de vie du produit ne connaît pas ce décrochage.
Trois sources de vérité qui divergent
La désynchronisation entre Figma, le code et le wiki crée des sources de vérité incompatibles. Chacun consulte la sienne, aucune n’est à jour. Il suffit d’un correctif urgent poussé dans le code et non répercuté sur la maquette Figma ni sur le wiki pour amorcer la divergence.
Quand la doc s’écarte de la production, la confiance s’effondre. Les développeurs se fient au code existant ou à l’historique Slack, les designers contournent le système, et le design system devient un goulot d’étranglement au lieu d’un accélérateur. La documentation ne perd pas seulement de la valeur : elle en détruit, en envoyant les équipes vers des informations fausses.
Les symptômes de dérive
Trois signes ne trompent pas, et chacun renvoie à une cause structurelle précise.
Symptôme | Cause structurelle |
|---|---|
Divergence Figma / code | Aucun lien bidirectionnel automatisé : des composants visuels obsolètes, ou impossibles à implémenter tels quels. |
Obsolescence documentaire | La mise à jour de la doc est déconnectée du jalon de livraison logiciel : elle attend un temps mort qui ne vient jamais. |
Silos d’écriture | Wikis et PDF isolés du flux technique : critères d’accessibilité et règles éditoriales ignorés au moment du développement. |
Docs-as-code : le principe appliqué à un design system
Markdown ou MDX dans Git, le même cycle que le code
La définition opérationnelle tient en une phrase : aligner le cycle de vie de la doc sur celui du code. Un format texte brut (Markdown, ou sa variante enrichie MDX qui autorise des composants interactifs), stocké dans le dépôt Git aux côtés des composants.
Le circuit est celui du développement produit, à l’identique : une branche, des modifications locales dans l’éditeur de code, une Pull Request, une revue par les pairs, une validation par l’intégration continue. La doc n’emprunte plus un processus parallèle et négligé, elle passe par le même tuyau que la fonctionnalité qu’elle documente.
Cette approche n’est pas née dans le design. Elle vient de la documentation logicielle : le terme docs-as-code a été popularisé autour de 2015 par Eric Holscher et la communauté Write the Docs, pour de la doc d’API et d’architecture. Situer cette filiation évite l’effet de mode, et rappelle une chose utile : appliquée au design, la méthode hérite d’outils pensés pour des ingénieurs, d’où une partie des frictions que nous verrons plus loin.
La co-localisation, le geste clé
Ranger Button.mdx dans le même dossier que Button.tsx et Button.css : la spécification et le composant vivent ensemble. C’est une contrainte géographique. Modifier le composant sans voir sa doc juste à côté devient contre-nature, et la charge cognitive baisse, puisqu’il n’y a plus à changer d’outil ni de contexte pour tenir les deux à jour.
Le « merge block » comme garde-fou de gouvernance
La chaîne de livraison peut aller plus loin et bloquer la fusion d’une Pull Request de code si le fichier de doc associé n’a pas été modifié conjointement. Un script inspecte le diff, repère qu’un Button.tsx a changé sans que Button.mdx bouge, et fait échouer la vérification. La conformité documentaire cesse d’être un vœu pieux pour devenir une règle exécutable. C’est le point de bascule : la mise à jour n’est plus une bonne intention, c’est une condition de livraison.
Ce que le .md permet que Figma et Confluence ne permettent pas
Traçabilité et revue par le diff
L’historique versionné restitue le contexte de chaque évolution : qui a modifié quoi, quand et dans quelle Pull Request. On peut remonter le temps et relire la doc exacte de la version 2.1.0 d’un composant. Aucun wiki ne donne ça nativement.
La revue se fait par le diff, ligne à ligne. Les relecteurs voient précisément ce qui change avant d’autoriser la fusion. La doc se relit comme du code, avec la même rigueur, les mêmes commentaires en revue, le même droit de veto.
Automatisation par l’intégration continue
Les pipelines vérifient sans intervention humaine ce qu’un relecteur laisserait passer. Les outils sont éprouvés : markdownlint pour la syntaxe, Vale pour faire respecter un guide de style éditorial, contextlint pour l’intégrité entre fichiers (liens internes morts, identifiants en double), Playwright ou Cypress pour la non-régression visuelle. Les liens cassés et les incohérences de style sont attrapés à la Pull Request, pas signalés trois mois plus tard par un utilisateur agacé.
Le point d’équilibre : des gains qui se paient
Ces bénéfices sont réels, mais ils sont d’abord ceux de l’ingénierie, et ils se paient en infrastructure et en compétences. C’est la tension que la suite de cet article assume plutôt que de la cacher : tout ce qui rend la doc solide côté code peut la rendre inaccessible côté design.
Gouvernance : qui écrit, qui valide, qui tranche
Centralisé, fédéré, hybride
Trois modèles, trois compromis, aucun gratuit.
Le modèle centralisé confie la doc à une équipe dédiée. Contrôle qualité fort, cohérence absolue, mais goulot d’étranglement et déconnexion du terrain.
Le modèle fédéré ouvre la contribution aux équipes produit. Forte adéquation au terrain, sentiment de propriété, mais qualité variable d’une main à l’autre.
Le modèle hybride combine une cellule centrale garante des standards et des contributeurs intégrés aux produits. C’est l’équilibre le plus défendable en pratique, et celui vers lequel convergent la plupart des systèmes matures.
Le mythe du fédéré heureux
Nathan Curtis, d’EightShapes, démonte le fédéré idéalisé. Sans facilitation formelle, sans chartes de décision précises et sans rôles clairement définis, la fédération n’est pas une démocratie de la contribution : c’est une illusion qui produit mécaniquement de l’incohérence. Ouvrir les vannes sans structurer la gouvernance ne distribue pas la qualité, ça distribue le désordre.
Petite équipe et rôle de garant
Une donnée de cadrage remet les choses à leur place. Selon le Nielsen Norman Group, une équipe de design system reste petite : 2 à 5 personnes dans la majorité des cas. Même dans les organisations de plus de 5 000 salariés, elle tourne autour de 9 à 11 personnes et dépasse rarement 20 à 25. On ne documente donc pas avec une armée, mais avec une poignée de gens qui doivent être secondés par le product design et par les équipes produit elles-mêmes.
D’où la nécessité d’officialiser un garant, l’« enforcer » du NNg, doté d’un vrai pouvoir d’arbitrage et soutenu par la direction. Sans autorité pour trancher les écarts esthétiques et refuser une contribution hors standard, la règle devient une suggestion que les équipes ignorent, et le système dérive vers l’assemblage hétéroclite. Ce garant fait partie des principes d’un design system qui tient dans la durée.
Le docs-as-code matérialise la règle, il ne la décide pas
Qui peut fusionner, quelle Pull Request exige quelle validation, comment versionner : l’outil rend la gouvernance visible et exécutable. Il ne la remplace pas. La décision de qui tranche, et selon quels critères, reste une décision humaine. Le .md est un excellent exécuteur, un piètre législateur.
Concevoir une doc utilisable, pas un manuel que personne ne lit
La doc comme produit : le « code pair » d’abord
Une documentation se conçoit comme un produit, avec des bacs à sable interactifs et des composants copiables, pas comme un long manuel théorique qu’on lit une fois. Nathan Curtis a identifié le module qui pèse le plus lourd dans l’expérience des concepteurs et développeurs : le « code pair », c’est-à-dire le rendu visuel interactif du composant, accompagné de ses onglets de code, d’un bouton copier et de la démonstration de ses états (survol, actif, désactivé). C’est ce bloc que les gens utilisent. Le reste est du contexte.
Divulgation progressive et écriture à l’impératif
Montrer d’abord le cas d’usage nominal, dévoiler la complexité (états, configurations avancées) seulement à la demande : c’est de l’architecture d’information appliquée à la doc, la même logique de charge cognitive qui régit une bonne interface. On ne noie pas le lecteur, on lui donne l’essentiel puis on ouvre les tiroirs.
L’écriture suit la même exigence. On écrit pour l’action : phrases à l’impératif, verbes forts, une règle en moins de deux phrases, des exemples Do / Don’t explicites plutôt que des paragraphes de nuances. Si une règle déborde de deux phrases, c’est qu’elle en cache deux.
L’éditorial et l’accessibilité se documentent dans la fiche
Les règles éditoriales (voix, ton, terminologie) et l’accessibilité sémantique appartiennent à la fiche du composant, pas à un wiki annexe. Adobe Spectrum et Intuit intègrent ainsi leurs guides d’UX writing directement au composant. Les spécifications techniques d’accessibilité les plus pointues (attributs ARIA, comportement clavier, contrastes) relèvent le plus souvent des guidelines de développement front-end. Mais si la fiche ne porte pas au moins les règles de contenu et l’accessibilité de sens, cette expertise retombe sur chaque développeur, qui la réinvente ou l’oublie.
L’écosystème d’outils, sans publi-reportage
Générateurs statiques : Docusaurus et Nextra
Docusaurus est un générateur React, avec support MDX, recherche intégrée et gestion de versions native. Il est pertinent quand la doc doit suivre les versions logicielles. Son coût est réel et souvent sous-estimé : quelques heures à quelques dizaines d’heures d’installation, puis une maintenance mensuelle des pipelines de déploiement qui se chiffre en temps d’ingénierie, pas en clics.
Nextra, bâti sur Next.js, rend l’écriture MDX simple et le déploiement rapide. Sa limite est nette : pas de gestion de versions intégrée, ce qui impose de déployer manuellement des branches séparées et complexifie l’arborescence dès qu’on veut historiser.
Storybook et Zeroheight : forces et silos
Storybook est le standard de fait pour isoler, tester et documenter les composants et leurs props. Mais il est conçu pour les développeurs, pauvre dès qu’il s’agit de porter une charte de marque, une anatomie de composant ou de longues consignes rédactionnelles.
Zeroheight prend le problème par l’autre bout : édition WYSIWYG et synchronisation Figma facilitent la contribution des designers. Le reproche classique, le silo propriétaire hors Git, mérite d’être nuancé aujourd’hui : une API et une interface en ligne de commande permettent de brancher Zeroheight dans des GitHub Actions, pour injecter automatiquement une URL Storybook ou des métriques d’adoption. Le silo existe encore, il n’est plus hermétique.
Style Dictionary pour les tokens multiplateformes
Style Dictionary, créé par Danny Banks chez Amazon en 2017 et distribué en open source, compile des tokens JSON neutres vers CSS, iOS et Android. Il garantit la cohérence multiplateforme depuis une source unique, mais réclame une expertise de configuration et n’offre aucune interface : c’est un outil de chaîne technique, pas un éditeur pour designers.
Choisir selon la maturité, pas selon la mode
Il n’existe pas d’outil universel. Le bon choix dépend de la maturité de l’équipe et de la nature de ce qu’elle documente. L’erreur la plus fréquente est d’adopter l’outil avant d’avoir tranché la gouvernance, comme on choisirait Figma pour son design system sans avoir décidé qui a le droit d’y publier. L’outil suit la décision d’organisation, il ne la précède pas.
Design tokens et frontière IA : du JSON W3C au format DESIGN.md
Le token JSON déterministe et sa limite sémantique
Les design tokens, conceptualisés chez Salesforce en 2014 par Jina Anne sur le Lightning Design System, sont aujourd’hui cadrés par le Design Tokens Community Group du W3C. Sa première version stable, baptisée 2025.10, a été publiée le 28 octobre 2025. Une précision souvent gommée : ce document a le statut de Final Community Group Report, hors du Standards Track officiel du W3C. C’est une spécification communautaire stable et sérieuse, pas une norme au sens de HTML ou CSS. Le JSON garantit une distribution déterministe : la même valeur, partout, sans ambiguïté.
Sa limite est sémantique. Il dit qu’une couleur vaut telle valeur hexadécimale (color-primary égale #1A1C1E), mais pas pourquoi cette couleur existe, ni quand il ne faut pas l’utiliser, ni quelles exceptions s’appliquent pour l’accessibilité ou le ton de marque. La valeur est là, le sens manque.
DESIGN.md : du YAML pour les valeurs, du Markdown pour le sens
C’est le vide que vise à combler le format DESIGN.md, open-sourcé par Google Labs, via son outil Stitch, le 21 avril 2026 sous licence Apache 2.0. Le principe : un en-tête YAML déterministe qui porte les valeurs de tokens, et un corps Markdown qui porte le reste, c’est-à-dire les règles d’usage, le ton de marque et les contraintes ergonomiques. Les chiffres d’un côté, l’intention de l’autre, dans un même fichier à la racine du dépôt.
Une doc lisible par les agents IA, le pont vers le GEO
Ce document est pensé pour être lu nativement par les agents qui génèrent des interfaces (Claude Code, Cursor, v0). Le contexte sémantique persistant leur donne un cadre : il limite la dérive esthétique et l’uniformisation par défaut des modèles, cette tendance à recracher la même interface générique faute de consignes de marque.
Le parti pris, ici, est de ne pas survendre. DESIGN.md est en version alpha, la spécification est explicitement un brouillon susceptible de changer, et ce n’est pas un standard ratifié : le mettre sur le même plan de maturité que la spécification W3C serait une faute. Il ne remplace pas non plus les design tokens : c’est une enveloppe documentaire posée par-dessus, et pour un pipeline qui produit du CSS, le JSON reste la référence. Mais la direction est claire, portée autant par Google que par une communauté qui recense déjà les usages du format. La documentation de design devient alors un actif d’ingénierie : lisible par les humains, exploitable par les machines.
Les limites : pour qui le docs-as-code est un piège
La barrière d’entrée pour les designers non techniques
Terminaux, clonage de dépôt, branches, conflits de fusion : quand contribuer exige cette panoplie, une partie des designers renonce. Ils délèguent l’écriture aux développeurs, et la doc devient dev-centric, amputée précisément de ce que les designers apportaient : les règles ergonomiques, la justesse éditoriale, le sens de l’usage. On a renforcé le contenant en vidant le contenu.
Les faiblesses de Git pour du contenu
Git a été conçu pour du code, et cela se sent dès qu’on lui confie du contenu. Pas de verrouillage de fichier, ce qui pose problème pour des traductions ou des éditions concurrentes. Un écart de rendu, car les Pull Requests montrent du Markdown brut et non le résultat mis en forme, d’où la nécessité de maintenir des serveurs de prévisualisation facturés à la minute. Une faiblesse sémantique native, enfin : pas de variables conditionnelles ni de validation possibles sans écrire des scripts.
Quand c’est surdimensionné, et la transition douce
Pour une startup en amorçage ou une équipe à peu de composants, l’architecture docs-as-code est souvent surdimensionnée. Le temps passé à réparer des pipelines pèse davantage sur la vélocité produit qu’il ne fait gagner en rigueur. Là, se demander s’il faut vraiment un design system aussi outillé est une question saine.
La réponse pragmatique tient en un mot : progressivité. On ne bascule pas tout d’un coup. Des blocs Markdown suffisent à amorcer une transition douce depuis Google Docs, sans big bang. Un CMS visuel branché sur Git, de type TinaCMS, abaisse la barrière pour les designers en leur offrant une interface d’édition par-dessus le dépôt. L’objectif est l’adoption, pas la pureté technique. Un dépôt parfait que personne n’alimente vaut moins qu’un Google Doc que tout le monde tient à jour.
Quatre design systems qui documentent en docs-as-code
Shopify Polaris
Polaris fonctionne en monorepo unifié : tokens, composants et site de documentation en MDX cohabitent dans le même dépôt, avec des contributions par Pull Request et un versioning automatisé via Changesets. Le 1er octobre 2025, Shopify a déprécié sa bibliothèque React historique au profit des Web Components. La motivation est mesurable : React et ReactDOM ajoutaient de l’ordre de 40 à 50 Ko compressés de surcharge, ramenés à moins de 5 Ko en composants natifs.
IBM Carbon
Carbon a bâti une plateforme de documentation où les fichiers MDX pèsent environ 22,4 % de l’architecture, imbriqués avec du TypeScript et du JavaScript. Les composants React sont importés dynamiquement dans le texte via un parseur maison, @carbon-platform/rmdx, qui convertit le MDX en arbre syntaxique et exclut volontairement certaines expressions pour bloquer les injections de code. Résultat : une parité stricte entre la spécification lue et le code exécuté.
Adobe Spectrum
Spectrum distribue ses tokens via le paquet @spectrum-css/tokens, généré par Style Dictionary, et documente ses workflows en Markdown dans un dépôt public. La cohérence visuelle est verrouillée en intégration continue par comparaison de pixels avec BackstopJS, et toute contribution impose la mise à jour du fichier .mdx co-localisé. Documenter fait partie du contrat, pas d’un après-coup.
Equinor EDS
Equinor hybride Storybook, pour le test technique, et Docusaurus, pour la documentation publique. Chaque modification de composant est liée à une mise à jour de doc. Lors de la refonte du composant Search, engagée dans la version EDS 2.0 au deuxième trimestre 2026, le code, les consignes, les exemples Do / Don’t et les critères d’accessibilité ont été soumis ensemble, dans un corpus pensé pour être aussi bien lu par les équipes que par des modèles d’IA.
Mesurer la doc : adoption, fraîcheur, et le piège des chiffres
Se méfier du ROI marketing
Les chiffres vendeurs circulent, et tous ne se valent pas. La donnée la plus solide du dossier est aussi la moins tapageuse : le groupe REA a mesuré environ 300 000 heures cumulées économisées sur quatre ans grâce à son design system maison, chiffre obtenu non par un sondage déclaratif mais par un script d’analyse hebdomadaire du code. C’est un audit interne neutre, pas un argumentaire d’éditeur.
À l’inverse, les chiffres de Knapsack (plus de 30 % de temps de QA en moins, plus 15 % de time-to-market) sortent de ses propres calculateurs de rentabilité : à citer comme des revendications d’éditeur, pas comme des garanties. Même prudence pour l’ordre de grandeur souvent avancé de 30 heures économisées par composant réutilisé, qui est un chiffre générique du secteur, pas une mesure attribuable. Le ROI d’un design system existe, mais il se démontre dans la durée et sur ses propres données, pas en recopiant les plaquettes.
L’adoption brute n’est pas la bonne mesure
Le taux d’adoption brut induit en erreur. Imposer l’usage d’un composant peut étouffer l’expérimentation produit et masquer un système inadapté derrière un chiffre flatteur. Knapsack va jusqu’à qualifier l’adoption de « métrique de vanité ». Le rapport 2026 de Zeroheight pointe d’ailleurs dans le même sens en montrant que la satisfaction vis-à-vis du soutien interne recule, de 42 % à 32 % : prouver la valeur d’un design system reste un exercice difficile, que le chiffre d’adoption ne résout pas.
Couverture, fraîcheur, usage réel
Trois indicateurs valent mieux qu’un compteur d’adoption. La couverture, soit la part des composants documentés. La fraîcheur, soit le délai depuis la dernière mise à jour, qu’un dépôt Git rend mesurable au jour le jour. L’usage réel, enfin, lu dans les pages consultées et les recherches infructueuses, qui disent ce que les gens cherchent sans le trouver.
On documente pour décider et pour faire adopter, pas pour cocher une case. Et de ces trois signaux, la fraîcheur est sans doute le meilleur indice de santé d’une doc, précisément parce que Git la rend visible sans effort déclaratif.
Documenter comme on code, sans exclure les designers
Le docs-as-code résout un vrai problème, la dérive de la documentation, par un vrai levier : co-localiser la spécification et le code, et rendre la mise à jour obligatoire via la chaîne de livraison. Sur ce terrain, il n’a pas d’équivalent.
Mais la méthode échoue si elle exclut les designers. La recommandation d’Usabilis est nette : viser l’hybride, une cellule centrale plus des contributeurs, abaisser la barrière d’entrée avec un CMS visuel sur Git et des blocs Markdown, et officialiser un garant soutenu par la direction. C’est un travail de stratégie et d’accompagnement du design system autant que de tuyauterie technique, qui peut passer par une formation dédiée des équipes.
Le bon départ est petit et concret : co-localiser la doc d’un composant pilote, instaurer la règle « pas de fusion de code sans doc » sur ce seul périmètre, mesurer la fraîcheur, puis étendre. On prouve la méthode sur un composant avant de l’imposer à cent.
Reste la perspective qui rebat les cartes. Avec des formats comme DESIGN.md, encore jeunes mais clairement orientés, la documentation cesse d’être un sous-produit pour devenir l’interface entre l’intention design, le code et les agents IA. Le .md pour le design n’est pas une lubie de développeur. C’est en train de devenir la prochaine source de vérité.
