Design.md pour Claude Code : générer une UI cohérente

Si Claude Code te sort des interfaces propres mais génériques, le problème ne vient pas du modèle. Il vient du contexte que tu lui donnes. Un prompt dit quoi faire. Un DESIGN.md dit à quoi ça doit ressembler — et surtout, pourquoi.

C’est exactement le tournant que Google Labs essaie d’installer avec DESIGN.md : un fichier texte lisible par les agents, qui combine des tokens de design et une intention visuelle en prose. Le signal est déjà sérieux : le repo officiel dépasse les 14 400 étoiles, la collection awesome-design-md affiche 73 DESIGN.md et plus de 81 000 étoiles, et les extracteurs Figma / navigateur commencent à industrialiser le format.

La bonne question n’est donc pas “est-ce que Claude Code sait générer une UI ?”. La vraie question est : est-ce que tu lui donnes assez de règles pour éviter la UI par défaut ?

DESIGN.md et Claude Code : le duo à comprendre

DESIGN.md n’est pas un nouveau framework. C’est un contrat visuel. Google le décrit comme un format de spécification pour donner aux agents une compréhension persistante d’un système de design. Le fichier mélange deux choses :

des tokens lisibles par machine dans l’en-tête YAML ;
une rationale lisible par l’humain dans le markdown.

Le point important est là : les tokens donnent des valeurs exactes, la prose explique l’intention. Dans le README officiel, Google montre même qu’un agent qui lit le fichier produit une UI avec une typo, une palette et des CTA cohérents avec la direction visuelle voulue.

Concrètement, ça change le rôle du fichier. Avec CLAUDE.md, tu expliques à Claude Code comment travailler dans ton repo, comme le rappelle la doc officielle de Claude : structure du projet, standards de code, workflows, contexte persistant. Avec DESIGN.md, tu lui expliques comment ton produit doit se présenter.

Tu peux voir la logique comme ça :

CLAUDE.md = la manière de construire.
DESIGN.md = la manière de montrer.

Sans cette séparation, ton agent mélange tout. Il code juste assez bien pour produire une interface techniquement correcte, mais visuellement banale. C’est exactement le genre de sujet qu’on retrouve aussi dans mon article sur CLAUDE.md et AGENTS.md : le contexte utile n’est pas un blob de texte, c’est un système de règles bien découpé.

Pourquoi CLAUDE.md ne suffit pas pour le design

Le piège classique, c’est de remplir CLAUDE.md avec des consignes du type “utilise une UI moderne”, “reste cohérent”, “fais simple”. Ça ne marche pas. C’est trop vague pour un modèle qui doit choisir entre des dizaines d’options à chaque composant.

La doc Claude Code parle d’ailleurs d’un environnement .claude qui centralise instructions, skills, commandes, hooks et mémoire automatique. C’est puissant, mais ce n’est pas une direction artistique.

Le design a besoin d’autres contraintes :

une palette sémantique plutôt qu’une vague couleur “bleue” ;
une échelle typographique claire ;
des espacements récurrents ;
des rayons et ombres identiques ;
une densité d’interface stable ;
des règles d’accessibilité qui ne changent pas selon l’humeur du prompt.

Sans ça, Claude Code invente. Et quand il invente, il part en moyenne vers la solution la plus générique possible, parce que c’est statistiquement la plus sûre.

C’est pour ça qu’un DESIGN.md bien écrit n’est pas du “prompt engineering déguisé”. C’est de l’ingénierie de contrainte. Tu réduis l’espace de décision de l’agent pour qu’il produise quelque chose de répétable.

Les 8 invariants à mettre dans un DESIGN.md minimal

Si tu veux un fichier vraiment utile, ne commence pas par l’esthétique. Commence par les invariants.

Voici la base que je mettrais dans presque tous les projets :

