DESIGN.md — un format de fichier unique de système de design pour les outils de code IA (synthèse en coréen)

Le format DESIGN.md proposé par Google Labs dans le projet Stitch m’a paru intéressant. J’ai donc passé plusieurs jours à décortiquer la spécification, puis je l’ai réorganisée en coréen sous la forme d’un cursus de 28 chapitres, car il m’aurait semblé dommage de la garder pour moi seul. Je l’ai conçue pour que celles et ceux qui étudient le même sujet n’aient pas à fouiller la spécification anglaise dès le départ, et pour que les personnes qui, comme moi, se demandent « comment faire lire un système de design à une IA » puissent tout parcourir d’un seul coup.

DESIGN.md est un format qui vise à représenter un système de design dans un unique fichier Markdown. Des valeurs comme les couleurs, la typographie, le spacing, le radius ou les component token sont placées dans le frontmatter YAML sous une forme lisible par machine, puis le Markdown en dessous décrit des critères de décision design comme « pourquoi utiliser cette couleur », « dans quelles situations utiliser ce style de bouton » ou « quels patterns faut-il éviter ». Autrement dit, il ne s’agit pas seulement d’un guide de style, mais de quelque chose de plus proche du « fichier source du système de design » qu’un agent de code IA comme Claude Code, Cursor ou Codex consultera à chaque fois.

Contexte — les évolutions que cette synthèse m’a fait revisiter

• Ancienne question : « comment bien organiser un système de design dans Figma ? »
• Question actuelle : « comment faire en sorte que les outils de code IA lisent notre système de design ? », « de quoi a-t-on besoin pour que l’IA respecte les règles de couleur, d’espacement et de composants de notre marque lorsqu’elle crée une nouvelle page ? »
• Avec des dynamiques comme Claude Design, Claude Code ou Figma MCP, le système de design ne reste plus seulement dans Figma : il entre dans la codebase, il est relu en PR, et il devient le « contexte persistant » des agents IA

Les points clés du format DESIGN.md (ce qui m’a marqué à la lecture de la spécification)

• Structure double YAML (pour la machine) + Markdown (pour l’humain et l’IA) — les tokens sont analysés par la machine, tandis que le corps du texte est la couche où l’on conserve les raisons des choix
• Les tokens sont la vérité, le texte explique pourquoi — le fait d’avoir défini à l’avance la priorité à suivre quand les deux divergent est élégant
• L’ordre des 8 sections est fixe — des sections comme colors, typography ou components jouent elles-mêmes le rôle de modèle mental du système de design
• lint / diff / export / spec CLI — vérifie automatiquement des éléments comme les références cassées, le contraste insuffisant, les tokens orphelins ou les violations de l’ordre des sections
• La politique d’interopérabilité avec DTCG, Tailwind et les variables Figma est explicitée séparément

Structure du cursus (28 chapitres, 7 modules)

• M1 philosophie du format · 3 chapitres — le problème que ce format cherche à résoudre, la structure double, la priorité entre tokens et texte
• M2 schéma des tokens · 5 chapitres — schéma complet / couleurs / longueurs et unités / polices / références de tokens
• M3 structure des sections · 6 chapitres — ordre des 8 sections et principes de conception de chaque section
• M4 lecture d’exemples concrets · 3 chapitres — cas Atmospheric Glass, Paws & Paths, Totality Festival
• M5 CLI · 4 chapitres — lint, diff, export, spec
• M6 règles de lint · 4 chapitres — 8 éléments dont broken-ref, contrast, orphaned, section-order
• M7 extensibilité · 2 chapitres — politique de traitement des contenus inconnus, relation avec DTCG et Tailwind
• Synthèse finale · 1 chapitre — résumé des 27 chapitres + 10 principes à reprendre en pratique

Ce que cette synthèse m’a inspiré

• Plus l’IA produira d’interfaces, plus le système de design deviendra important. La question semble se déplacer de « est-ce que l’IA sait bien designer ? » vers « à quel point l’équipe a-t-elle laissé des règles claires que l’IA doit suivre ? »
• DESIGN.md est une tentative pragmatique de placer ces règles non pas dans Notion ou un PDF, mais dans la codebase. Cela signifie aussi que les livrables des designers deviennent des objets relus au niveau des PR
• Je partage cela en pensant que cela peut être utile à celles et ceux qui construisent un système de design, ou qui créent des interfaces avec des outils de code IA en se disant « pourquoi le résultat est-il différent à chaque fois ? ». Si j’ai mal compris ou mal synthétisé certains points, dites-le-moi en commentaire et je corrigerai.

[m00nlygreat]

J’ai une question : si on considère que DESIGN.md est un ensemble d’instructions pour produire le design, j’ai l’impression qu’au final il sert aux premières pages… ou à une seule page, pour générer un mood board. Ensuite, n’y a-t-il pas un décalage qui apparaît entre le code et le fichier d’instructions .md, ce qui oblige à maintenir une synchronisation bidirectionnelle en permanence ?

Au final, pour la suite du design, il faudrait considérer le code comme source of truth et réutiliser de façon cohérente les variables, les noms, etc. Si on ne met pas continuellement à jour DESIGN.md pour le gérer comme SSoT, est-ce qu’on ne finit pas par hardcoder les tokens en permanence ? Je me demande s’il n’y a pas ce genre de problème dans l’usage réel.

[neostom432]

DESIGN.md => orienter le code est facile à automatiser, mais à l’inverse, faire remonter dans DESIGN.md les nouveaux patterns apparus dans le code ne s’automatise pas, donc il faut que quelqu’un s’en occupe manuellement. Avec le temps, de petits éléments codés en dur s’accumulent dans le code sans être reportés dans la documentation.

Cela dit, la philosophie même de ce format est plutôt de « continuer à faire évoluer le design system au sein de la codebase », donc j’y vois moins un défaut qu’un mode de fonctionnement assumé. Dans la mesure où des guides auparavant figés dans Notion ou en PDF deviennent des éléments revus au niveau des PR, cela implique aussi qu’une responsabilité de maintenance régulière par des humains s’y ajoute. Nous l’avons adopté sur notre projet, et la cohérence des écrans s’est nettement améliorée par rapport à avant ; comme son utilité se ressent concrètement, la revue manuelle ne m’a pas semblé contraignante. Au final, j’en suis arrivé à la conclusion que tout dépend de la clarté avec laquelle l’équipe laisse les critères que l’IA doit suivre, et que la charge de garder ces critères vivants reste, elle, du côté des humains.