DESIGN.md : Résoudre l'incohérence UI avec Claude Code

Problème : Claude Code a un fort contexte local et un faible contexte produit. Il connaît le fichier qu'il édite. Il ne sait pas à quoi ton produit est censé ressembler. Entre les sessions, ton design system s'évapore. Des boutons apparaissent là où il devrait y avoir des liens. Les états vides disparaissent. Une couleur qui était #E07850 dans un composant devient orange-400 dans le suivant.

Victoire rapide : Dépose un fichier design.md à la racine du projet et référence-le depuis CLAUDE.md. Tes valeurs de design voyagent avec le codebase. Chaque session démarre avec les mêmes contraintes en contexte.

Ce qu'est vraiment design.md

Un fichier design.md est un design system en texte brut. Pas de syntaxe spéciale. Pas d'outillage requis. Couleurs, espacement, typographie, règles de composants, et états d'interaction écrits en Markdown lisible.

Google Stitch a introduit le format en mars 2026 et l'a positionné comme infrastructure d'interopérabilité, similaire à la façon dont README.md est devenu une convention universelle. La collection awesome-design-md sur GitHub a atteint 62 300 étoiles en avril 2026 et inclut 60+ design systems de marque au format : Stripe, Linear, Supabase, Vercel, Notion, et d'autres.

L'idée est simple. Claude Code lit des fichiers. Si le design system est un fichier, Claude Code lit le design system.

Pourquoi les sessions dérivent sans ça

Claude Code charge le contexte au début de chaque session. Il lit CLAUDE.md, scanne les fichiers ouverts, et se construit une image de ton projet. Sans fichier de design explicite, rien ne rattache les décisions UI à une source de vérité.

Tu as peut-être décrit la couleur primaire dans un commentaire quelque part. Ou une classe Tailwind dans un composant. Claude lit ce qu'il ouvre en premier et extrapole à partir de là. Trois sessions plus tard, ton UI est une collection de suppositions.

Un fichier design.md dans CLAUDE.md change l'input. Les valeurs sont explicites, pas inférées. Chaque session s'ouvre avec la même source de vérité en contexte.

Obtenir design.md depuis Google Stitch

Google Stitch est un outil de design UI de Google Labs, lancé à Google I/O en mai 2025. Il tourne sur Gemini 2.5 Pro, vit à stitch.withgoogle.com, et est gratuit pendant la phase Labs (compte Google, pas de liste d'attente, 350 générations par mois sur le tier gratuit). L'export design.md est arrivé dans Stitch 2.0 le 18 mars 2026.

Le workflow pour générer ton fichier :

1. Va sur stitch.withgoogle.com. Clique sur l'onglet Web (pas App). Sélectionne le modèle Pro le plus élevé disponible.
2. Optionnellement, uploade une capture d'écran de référence de ton UI actuel ou une image d'inspiration.
3. Écris un brief décrivant ta marque : couleurs, ton, style de composants, ce que fait le produit.
4. Itère de façon conversationnelle jusqu'à ce que l'output corresponde à ton intention.
5. Clique sur Export, choisis DESIGN.md, sauvegarde le fichier à la racine de ton projet.

Stitch construit un fichier structuré couvrant les tokens de couleur, l'échelle typographique, les unités d'espacement, les patterns de composants, et les définitions d'états (hover, focus, active, disabled). L'output est portable. Il fonctionne avec Claude Code, Cursor, Windsurf, ou n'importe quel outil qui lit des fichiers.

Câbler CLAUDE.md sur le fichier

Déposer design.md à la racine ne suffit pas. Sans instructions explicites dans CLAUDE.md, Claude traite le fichier comme du matériel de référence qu'il peut consulter. Avec des instructions explicites, Claude traite les valeurs comme des contraintes qu'il doit suivre.

Le bloc qui fonctionne :

## Design System
This project uses a design system defined in `design.md` at the project root.
Always refer to this file when generating or modifying any UI component.
- Use only colors, fonts, and spacing values defined in design.md.
- Do not invent new values or use defaults from any framework.
- Match component states (hover, focus, active, disabled) to the patterns in design.md.
- Follow the typographic scale and weight assignments in design.md.
@design.md

L'import @design.md en bas injecte le contenu complet du fichier au démarrage de la session. Les quatre points transforment une référence passive en contraintes actives. Les deux parties comptent. L'import seul donne à Claude un document. Les instructions donnent à Claude une règle.

Vérifier le câblage avant de construire

Après avoir mis à jour CLAUDE.md, confirme que Claude a bien chargé les valeurs correctement :

Demande à Claude : What primary color is defined in design.md?

S'il retourne le bon hex, l'import fonctionne. S'il hésite ou devine, vérifie que @design.md apparaît à la fin du bloc et que le chemin du fichier est exactement correct (sensible à la casse sur Linux).

Fais cette vérification au début de toute session impliquant du travail UI. Ça prend dix secondes et attrape un import manquant avant que ça devienne un problème de dérive.

Ajouter une couche d'application Tailwind

CLAUDE.md est du contexte. Tailwind est de l'application. Les deux fonctionnent ensemble.

Traduis les valeurs de tokens de ton design.md dans tailwind.config.js. Quand Claude écrit bg-blue-500 au lieu de bg-primary, le build échoue. C'est le comportement correct. Une erreur de type au moment du build vaut mieux qu'une incohérence visuelle que tu découvres au quatrième écran.

Un bloc de config minimal pour une marque à deux couleurs ressemble à ça :

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#E07850',
        'primary-dark': '#C5613A',
        surface: '#1A1A1A',
        'surface-elevated': '#1E1B18',
        text: '#FFFFFF',
        'text-muted': '#999999',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
        mono: ['JetBrains Mono', 'monospace'],
      },
    },
  },
}

