Atlassian publie DESIGN.md : les leçons tirées de tests concrets d’un contexte de design portable

• Un format Markdown portable conçu pour résoudre le problème du « slop » des UI générées par l’IA, qui tendent à devenir génériques et sans identité de marque ; l’idée consiste à regrouper les éléments clés d’un design system dans un seul fichier à inclure dans le prompt
• DESIGN.md se compose de deux parties : des design tokens lisibles par machine et la justification de design (rationale) lisible par les humains et les agents ; il ne contient pas la spécification technique complète du système, mais son intention (intent)
• Lors de son application à la génération d’un tableau de bord Figma Make dans la démo keynote de Team '26, les couleurs, espacements, formes et la typographie se sont alignés sur le système Atlassian, avec de bonnes performances en prototype généré en one-shot
• En revanche, dans une base de code de production, l’approche a consommé environ 92 % de tokens en plus par rapport à leur propre serveur MCP et skills, avec un temps de génération plus long et une variabilité d’environ 2,7x de la consommation de tokens entre exécutions, donc une efficacité en baisse
• Ses atouts propres — portabilité et concision — restent précieux pour la portabilité cross-platform, le theming client et le prototypage dans de nouveaux environnements ; il se positionne comme un complément, et non un remplacement, d’outils de design system plus riches

---

Contexte — le problème du « slop » dans les UI IA

• Quand l’IA génère des UI, les résultats ont tendance à se ressembler : boutons en dégradé, titres en majuscules, mises en page de cartes génériques, animations de survol inutiles, etc. Le produit fonctionne, mais il manque d’identité visuelle
• La communauté du design qualifie ce type de résultats de « slop » : des sorties fonctionnelles, mais sans décisions de design intentionnelles
• La cause est l’absence de contexte sur la marque, les composants et les patterns ; l’IA retombe alors sur la moyenne de ses données d’entraînement comme sortie par défaut → « Generic in, generic out »
• L’équipe du design system d’Atlassian construit un moteur de contexte pour l’ère de l’IA et fournit aux agents un riche contexte de design via le serveur ADS MCP et des skills IA détaillées
  • Ils ont constaté grâce à cela une réduction du coût en tokens IA ainsi qu’une amélioration de la précision et de la qualité des résultats générés par des milliers de product builders

Vue d’ensemble de DESIGN.md

• Un format Markdown open source conçu par Google pour son outil de design Stitch, comme instantané portable de la marque et des patterns UI d’une équipe
• Une fois le fichier inclus dans le prompt, le résultat généré commence à ressembler au produit de l’entreprise : le principe est simple

• Ce que c’est (What it is)

  • Un fichier Markdown portable qui décrit uniquement les éléments essentiels d’un design system
  • La première partie énumère des design tokens lisibles par machine
  • La seconde décrit, pour les humains et les agents, la justification de design concernant les couleurs, espacements, layouts, elevation, composants, etc.

