Design Md Convention

DESIGN.md — Convention Design System AI-Friendly

Convention inspirée de VoltAgent/awesome-design-md (55+ design systems populaires, concept Google Stitch).

Principe : un fichier DESIGN.md en markdown à la racine du projet sert de source de vérité pour les agents IA qui génèrent ou modifient l'UI. Pas de Figma, pas de JSON complexe, juste du texte lisible par humain et par LLM.

Pourquoi DESIGN.md ?

Structure recommandée

Un DESIGN.md contient 7 sections obligatoires :

1. Principes visuels — ton, personnalité, do/don't 2. Design tokens — couleurs, typographie, espacements, rayons, ombres 3. Grille & layout — breakpoints, colonnes, gutters, container widths 4. Composants — liste + variantes + règles d'usage 5. Patterns d'interaction — hover, focus, active, disabled, loading 6. Accessibilité — niveau cible (AA/AAA), contrastes, focus rings 7. Références — lien vers Figma (optionnel), design system inspiré

Voir .claude/templates/DESIGN.md.template pour la structure complète.

Règles de rédaction

1. Concis et structuré

• Tableaux > prose
• Tokens > valeurs hardcoded
• Exemples concrets > théorie

2. Tokens nommés, pas valeurs brutes

❌ MAUVAIS
Primary button: background #3B82F6

✅ BON
| Token | Valeur | Usage |
|-------|--------|-------|
| `color.primary.500` | #3B82F6 | Boutons primaires, liens actifs |
| `color.primary.600` | #2563EB | Hover des éléments primaires |

3. Do / Don't explicites

### Boutons

**DO**
- Utiliser `button.primary` pour l'action principale d'un écran (1 max)
- Utiliser `button.secondary` pour actions secondaires

**DON'T**
- Jamais 2 boutons primaires sur le même écran
- Jamais de couleur custom hors palette

4. Versionner avec le code

DESIGN.md est dans le repo, reviewé en PR au même titre que le code.

Intégration avec agents Claude Craft

Les agents suivants lisent DESIGN.md par défaut :

• `@ui-designer` — génère UI conforme aux tokens
• `@ux-ergonome` — valide les patterns d'interaction
• `@accessibility-expert` — vérifie contrastes vs niveau cible
• `@{react,vue,angular}-reviewer` — flag les valeurs hardcoded

Workflow recommandé

1. Nouveau projet → copier .claude/templates/DESIGN.md.template à la racine
2. Remplir les 7 sections (30-60 min)
3. Commiter DESIGN.md
4. Référencer depuis @.claude/CLAUDE.md projet : "@DESIGN.md"
5. Les agents IA le chargent automatiquement
6. Mettre à jour à chaque évolution du design system

Génération assistée

Command dédiée (Phase 4) : /uiux:generate-design-md

• Analyse tailwind.config.js ou tokens existants
• Pré-remplit les sections
• Demande validation sur les zones ambiguës

Exemples de DESIGN.md inspirants

• Stripe Dashboard
• Linear
• Vercel
• Liste complète : awesome-design-md

Anti-patterns

---

Date de dernière mise à jour : 2026-04-15 Version : 1.0.0