Toute valeur dans design.md doit avoir un token nommé dans cette config. Claude écrit alors des tokens, pas des valeurs brutes. Le build attrape tout ce qui passe à travers les mailles.

Six modes d'échec

Ce sont les façons dont le setup casse en pratique.

Exporter trop tôt. Stitch génère des couleurs placeholder et des états manquants si ton brief est mince. Itère jusqu'à ce que l'output soit complet avant d'exporter. Les lacunes dans design.md deviennent des lacunes dans les contraintes de Claude.

Instructions CLAUDE.md vagues. L'import seul ne suffit pas. Les quatre points dans le bloc ci-dessus transforment un document en règle. Sans eux, Claude lit le fichier et décide ensuite de combien le suivre.

Pas de traduction Tailwind. La dérive attrapée dans une review visuelle après quatre écrans coûte plus qu'une erreur de build attrapée après un composant. Ajoute la couche de config avant de commencer à construire.

design.md pas dans le contrôle de version. Si c'est pas dans le repo, un nouveau clone ou un nouveau membre de l'équipe démarre sans design system. Committe le fichier dès que tu le crées.

Fichier obsolète après une refonte. Quand tu changes la marque, ré-exporte depuis Stitch. Un design.md qui décrit les couleurs du trimestre dernier est pire qu'aucun fichier du tout : il donne à Claude des réponses confiantes mais erronées.

Pourriturre de contexte dans les longs fichiers. L'information au milieu d'une longue fenêtre de contexte est rappelée moins fiablement que l'information au début ou à la fin. Garde design.md sous 2 000 à 3 000 tokens. Divise par catégorie (couleur, typographie, espacement, composants) si le fichier dépasse ça.

Alternatives à Stitch

Stitch est le chemin le plus rapide vers un design.md complet, mais quatre autres approches fonctionnent.

Extraction manuelle depuis DevTools. Ouvre Chrome DevTools, inspecte les éléments clés (boutons, titres, cartes), copie le CSS calculé dans Claude, puis demande : Turn this into a design system as a markdown file. Cinq minutes. Fonctionne bien pour les produits existants où tu dois capturer l'état actuel plutôt que définir un nouveau système.

awesome-design-md sur GitHub. La collection à github.com/VoltAgent/awesome-design-md a 60+ design systems de marque au format DESIGN.md en avril 2026. Si tu construis quelque chose d'adjacent à une esthétique de marque existante, pars d'une référence et édite plutôt que de générer from scratch.

Figma MCP. Claude Code se connecte à Figma directement via MCP et lit les tokens de design en temps réel. Une étude de cas de Parallel HQ a rapporté 62% moins d'incohérences de design et 78% de meilleure efficacité de workflow sur six mois. La contrepartie est la friction d'authentification. Stitch exporte un fichier autonome ; Figma MCP nécessite une connexion live et une gestion de tokens.

