Comment documenter un design system pour qu'une IA le respecte réellement

L'instinct est de diriger l'agent vers le site du design system. Cela aide rarement, pour quatre raisons structurelles qui n'ont rien à voir avec la qualité du site.

La ligne sur l'organisation est celle que les gens oublient. Un site organisé par composant est parfait pour quelqu'un qui sait déjà qu'il a besoin d'un Bouton. Un agent sur le point de construire un écran n'a pas encore décidé quels composants utiliser. Ses premières décisions concernent la densité, la hiérarchie et la mise en page, et c'est précisément ce qu'un site organisé par composants ne couvre jamais.

La ligne sur l'exhaustivité est la plus déterminante. La documentation décrit ce qui existe car c'est sa fonction. Mais la différence entre votre interface et une interface générique réside principalement dans un ensemble de choses que vous ne faites jamais, et aucune page de composant ne les mentionnera jamais.

Nous avons analysé 299 fichiers DESIGN.md publiés dans des dépôts et répertoires publics, des fichiers écrits délibérément pour donner des directives de design aux agents IA, et nous avons mesuré leur contenu. 72 étaient spécifiquement des fichiers de design visuel. Le schéma est suffisamment constant pour servir de checklist de ce qu'il faut éviter.

Mettez les deux dernières lignes en perspective. La typographie est mentionnée dans 83 % des fichiers, mais 44 % ne contiennent aucune valeur de taille concrète. Cet écart résume tout le problème en une seule statistique : les fichiers parlent de typographie sans jamais préciser la taille des éléments.

Le chiffre concernant les adjectifs représente l'autre moitié du problème. « Clean » apparaît dans 39 % de ces fichiers, « moderne » dans 36 %. Ce sont des termes qu'un modèle satisfait en produisant le centre de sa distribution d'entraînement, soit précisément le look générique que le fichier était censé éviter.

Chacun de ces points correspond à l'un des échecs mesurés plus haut. Appliqués ensemble, ils transforment une description en une instruction exécutable.

1. 1

   Attribuez un rôle à chaque couleur, pas seulement une valeur

   #6b7280 est une valeur qu'un modèle utilisera indistinctement pour le corps de texte, les bordures, les icônes, les placeholders et les états désactivés. --text-muted, décrit comme étant uniquement pour le texte secondaire et de soutien, a une fonction précise. Cinq rôles valent mieux qu'un code hexadécimal, et cela vous permet de modifier les bordures plus tard sans modifier les légendes.

   Copy

   --text-muted: #6b7280   /* secondary and supporting text only */
   --border-subtle: #e5e7eb /* structural edges, dividers */
   --text-disabled: #9ca3af /* disabled controls only */

2. 2

   Remplacez chaque adjectif par un nombre ou une règle

   « Espacement généreux » devient « écart de section 64px, padding de carte 24px ». « Typographie clean » devient une échelle. Si une phrase ne peut pas être vérifiée sur un écran rendu, c'est de la décoration.

3. 3

   Rédigez les interdictions

   C'est la section ayant l'impact le plus élevé, et celle que 76 % des fichiers omettent totalement. Cinq lignes suffisent pour commencer.

   Copy

   ## Never
   
   - No gradients
   - No drop shadows — elevation is a surface step plus a 1px border
   - No font-weight above 600
   - No colour value outside the token set
   - No border-radius above 12px

4. 4

   Définissez le mode sombre, ne le laissez pas être dérivé

   S'il n'est pas défini, le modèle inverse le mode clair, et le résultat échoue de manière prévisible : les ombres ne sont plus lisibles, les gris moyens perdent leur contraste aux deux extrémités, et un accent saturé qui paraissait assuré sur blanc devient éblouissant sur un fond presque noir. Un second jeu de tokens coûte une heure de travail et élimine toute une catégorie de retouches.

5. 5

   Énoncez explicitement la décision de densité

   Savoir s'il s'agit d'un outil dense ou d'une surface marketing aérée modifie chaque choix ultérieur, et c'est la décision que la plupart des fichiers ne prennent jamais. Si votre produit comporte les deux types de surfaces, créez deux fichiers distincts plutôt qu'un seul fichier ambigu.

6. 6

   Nommez au moins deux motifs

   Ces éléments spécifiques et récurrents qui rendent le design unique : une règle d'accentuation de 2px à gauche des titres de section, des colonnes numériques toujours tabulaires et alignées à droite, une manière particulière de dessiner les états vides. 57 % des fichiers n'en ont aucun, c'est pourquoi leur résultat est correct mais sans caractère.

