Design systems pour les agents de code IA

Demandez à n'importe quel agent de code de « créer une landing page » et vous obtiendrez la même chose : un hero presque noir, un dégradé violet, la police Inter, trois cartes de fonctionnalités avec des coins arrondis. C'est compétent mais totalement générique, car le modèle n'a aucune mémoire de votre marque entre deux prompts. Ajoutez une seconde page et le style dérive : espacements différents, un bleu légèrement différent, une nouvelle forme de bouton. Il n'y a aucune source de vérité pour l'aspect visuel, donc aucune cohérence.

Il est important d'être précis sur le pourquoi, car la raison détermine la solution. Le modèle n'échoue pas en design. Il fait exactement ce qu'on lui a demandé : produire l'interface la plus probable compte tenu de la requête. En l'absence de contrainte, l'interface la plus probable est la moyenne de tout ce qu'il a vu, et tous ceux qui promptent sans contraintes arrivent au même résultat.

Cela redéfinit la solution. Vous ne cherchez pas à rendre l'agent plus créatif. Vous cherchez à l'extraire de cette moyenne pour le maintenir dans un cadre spécifique, ce qui nécessite de définir précisément où se trouve ce cadre et ce qui en est exclu.

Nous avons échantillonné 299 fichiers DESIGN.md publiés dans des dépôts et répertoires publics (des fichiers réels, écrits par des équipes réelles pour guider les agents en design) et avons mesuré leur contenu réel plutôt que leurs intentions. 72 étaient spécifiquement des fichiers de design visuel. Le schéma est suffisamment constant pour établir un diagnostic.

La dernière ligne est révélatrice. La typographie est mentionnée dans 83 % des fichiers, et 44 % de ces mêmes fichiers ne contiennent aucune valeur de taille concrète. « Utilisez une hiérarchie typographique claire » est une mention. Ce n'est pas une instruction, et le modèle la satisfait en utilisant la hiérarchie la plus courante dans ses données d'entraînement.

Les deux chiffres les plus importants sont celui des interdictions et celui des rôles sémantiques, et ils échouent de la même manière. Un fichier indiquant que #3b82f6 est la couleur « primary » sans rien interdire indique au modèle qu'un bleu spécifique existe, tout en laissant chaque décision d'utilisation totalement ouverte. L'agent l'utilise alors pour les titres, les liens, le remplissage des icônes, une bordure et un dégradé, car tous ces usages sont plausibles pour une couleur primaire.

Pour qu'un design system survive à la lecture par un modèle, à son application sur vingt fichiers et à sa reprise lors d'une session ultérieure, il doit comporter six parties. Chacune d'elles corrige un échec spécifique.

La ligne sur le mode sombre est celle que les équipes sous-estiment. Dériver le mode sombre en inversant le mode clair est ce qu'un modèle fait quand rien ne lui indique le contraire, et cela échoue de manière prévisible : les ombres ne sont plus lisibles sur les surfaces sombres, les gris moyens perdent leur contraste avec le texte et l'arrière-plan, et un accent saturé qui paraissait assuré sur blanc devient criard sur un fond presque noir. Le définir demande un second ensemble de tokens, mais élimine toute une catégorie de retouches.

Un kit est un système complet, pas une simple palette. Voici un aperçu en direct du kit gratuit ambient-sage : les mêmes tokens, polices et traitements qu'un agent reçoit lors de son application. Tout sur cette page pourrait être redessiné en changeant de kit.

Quel que soit le mode d'installation, la charge utile comprend toujours ces trois éléments :

1. Un DESIGN.md : le brief écrit : l'intention du design, le système typographique, les règles d'espacement et de mise en page, le traitement des composants, les motifs distinctifs, ainsi que les « do's & don'ts ». C'est ce qui empêche l'agent de retomber dans le générique. Qu'est-ce qu'un DESIGN.md et comment en générer un.
2. Des tokens de couleurs sémantiques : 28 rôles (background, foreground, primary, muted, card, border, chart-1…5, etc.) en modes clair et sombre. L'agent stylise en fonction des noms de rôles et non de codes hexadécimaux bruts, garantissant la cohérence des thèmes. Explications sur les tokens de couleurs sémantiques.
3. Des exports de framework : le même système sous forme de variables CSS, de @theme Tailwind v3/v4, d'élément de registre shadcn, ou de JSON DTCG/W3C. L'agent connecte celui qui correspond à votre stack.