Invariant	Ce que tu fixes	Pourquoi c’est important
Couleurs	palette principale, secondaire, neutres, états	évite les couleurs “presque pareilles”
Typographie	famille, tailles, poids, interlignage	garde une hiérarchie stable
Espacement	échelle 4/8/12/16/24/32	stop aux marges improvisées
Rayons	`sm`, `md`, `lg`	uniformise boutons, cards et modals
Ombres / élévation	une seule logique de profondeur	évite les interfaces “patchwork”
Densité	aéré, compact, admin, marketing	l’agent choisit le bon rythme
Composants	bouton, input, alert, card, table	empêche les variantes sauvages
Accessibilité	contraste, focus, états désactivés	le beau qui n’est pas lisible ne sert à rien

Tu n’as pas besoin de 40 pages. Tu as besoin d’un fichier qui dit clairement : “dans ce produit, les titres sont comme ça, les boutons comme ça, les sections comme ça”.

Le repo officiel de Google va d’ailleurs dans ce sens : il propose une commande de lint qui valide les références cassées et les contrastes, avec une sortie structurée, et une commande de diff pour détecter les régressions de tokens ou de prose. Ce n’est pas un détail. C’est la preuve que DESIGN.md doit être traité comme du code, pas comme un texte marketing.

Et le mieux, c’est que le contrôle qualité peut devenir concret : dans l’exemple du README, le lint remonte un contraste de 15,42:1 et le classe correctement comme conforme. Tu passes donc d’une “vibe” de design à un système vérifiable.

Comment le brancher à shadcn/ui sans créer du bruit

Si tu utilises shadcn/ui, l’intérêt de DESIGN.md est encore plus évident. La doc de theming repose sur des CSS variables et des paires sémantiques comme primary / primary-foreground. Autrement dit : tu ne stockes pas juste une couleur, tu stockes un rôle visuel.

C’est exactement le bon modèle pour un agent.

Voici le workflow simple :

Tu définis les tokens dans DESIGN.md.
Tu les traduis en variables CSS ou en thèmes shadcn.
Tu demandes à Claude Code de générer l’écran.
Tu vérifies le diff avec npx @google/design.md diff.
Tu lances le lint pour éviter les incohérences.

Le plus important, c’est de ne pas laisser l’agent réinventer la hiérarchie visuelle à chaque composant. Si ton button, ton badge et ton chip n’obéissent pas à la même logique, tu obtiens vite une UI qui “a l’air bonne” mais ne tient pas ensemble.

Le point fort de shadcn/ui, c’est justement d’exposer le style à travers des variables lisibles et des conventions simples. Le point fort de DESIGN.md, c’est d’enrichir ces conventions avec une intention de design plus large : ton rythme, ta densité, ton ton visuel, tes exceptions.

En pratique, c’est là que l’agent devient utile : il ne te fabrique pas une interface “jolie”, il te fabrique une interface cohérente.

Ce que l’écosystème montre déjà

Le format n’est pas théorique. Il y a déjà tout un mini-écosystème autour.

Projet	Ce qu’il apporte	Signal utile
Google DESIGN.md	la spec officielle, le lint et le diff	14 400+ étoiles
awesome-design-md	une collection de fichiers prêts à copier	73 DESIGN.md et 81 000+ étoiles
design-md-figma	export depuis Figma vers DESIGN.md / SKILL.md	pont design → agent
design-md-chrome	extraction d’un site web vers DESIGN.md	2 012 étoiles
DesignMD	extraction depuis une URL de prod	benchmark + CLI

Même côté benchmarks, le signal est clair : DesignMD annonce 56 sites mesurés, avec un npx @designmdcc/cli stripe.com > DESIGN.md en une ligne. Le message est simple : le format devient un standard de travail, pas juste un concept de thread X ou de repo tendance.

C’est aussi là que le sujet devient intéressant pour un dev ou un fondateur. Tu n’as pas besoin d’attendre qu’un outil soit “vraiment standard” pour l’utiliser. Tu as juste besoin d’un pattern qui réduit les erreurs et accélère la production.

Et honnêtement, c’est exactement ce que fait DESIGN.md : il réduit la variabilité.

Les limites : ce que DESIGN.md ne fera jamais à ta place

Il faut être net : un fichier de design ne résout pas un mauvais produit.