7. 7

   Pointez vers le fichier de tokens ; ne le recopiez jamais

   Dès qu'une valeur hexadécimale existe à la fois dans le fichier de design et dans le fichier de tokens, l'un sera mis à jour et l'autre non, et le modèle utilisera avec assurance la valeur obsolète. Référencez, ne copiez pas.

Ce que produisent ces sept changements, au final, c'est un fichier dont les valeurs peuvent être résolues par un agent sans qu'il ait besoin d'inventer quoi que ce soit. Voici ces mêmes informations présentées sous forme de tableau plutôt que de texte : utile ici comme checklist de ce que votre propre fichier doit être capable de trancher :

Toutes les interdictions ne se valent pas. Trois propriétés distinguent celles qui modifient le résultat de celles qui sont ignorées.

C'est la troisième ligne qui est oubliée. Une interdiction sans alternative crée un vide que le modèle doit combler, et il le fait en puisant dans la même distribution d'entraînement que celle que vous essayiez d'éviter. Chaque "jamais X" devrait être suivi d'un "à la place, Y".

Le fichier doit tenir dans le contexte aux côtés de la tâche réelle, ce qui impose un plafond concret. Environ 400 lignes constituent un objectif viable ; au-delà, les règles individuelles perdent l'attention au profit de la tâche.

L'ordre compte également. Placez l'intention et les interdictions au début. Un modèle lisant de haut en bas rencontre la règle générale avant le cas particulier, ce qui correspond à l'ordre utilisé par Stripe dans son Appearance API : le thème d'abord, puis les variables, puis les règles spécifiques.

# DESIGN.md

## Intent            <- who reads this product, and what it is for
## Never             <- the prohibitions, early and unmissable
## Colour            <- roles for light and dark, referencing tokens
## Type              <- scale with real numbers, weight band, tracking
## Spacing & density <- the scale, and which surface uses which step
## Elevation         <- the strategy, stated once
## Composition       <- how components sit together
## Motifs            <- what makes this design specifically ours

Tout ne doit pas figurer dans le fichier ; tenter de tout y insérer est ce qui le rend trop volumineux pour être utile. La ligne de démarcation est de savoir si l'agent en a besoin avant de décider ou seulement à la demande.

Le serveur MCP Carbon d'IBM est un bon modèle pour la première colonne : il expose la recherche de documentation, des exemples de code de composants, des graphiques et des composants expérimentaux sous forme d'outils. Notablement, aucun de ces éléments n'est une interdiction, car un outil de récupération ne fait remonter que ce que l'agent a pensé interroger. Plus d'informations sur cette séparation.

Rédiger le fichier et supposer qu'il fonctionne est ainsi que les équipes découvrent le problème trois semaines plus tard. Quatre vérifications, par ordre croissant d'effort.

1. 1

   Recherchez les valeurs de couleur littérales via grep

   Si l'agent suit des rôles sémantiques, il ne devrait y avoir aucun hex en dehors de votre fichier de tokens.

   Copy

   grep -rn --include='*.tsx' --include='*.css' -E '#[0-9a-fA-F]{3,8}\b' src \
     | grep -v 'tokens\|globals.css'

2. 2

   Recherchez via grep les poids que vous avez interdits

   Le poids est l'endroit où la hiérarchie revient discrètement au mode par défaut, et c'est le signal le plus rapide qu'une interdiction n'est pas prise en compte.

   Copy

   grep -rn --include='*.tsx' -E 'font-(bold|extrabold|black)' src | head -30

3. 3

   Demandez deux fois le même écran, dans des sessions distinctes

   La cohérence entre les sessions est le véritable test. Si deux exécutions diffèrent de manière significative sur l'espacement, le radius ou la hiérarchie, le fichier ne contraint pas ce qu'il devrait, et le diff vous indique précisément quelle section est manquante.

4. 4

   Créez d'abord un écran en mode sombre

   Si le mode sombre a été dérivé plutôt que défini, c'est là que le problème apparaît. Il est bien moins coûteux de le détecter sur le premier écran que sur le vingtième.

Les deux premiers appartiennent à la CI. Un test qui échoue lors d'une pull request contenant une valeur hex brute est plus efficace pour la cohérence à long terme que n'importe quelle documentation, comme l'ont conclu Salesforce avec le linter SLDS et Stripe en supprimant totalement la fonctionnalité.