• Ce que ce n’est pas (What it isn't)

  • Ce n’est pas la spécification technique complète du fonctionnement d’un design system en production, ni l’intégralité des détails du système
  • Il n’inclut ni les bibliothèques de code existantes, ni les linters qui maintiennent les standards de code, ni les spécifications détaillées de design dans Figma
  • La spécification définit ce format comme un moyen de capturer non pas tous les détails du système, mais son intention (intent)

Construire leur propre DESIGN.md

• Atlassian préparait déjà son design system à la consommation par l’IA via un serveur MCP, un pipeline de contenu structuré et diverses skills d’agents
• Ils ont généré leur propre DESIGN.md à partir du même pipeline de contenu structuré qui alimente MCP et les skills d’agents
• Ils ont testé le format dans des outils de vibe coding grand public et ajouté des consignes plus strictes sur des erreurs fréquentes qui n’apparaissaient pas dans leurs guides existants

Test lors de Team '26

• La démo keynote de Team '26, finalisée un mois plus tôt à Anaheim, a servi de cas de test approprié
• Dans l’une des démos de la keynote, Figma Make générait un tableau de bord personnalisé avec Teamwork Graph, avec pour objectif d’aligner le langage de design en une seule passe, sans dépendre de serveurs MCP ou d’outils internes
• Avec DESIGN.md, le résultat est passé d’un « slop » générique à une sortie immédiatement reconnaissable comme Atlassian, utilisant les bonnes attentes en matière de couleur, d’espacement, de forme et de typographie, ainsi qu’une elevation alignée sur le système pour les composants
• Les consignes et spécifications de haut niveau du fichier conviennent bien à la personnalisation de bibliothèques courantes comme Tailwind et Shadcn pour générer une UI from scratch

Les compromis en production

• Une base de code de production diffère fortement d’un environnement isolé construit from scratch : elle possède déjà des bibliothèques de tokens et de composants, des règles de lint strictes et une vérification de types
• Sur une tâche simple comme un écran de connexion utilisateur, utiliser DESIGN.md comme unique guide de design a entraîné environ 92 % de consommation de tokens en plus, des temps de génération plus longs et une variabilité d’environ 2,7x entre exécutions
  • Ils précisent toutefois que ce résultat n’est pas définitif et peut varier selon le modèle, le prompt, le design system, l’environnement et la qualité du contexte

• Limite 1 — le contexte est transmis d’un bloc, pas à la demande

  • Un serveur MCP récupère à la demande uniquement les consignes relatives à un composant donné via un tool call comme ads_plan
  • Cela évite de charger inutilement les parties lourdes, comme des centaines d’icônes ou un vaste ensemble de design tokens sémantiques
  • DESIGN.md charge l’ensemble à chaque fois, avec dès le départ un coût élevé et une réponse plus lente, ainsi qu’un risque de perte de précision quand le contexte est tronqué dans des interactions courtes

• Limite 2 — garder le fichier court entraîne une perte de contexte

  • Un design system est un objet complexe qui compresse le langage commun de milliers de vues, fichiers Figma et composants frontend
  • Les skills MCP à la demande distillent cela en environ 2,5 Mo de consignes, alors que DESIGN.md doit être chargé d’un coup et nécessite donc une réduction bien plus importante
  • Le fichier obtenu pèse 80 Ko, soit environ 19 800 tokens LLM (environ 10 700 hors frontmatter), ce qui est plutôt volumineux par rapport aux exemples de la communauté
  • Pour tenir dans cette taille, ils ont supprimé une grande partie des consignes d’usage de plus de 50 composants, fortement réduit les consignes de base et retiré certains design tokens peu utilisés
  • Avec ce contexte manquant, ils ont observé que les agents visant une qualité de production perdaient en précision ou tentaient d’aller chercher eux-mêmes du contexte, en lisant directement l’implémentation des composants pour trouver des consignes d’usage absentes de la spécification

• Limite 3 — la spécification expose l’intérieur du design system

  • DESIGN.md est un instantané portable qui réécrit le design system sous forme de prose, destiné à fournir les principes, spécifications et consignes nécessaires pour le réimplémenter from scratch
  • Dans un environnement de production établi, ces informations sont inutiles ou peuvent pousser l’agent à créer de la dette technique (tech debt), en particulier pour les composants
  • Au lieu de lire et d’interpréter tous les détails de style d’un bouton (backgroundColor, textColor, borderColor, etc.), mieux vaut importer et utiliser le composant existant
    • Exemple : import Button from '@atlaskit/button'; puis <Button appearance="primary" spacing="compact" />
  • L’usage de composants partagés est essentiel à la maintenance : une modification du bouton à un seul endroit se répercute dans toute la base de code, ce qui facilite les revues et la maintenance
  • Comme DESIGN.md exclut volontairement les consignes de code et ne fournit que des spécifications de réimplémentation, les tests ont montré une tendance plus forte à régénérer les composants plutôt qu’à réutiliser le système existant
  • Le serveur MCP et les skills offrent un meilleur niveau d’abstraction, fondé sur la base technique : ils servent de manuel d’usage du système existant, et non de guide de réimplémentation
  • Combinés à des règles de lint qui imposent les standards de code sans coût en tokens, ils créent une boucle de rétroaction positive pour les agents

Les cas où DESIGN.md est le plus utile

• Direction artistique de haut niveau (High-level artistic direction)

  • Le DESIGN.md le plus simple se concentre sur la direction visuelle et le ressenti du système ; si cela n’a pas encore été documenté, c’est déjà un livrable utile
  • En revanche, le frontmatter duplique des informations déjà présentes dans la base de code

• Prototypage rapide dans des environnements peu familiers

  • Pour du prototypage blue-sky ou des tests de nouveaux outils, il permet de produire une UI fidèle à la marque sans avoir à reconstituer toute la stack technique ni subir les contraintes des composants existants

• Interopérabilité avec les outils de design (Interoperability)

  • Certains outils IA assemblent une UI en personnalisant des composants préfabriqués alignés sur un langage de design ; DESIGN.md fournit un niveau de consignes adapté à ce type d’outils

• Theming client pour des UI adaptatives (Customer theming)

  • Dans des produits qui doivent générer des interfaces dynamiques — rapports, graphiques, tableaux de bord —, il peut aider les clients à décrire facilement leur propre marque afin que la sortie IA donne l’impression d’appartenir à cette marque
  • On peut l’imaginer comme une option que des administrateurs ou équipes marque téléversent dans leurs outils de travail
• Leur point commun : il s’agit d’UI générées par des agents dans des contextes où la sortie habituelle du design system existant est indisponible ou peu pratique

Démarrer et contribuer au standard

• Atlassian publie son fichier atlassian.design/DESIGN.md afin non seulement de réagir au standard, mais aussi de contribuer à le façonner
• Son fichier diffère encore du standard actuel sur certains points, inclut des propriétés non standard pour le rendu des composants, et comme le standard ne prend pas en charge le theming, Atlassian fournit aussi une variante dark mode séparée
• L’entreprise partage ses retours sur GitHub, précise que certaines propositions ont déjà été intégrées à la spécification, et encourage la participation de l’ensemble du secteur

Conclusion

• DESIGN.md est un format portable utile comme instantané d’un design system, mais ce n’est pas un remplaçant à des outils de design system plus riches
• Si les agents prennent en charge MCP ou les skills, ils fournissent de meilleurs résultats à moindre coût
• Pour la portabilité cross-platform, le theming client et le prototypage blue-sky, un DESIGN.md bien structuré apporte des améliorations significatives
• Quand les design systems deviennent lisibles par l’IA, tout l’écosystème en bénéficie