Les noms de rôles du second élément sont plus puissants qu'il n'y paraît. --color-muted-foreground indique au modèle à la fois quelle est la valeur et où elle doit être placée ; --gray-400 n'indique que la valeur, et l'agent décide alors lui-même quel gris utiliser pour une légende. C'est dans cette décision que la cohérence s'effrite, fichier après fichier.

La mécanique diffère selon l'outil : les agents de code exécutent un serveur MCP local, les constructeurs web utilisent le registre shadcn ou le fichier DESIGN.md exporté. Choisissez votre outil :

• Donner un design system à Claude Code : MCP via .mcp.json, ou identityforge apply.
• Donner un design system à Cursor : MCP via .cursor/mcp.json, plus comment structurer les fichiers de règles.
• Donner un design system à Windsurf : configuration MCP manuelle pour Cascade, plus le chemin CLI.
• Donner un design system à v0 : le registre shadcn + DESIGN.md comme brief.
• Donner un design system à Lovable : connaissance du projet + ajout de shadcn dans le repo.
• Donner un design system à Bolt : exécuter shadcn add directement dans le terminal de Bolt.

Les deux, et pour des raisons différentes. Il est crucial de bien faire la distinction, car installer un serveur MCP en espérant un résultat visuellement plus abouti est une déception courante.

Les interdictions sont le cas d'école pour le fichier. Un agent sur le point d'ajouter une ombre portée n'a aucune raison de demander « les ombres portées sont-elles autorisées » ; ainsi, une contrainte cachée derrière un appel d'outil est une contrainte qui ne s'active jamais. Les contraintes doivent être présentes avant la décision. Plus de détails sur l'emplacement de chacun.

Parcourez les kits par style visuel pour voir des systèmes complets en contexte : typographie, couleurs, surfaces et règles de construction. Chaque kit possède un id permanent et un slug lisible ; une fois l'un ou l'autre connu, l'agent peut ignorer la recherche et l'appliquer directement. Les slugs peuvent être renommés, mais l'ancien continue de fonctionner, donc un identifiant stocké ne devient pas obsolète. Si vous avez déjà des couleurs de marque, l'outil MCP match_palette trouve les kits les plus proches visuellement.

Installer un design system et supposer qu'il fonctionne est le meilleur moyen d'avoir des surprises trois semaines plus tard. Quatre vérifications, par ordre croissant d'effort :

1. 1

   Grep pour les valeurs de couleur littérales

   Le signal le plus rapide. Si l'agent suit les design tokens sémantiques, il ne devrait y avoir aucun hexadécimal en dehors de votre fichier de tokens.

   Copy

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

2. 2

   Vérifier les graisses de police

   C'est au niveau de la graisse que la hiérarchie revient discrètement aux valeurs par défaut. Si votre système n'autorise que le 400 et le 600, tout autre choix est une dérive.

   Copy

   grep -rn --include='*.tsx' -E 'font-(bold|extrabold|black|semibold)' 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 produisent des espacements, des rayons ou une hiérarchie significativement différents, le système ne contraint pas suffisamment.

4. 4

   Construire un premier écran en mode sombre

   Si le mode sombre a été dérivé plutôt que défini, c'est ici que cela se voit : ombres inertes, gris moyens ternes, accent trop vif. Il est moins coûteux de s'en rendre compte maintenant qu'après vingt écrans.

Les deux premières vérifications valent la peine d'être intégrées à la CI. Une règle qui détecte une valeur hexadécimale brute dans une pull request fait plus pour la cohérence à long terme que n'importe quelle documentation, conclusion à laquelle Salesforce est parvenu avec le linter SLDS.