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.

C'est la ligne sur l'organisation 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 mesuré leur contenu. 72 étaient spécifiquement des fichiers de design visuel. Le schéma est suffisamment constant pour servir de liste de contrôle de ce qu'il faut éviter.

Mettez les deux dernières lignes en regard. 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 mots qu'un modèle satisfait en produisant le centre de sa distribution d'entraînement, ce qui correspond précisément au look générique que le fichier était censé éviter.

Chacun d'entre eux répond à l'un des échecs mesurés ci-dessus. 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 ils vous permettent 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 le plus d'impact, 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, cela nécessite deux fichiers, et non 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 mettre 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 que cela fonctionne est le meilleur moyen pour les équipes de découvrir le problème trois semaines plus tard. Quatre vérifications, par ordre croissant d'effort.

1. 1

   Rechercher les valeurs de couleur littérales via grep

   Si l'agent respecte les rôles sémantiques, aucune valeur hexadécimale ne devrait se trouver 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

   Rechercher les graisses de police interdites via grep

   La graisse est l'endroit où la hiérarchie revient discrètement aux valeurs par défaut ; c'est le signal le plus rapide pour savoir qu'une interdiction n'est pas appliquée.

   Copy

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

3. 3

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

   La cohérence entre les sessions est le véritable test. Si deux exécutions diffèrent significativement sur l'espacement, le rayon des bordures ou la hiérarchie, c'est que le fichier ne contraint pas assez — et le diff vous indique précisément quelle section manque.

4. 4

   Construire d'abord un écran en mode sombre

   Si le mode sombre a été déduit plutôt que défini, c'est ici qu'il apparaîtra. Il est bien moins coûteux de s'en rendre compte sur le premier écran que sur le vingtième.

Les deux premiers tests doivent être intégrés à la CI. Un contrôle qui rejette une pull request contenant une valeur hexadécimale brute fait plus pour la cohérence à long terme que n'importe quelle documentation, conclusion à laquelle sont parvenus Salesforce avec le linter du SLDS et Stripe en supprimant complètement cette possibilité.