Extraire depuis une URL. Stitch accepte des URLs publiques en input. Colle l'URL d'un site marketing propre et Stitch lit le style visuel. Fonctionne bien pour les pages publiques propres, galère avec les dashboards authentifiés.

Claude Design vs. design.md

Claude Design a lancé le 17 avril 2026, propulsé par Opus 4.7 avec un nouveau mode vision 2 576px. Il crée du travail visuel par conversation et produit un bundle de handoff à l'intérieur de l'écosystème Anthropic. Une entreprise d'edtech a rapporté que des pages nécessitant 20+ prompts sur d'autres outils n'en nécessitaient que 2 dans Claude Design.

La différence avec le workflow design.md se résume à la portabilité. Claude Design produit des artefacts liés au stack Anthropic. Un design.md depuis Stitch est un fichier brut qui fonctionne avec n'importe quel outil qui lit des fichiers : Claude Code, Cursor, Windsurf, ou un script de build personnalisé.

Claude Design est plus rapide si tu restes dans l'écosystème Anthropic. design.md est mieux si tu veux que le design system voyage avec le codebase, versionné aux côtés du code qu'il gouverne.

Ce que tu obtiens

Un fichier à la racine du repo. Quatre lignes dans CLAUDE.md. Des tokens nommés dans tailwind.config.js.

Chaque session s'ouvre avec les mêmes contraintes de design en contexte. Chaque build échoue sur les valeurs brutes au lieu de laisser la dérive s'accumuler. Chaque écran que Claude touche suit les mêmes règles que le dernier.

La cohérence du design n'est pas un processus de review. C'est un fichier.

Questions fréquentes

C'est quoi design.md dans Claude Code ?

design.md est un fichier texte brut à la racine de ton projet qui définit ton design system : couleurs, typographie, espacement, règles de composants, et états d'interaction. Quand il est référencé dans CLAUDE.md avec l'import @design.md, Claude Code charge ces valeurs au démarrage de la session et les traite comme des contraintes plutôt que des suggestions, gardant chaque écran cohérent entre les sessions.

Comment utiliser design.md avec Claude Code ?

Exporte un fichier design.md depuis Google Stitch ou écris-en un manuellement, place-le à la racine de ton projet, puis ajoute un bloc ## Design System à CLAUDE.md qui inclut l'import @design.md et quatre règles en points. Enfin, traduis tes valeurs de tokens dans tailwind.config.js pour que le build échoue sur toute valeur brute qui contourne le système.

Google Stitch est-il gratuit ?

Oui, pendant la phase Google Labs. Le tier gratuit sur stitch.withgoogle.com inclut 350 générations par mois avec accès à toutes les fonctionnalités principales et ne requiert qu'un compte Google sans liste d'attente. Stitch 2.0, qui a introduit l'export design.md, a lancé le 18 mars 2026. Les tarifs pourraient changer quand Stitch sortira de la phase Labs.

C'est quoi le repo awesome-design-md ?

awesome-design-md est une collection GitHub maintenue par VoltAgent à github.com/VoltAgent/awesome-design-md. Elle contient 60+ fichiers DESIGN.md prêts à l'emploi modélisés sur de vrais design systems de marque incluant Stripe, Linear, Supabase, Vercel, et Notion. Tu peux en déposer un directement dans ton projet comme point de départ et l'éditer pour correspondre à ta marque plutôt que de générer from scratch.

Comment empêcher Claude Code d'ignorer mon design system ?

Deux choses sont nécessaires ensemble, pas séparément. D'abord, ajoute l'import @design.md à la fin du bloc design dans CLAUDE.md pour que le contenu du fichier se charge au démarrage de la session. Ensuite, ajoute des règles explicites en points au-dessus de l'import qui disent à Claude d'utiliser seulement les valeurs du fichier et de ne pas en inventer de nouvelles. L'import seul donne à Claude un document ; les règles donnent à Claude une contrainte.

design.md vs Figma MCP : lequel est mieux pour Claude Code ?

Ils résolvent le même problème différemment. Figma MCP connecte Claude à Figma en temps réel, lui donnant accès aux tokens de design et composants en live, mais ça nécessite une configuration d'authentification et une connexion persistante. Un design.md depuis Stitch est un fichier autonome qui fonctionne hors ligne, voyage avec le repo, et se versionne aux côtés de ton code. Figma MCP convient aux équipes déjà bien dans Figma ; design.md convient aux builders solos qui veulent zéro infrastructure.