DESIGN.md minimal : template pour générer une UI cohérente avec Claude Code

Introduction

Si tu laisses Claude Code générer une UI sans contrat visuel, tu obtiens vite des composants qui se contredisent : couleurs différentes, espacements incohérents, boutons qui ne ressemblent pas à ceux du reste de l’app. Le fix n’est pas plus d’engineering ni plus d’heures : c’est un fichier court et actionnable appelé DESIGN.md. Ici, je te donne un template minimal, les invariants à verrouiller et la checklist pour l’intégrer dans un repo (monorepo ou package) de façon à ce que Claude Code respecte ton identité visuelle dès la première itération.

Pourquoi maintenant

Les outils qui génèrent du code UI (Claude Code, multica, agents) deviennent des co-développeurs — ils exécutent des commandes et touchent des fichiers. Un DESIGN.md bien écrit transforme cette automation en prédictible : tu perds moins de temps à corriger l’UI et tu gagnes en cohérence visuelle.

Thèse centrale

Un DESIGN.md utile est court, prescriptif et composé d’invariants (tokens, composants, règles d’espacement). Donne à Claude des règles concrètes — pas des principes vagues — et il produira des composants compatibles entre eux.

Comment lire cet article

• Je commence par un template prêt à copier.
• Ensuite 7 invariants que tu dois verrouiller.
• Enfin, intégration pratique avec CLAUDE.md et un exemple monorepo.

TEMPLATE MINIMAL — copie colle

# DESIGN.md

## Tokens de base
primary: #0E6FFF
primary-foreground: #ffffff
background: #ffffff
surface: #F8FAFC
muted: #6B7280

## Espace (scale)
space-0: 4px
space-1: 8px
space-2: 16px
space-3: 24px

## Typographie
font-family: Inter, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue"
font-sizes: { small: 13px, base: 16px, large: 20px }
line-height: 1.4

## Composants (contrat minimal)
button.primary: background=primary; color=primary-foreground; padding=space-1 space-2; border-radius=8px
button.ghost: background=transparent; border=1px solid muted; color=primary
card: background=surface; padding=space-2; border-radius=12px; shadow=sm
input: border-radius=8px; border=1px solid #E5E7EB; padding=space-1

## Règles rapides
- Utilise tokens uniquement (ne pas coder couleurs hex dans les composants)
- Les boutons primaires utilisent toujours `button.primary`
- Les composants hébergent des classes utilitaires limitées (max 3)

## Où chercher
- Composants importants: src/components, src/ui
- Entrée principale: packages/frontend/src/index.tsx

## Limites : NE PAS TOUCHER
- Ne pas modifier tokens sans bump minor + tests visuels
- Ne pas ajuster shadows sans reviewer humain

7 invariants à verrouiller (ce que doit contenir ton DESIGN.md)

1. Tokens explicites et un seul endroit pour les modifier

• Définit toutes les couleurs qui comptent (primary, background, surface, muted, accent). Pas de couleurs ad hoc dans les composants.
• Pourquoi : ça évite des divergences quand l’agent génère un nouveau composant.

2. Echelle d’espacements (spacing scale)

• Donne 3–5 valeurs (4px, 8px, 16px, 24px). Demande à l’agent d’utiliser uniquement ces tokens.
• Pourquoi : les marges uniformes font paraître une UI pro.

3. Contrat composants minimal

• Déclare 3–6 composants clés (button.primary, card, input, table, badge).
• Pour chaque composant, donne le mapping token→propriété (ex: button.primary → background=primary).

4. Typographie et ratio simple

• Police, petite/standard/grande, line-height. Demande d’utiliser font-size tokens.

5. Règles de contraste et accessibilité

• Spécifie que la couleur du texte sur primary doit respecter WCAG AA (ou donne un fallback).

6. Exemple concret de snippet d’utilisation

• Montre 2 exemples concrets : un bouton primaire dans une card; un formulaire avec label+input+hint.
• Ces snippets servent de tests rapides pour valider le contrat.

7. Dépôt & emplacements (pour les agents)

• Indique les chemins où l’agent doit chercher (packages/frontend/src/components, src/ui), et les commandes exactes pour dev/build/test (ex: pnpm --filter=@myorg/frontend dev). Ça évite aux agents d’explorer inutilement le repo.

Intégrer DESIGN.md avec CLAUDE.md et Claude Code (procédure)

1. Place DESIGN.md à la racine du package (ex: packages/frontend/DESIGN.md). Pour petits projets, ./DESIGN.md suffit.
2. Dans CLAUDE.md du même package, ajoute une section courte :

## Respecter le contrat visuel
- Voir `packages/frontend/DESIGN.md` pour tokens et règles
- Dev/test: `pnpm --filter=@myorg/frontend dev`
- Critère de validation: les snapshots visuels sont identiques (voir /tests/visual)

3. Demande à Claude Code d’appliquer uniquement les tokens définis :

• Prompt minimal à donner à Claude (extrait): “Quand tu génères un composant UI, utilise exclusivement les tokens listés dans packages/frontend/DESIGN.md. Ne pas ajouter de nouvelles couleurs; si tu as un doute demande un flag ‘nouveau-token’.”

Exemple monorepo (pnpm) — pourquoi privilégier des DESIGN.md par package

• Dans un monorepo, un DESIGN.md par package réduit les biais : les agents n’ont pas à trier un énorme fichier racine. Le template claude-md-monorepo-template.md (référence interne) recommande d’indiquer le package ciblé en tête de CLAUDE.md — fais de même pour DESIGN.md.
• Voir le template CLAUDE.md monorepo disponible dans nos références pour la syntaxe (ex: packages/frontend).

Checklist d’intégration rapide (5 min)

• Créer packages/frontend/DESIGN.md (ou ./DESIGN.md) avec tokens et 3 composants au minimum
• Ajouter la ligne “Voir DESIGN.md” dans packages/frontend/CLAUDE.md
• Ajouter un test visuel simple: tests/visual/button-primary.test.ts qui snapshot le rendu
• Copier placeholder image pour l’article (assets)
• Commit & PR (voir la checklist pré-commit du repo)

FAQ (questions que les gens cherchent)

Q: DESIGN.md va-t-il remplacer un design system ? A: Non. C’est un contrat minimal pour rendre les agents productifs. Un vrai design system (tokens, figma, docs) est complémentaire.

Q: Dois-je générer DESIGN.md automatiquement ? A: Non. Les agents peuvent proposer un draft, mais il doit être édité par un humain. Trop d’instructions ou de bruit empêchent Claude de suivre le contrat.

Ce qu’il faut retenir (takeaways actionnables)

• Rends DESIGN.md court et prescriptif : tokens, spacing, 3 composants.
• Place-le à l’endroit où l’agent va chercher (package scope de préférence).
• Lien direct dans CLAUDE.md et commandes exactes pour dev/test.
• Toujours vérifier avec un test visuel avant de merger une PR générée par un agent.

Sources & références

• Template CLAUDE.md (internes) — /root/.openclaw/skills/ai-blog-editor/references/claude-md-monorepo-template.md
• Notes DESIGN.md (internes) — references/design-md-claude-code-note.md
• Claude Code — Best practices docs: https://code.claude.com/docs/en/best-practices
• shadcn UI theming — guide tokens/theming: https://ui.shadcn.com/docs/theming
• Claude-Mem (persistent memory for Claude Code): https://github.com/thedotmack/claude-mem