Si ton UI est confuse, tu peux écrire le plus beau DESIGN.md du monde, tu obtiendras juste une confusion plus élégante. Le format sert à codifier une direction, pas à la créer.

Il y a aussi trois pièges :

Le faux sentiment de contrôle. Tu crois avoir “documenté le design”, alors que tu as juste figé quelques tokens.
Le drift. Le fichier dit une chose, le code en fait une autre.
L’excès de précision. Trop de règles tue la flexibilité et rend le système pénible à maintenir.

Le bon réflexe, c’est donc de garder DESIGN.md proche de la source de vérité : composants réels, tokens réels, conventions réelles. Pas un document de marketing laissé mourir dans un coin du repo.

La bonne nouvelle, c’est que l’outillage va dans le bon sens. Le lint du repo Google peut vérifier les contrastes et les références cassées. Le diff te montre quand une intention de design glisse. C’est le genre de garde-fou qui évite que l’agent dérive au fil des PR.

Si tu veux un test simple : demande à l’agent de générer deux écrans à partir du même DESIGN.md. Si les deux se ressemblent vraiment, tu tiens quelque chose. Si le résultat change à chaque exécution, ton fichier est encore trop vague.

Template minimal prêt à copier

Tu peux commencer avec une version très simple comme celle-ci :

---
name: Dashboard Studio
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  accent: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Inter
    fontSize: 3rem
    fontWeight: 700
  body:
    fontFamily: Inter
    fontSize: 1rem
    lineHeight: 1.6
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
radius:
  sm: 6px
  md: 10px
  lg: 16px
motion:
  duration: 160ms
  easing: cubic-bezier(0.2, 0, 0, 1)
---

## Overview

Produit sobre, dense, lisible. Beaucoup d'air autour des blocs clés. Les CTA restent rares et assumés.

## Rules

- Une seule couleur d'accent pour les actions principales.
- Pas de bordures lourdes.
- Titres courts, alignés sur une grille simple.
- Les cartes doivent rester visuellement secondaires.
- Les états focus doivent être visibles.

## Components

### Button
Bouton principal plein, bouton secondaire ghost, jamais plus de deux styles par écran.

### Card
Fond neutre, ombre légère, rayon moyen, pas d'effet décoratif inutile.

### Form
Labels toujours visibles, aide contextuelle courte, erreurs explicites.

Le vrai intérêt du template, ce n’est pas de le copier tel quel. C’est de te montrer la logique : des tokens concrets, puis des règles d’usage, puis quelques composants critiques. Rien de plus.

Si tu veux aller plus loin, le bon réflexe est de faire l’inverse de ce que beaucoup font avec les prompts : au lieu d’ajouter des adjectifs, enlève du bruit.

Questions fréquentes

DESIGN.md remplace CLAUDE.md ?

Non. CLAUDE.md décrit le projet et la manière de travailler. DESIGN.md décrit le système visuel. Les deux se complètent.

Est-ce utile si je n’ai pas encore de design system ?

Oui, mais à petite échelle. Même un mini système avec 5 couleurs, 4 tailles de typo et 4 espacements rend déjà Claude Code beaucoup plus régulier.

Faut-il une maquette Figma pour commencer ?

Pas forcément. Tu peux partir d’un site existant, d’un produit de référence ou d’une UI déjà en place. Les plugins et extracteurs Figma / Chrome existent justement pour accélérer le passage à un DESIGN.md.

Ce qu’il faut retenir :

DESIGN.md n’est pas un prompt, c’est un contrat visuel. Tu donnes à l’agent des règles stables au lieu d’une intention vague.
Le duo avec Claude Code est logique. CLAUDE.md fixe le travail, DESIGN.md fixe le rendu.
Le format est déjà praticable. Google publie un lint/diff, des extracteurs Figma et navigateur existent, et des collections comme awesome-design-md montrent que l’écosystème prend forme.
La cohérence vaut plus que la créativité brute. Une UI générée par agent n’a pas besoin d’être surprenante. Elle doit être répétable, lisible et fidèle à ton système.

Si tu veux que ton agent fasse de bonnes interfaces, arrête de lui demander d’être “créatif”. Donne-lui d’abord un système.