Cet article explique ce mécanisme, ce que les études en disent réellement, et comment écrire une documentation de design system à la fois courte et complète. Un avertissement d'emblée : les modèles évoluent vite, et plusieurs résultats cités ici ont été mesurés sur des générations antérieures. Nous distinguons donc ce qui est établi de ce qui relève de la bonne pratique.
Ce que Claude fait de votre documentation
Claude ne « consulte » pas votre design system comme un designer feuillette un guide : il le charge dans sa fenêtre de contexte, l'espace de texte qu'il traite à chaque réponse. Tout ce qui s'y trouve est lu en même temps, l'utile comme le superflu.
Anthropic décrit cette ressource comme un budget d'attention limité, qu'il compare à la mémoire de travail humaine. Chaque token ajouté (un token correspond à un fragment de mot) en consomme une part. La raison est architecturale : dans un modèle de type transformer, chaque token peut se rapporter à tous les autres, soit n² relations pour n tokens. Plus le contexte s'allonge, plus cette attention se répartit finement (Anthropic, 2025).
Imaginez un briefing avant une intervention. Donné en cinq minutes, avec les trois consignes qui comptent, il est retenu. Noyé dans une heure de détails, la consigne critique risque de passer inaperçue, même si elle a bien été prononcée.
Anthropic précise que cette dégradation est progressive, pas brutale : les modèles restent très capables sur des contextes longs, mais peuvent perdre en précision pour retrouver une information ou raisonner sur des éléments éloignés. D'où sa recommandation : chercher le plus petit ensemble d'informations pertinentes qui maximise le résultat attendu. Il ajoute une nuance essentielle pour notre sujet : minimal ne veut pas dire court. L'agent doit tout de même recevoir assez d'informations pour se comporter correctement.
Ce que dit la recherche
Quatre travaux convergent : un contexte plus long ou plus bruité tend à dégrader les réponses des modèles de langage. Aucun ne porte spécifiquement sur les design systems, il s'agit donc d'une transposition raisonnée, pas d'une preuve directe.
1. Une information noyée au milieu est moins bien exploitée. Des chercheurs de Stanford ont mesuré que les performances sont souvent meilleures quand l'information utile se trouve au début ou à la fin du contexte, et qu'elles chutent quand elle est enfouie au milieu d'un long texte, y compris pour des modèles conçus pour les contextes longs (Liu et al., 2024).
2. Une seule information hors sujet peut suffire à dérouter. Une équipe de chercheurs a ajouté des phrases sans rapport à des problèmes de mathématiques simples : la précision des modèles a fortement baissé. Bonne nouvelle toutefois, une consigne demandant explicitement d'ignorer l'information non pertinente atténue l'effet (Shi et al., 2023).
3. La dégradation apparaît bien avant la limite technique. En ne faisant varier que la longueur du texte, à tâche identique, une étude présentée à ACL 2024 observe une baisse nette du raisonnement dès quelques milliers de tokens, très en deçà de la capacité maximale annoncée des modèles (Levy et al., 2024).
4. Le phénomène persiste sur les modèles récents. Le rapport « Context Rot » de Chroma a testé 18 modèles, dont Claude Sonnet 4 et Opus 4. Tous obtiennent de meilleurs résultats avec une version ciblée d'environ 300 tokens qu'avec la version complète d'environ 113 000 tokens contenant la même réponse. Le rapport montre aussi qu'un seul « distracteur » (une phrase proche de la bonne réponse, mais fausse) fait baisser les performances (Hong et al., 2025).
Comprendre le phénomène : cherchez une aiguille dans une botte de foin : c'est difficile. Cherchez-la dans une botte d'aiguilles presque identiques : c'est pire. Dans un design system, deux règles quasi identiques pour deux boutons voisins jouent exactement ce rôle de fausse aiguille.
Ces études utilisent des tâches de laboratoire (questions-réponses, arithmétique, recherche d'une phrase), pas la génération d'interfaces. Les deux premières portent sur des modèles de 2023, moins robustes que les actuels. Le rapport Chroma est un rapport technique d'entreprise, non évalué par des pairs, publié par un éditeur de base de données dont l'activité bénéficie de ce constat. Enfin, l'effet de position n'est pas universel : Chroma ne l'a pas retrouvé sur l'une de ses tâches. La tendance générale reste néanmoins cohérente d'une étude à l'autre.
La sobriété, aussi un enjeu environnemental
Chaque token lu par le modèle mobilise du calcul, donc de l'énergie. Des chercheurs de l'université de Cambridge ont mesuré la consommation de plusieurs modèles open source en faisant varier séparément la longueur du texte d'entrée et celle de la réponse. Les deux ont un effet significatif sur l'énergie consommée, avec un effet plus fort pour les tokens produits que pour les tokens lus (Wilkins et al., 2024).
Une documentation de design system est relue à chaque demande, comme un trajet quotidien. Raccourcir le parcours d'un kilomètre paraît anodin pour un trajet ; sur des milliers de trajets, l'économie devient réelle.
À pondérer, et sérieusement. Trois limites empêchent d'en tirer un chiffre pour Claude :
- Les mesures portent sur d'autres modèles et d'autres machines. L'étude a testé des modèles comme Llama 2 ou Mistral, sur des processeurs graphiques A100, avec certaines optimisations volontairement désactivées. Les auteurs soulignent eux-mêmes que les résultats varient fortement selon le matériel.
- La mise en cache réduit le coût d'une documentation relue. Anthropic propose une mise en cache des débuts de prompts identiques, qui réduit nettement le temps de traitement et le coût des contenus répétés (documentation Claude). Un design system chargé à chaque requête est typiquement ce genre de contenu.
- Les tokens lus pèsent moins que les tokens produits. Alléger la documentation réduit donc une partie de la consommation, pas l'essentiel.
L'argument environnemental est réel dans son principe, mais impossible à chiffrer pour un cas donné, et probablement secondaire. Le principal bénéfice de la concision reste la qualité des réponses.
Un exemple terrain : Miro
L'équipe design system de Miro (six personnes au service de plus de 48 équipes produit) a passé un an à rendre son design system exploitable par Claude. Leur retour d'expérience, présenté à l'AI Conference for Designers 2026, illustre les deux faces de la sobriété (Into Design Systems, 2026).
Côté réduction. L'outil de recherche d'icônes, conçu sous forme de skill Claude Code, est passé d'environ 33 000 tokens à environ 410, soit une baisse de 98 %.
Côté enrichissement. Le correctif qui a mis fin aux erreurs de Claude n'a pas consisté à couper, mais à ajouter : une description visuelle, un cas d'usage et une règle « ne pas utiliser pour » sur chaque icône et chaque token. Par exemple, un token de fond est désormais décrit comme réservé aux barres d'outils, panneaux et menus déroulants, interdit pour les cartes, avec l'alternative à utiliser à la place.
Un bon panneau routier ne décrit pas la ville : il dit « à gauche », « interdit aux camions », « déviation par ici ». Court, mais sans ambiguïté.
La leçon est donc plus fine que « écrire moins » : retirer ce qui ne décide rien, ajouter ce qui tranche.
Ce cas est rapporté par l'organisateur de la conférence, qui vend l'accès aux enregistrements, et non par une étude indépendante. Les chiffres sont déclarés par l'équipe elle-même. Enfin, les 98 % mesurent une économie de tokens sur un outil précis, pas un gain de qualité des interfaces produites.
Concision n'est pas pauvreté
Une documentation sobre n'est pas une documentation maigre. Elle garde tout ce qui aide Claude à décider, et retire tout ce qu'il sait déjà ou qui ne tranche rien.
Ce qui mérite sa place :
- L'intention : à quoi sert le composant ou le token.
- Les interdits : dans quels cas ne pas l'utiliser.
- L'alternative : quoi prendre à la place.
- Un exemple de référence plutôt qu'une liste de cas limites. Anthropic déconseille d'empiler les cas particuliers et recommande quelques exemples canoniques et variés (Anthropic, 2025).
Ce qui peut sortir :
- Les explications que Claude connaît déjà. Le guide d'Anthropic sur les skills part du principe que Claude est déjà très compétent, et invite à se demander pour chaque paragraphe s'il justifie son coût en tokens. Inutile d'expliquer ce qu'est un contraste ou une grille (documentation Claude).
- Les options multiples sans hiérarchie. Le même guide recommande de proposer une solution par défaut, avec une porte de sortie pour les cas particuliers, plutôt qu'une liste de choix équivalents.
- Les synonymes. « Bouton principal », « CTA » et « action primaire » pour la même chose : choisissez un terme et tenez-le partout.
Organiser plutôt que tout charger. Anthropic décrit un principe de « divulgation progressive » : un fichier d'entrée court sert de sommaire, et Claude ne lit les fichiers détaillés que lorsque la tâche l'exige. Les fichiers non lus ne consomment aucun token. Le guide recommande de garder le fichier principal sous 500 lignes et de ne pas imbriquer les renvois sur plus d'un niveau.Une bonne documentation ressemble à une cuisine de restaurant bien rangée : le plan de travail ne porte que les ustensiles du plat en cours, le reste attend dans des tiroirs étiquetés. Rien n'est jeté, tout est à portée de main.
Ces recommandations sont des bonnes pratiques publiées par Anthropic pour ses propres outils, pas des normes. Elles visent les skills, et nous les transposons au design system par analogie.
Méthode : cinq principes pour une documentation sobre
Ces principes sont notre synthèse des sources citées plus haut. Ce sont des bonnes pratiques, à valider sur chaque projet par des tests.
- Tester avant d'écrire. Soumettez à Claude quelques tâches réelles sans documentation, notez ses erreurs, puis écrivez juste ce qu'il faut pour les corriger. C'est la démarche que recommande Anthropic pour les skills : mesurer une base de référence, rédiger des instructions minimales, puis comparer (documentation Claude).
- Écrire chaque règle en trois temps : intention, interdit, alternative. C'est le format qui a corrigé les erreurs chez Miro.
- Éliminer les doublons et les règles quasi identiques. Deux règles presque semblables jouent le rôle des « distracteurs » étudiés dans le rapport Chroma. Fusionnez-les ou rendez leur différence explicite.
- Mettre l'essentiel en tête, le détail à part. Un fichier d'entrée court porte les règles critiques ; les spécifications détaillées vivent dans des fichiers séparés, chargés à la demande.
- Observer et élaguer. Regardez ce que Claude lit, ignore ou comprend de travers. Un contenu jamais consulté est peut-être inutile ; une règle souvent enfreinte est peut-être mal placée ou mal formulée.
Exemple de règle sobre, pour un bouton :
## Bouton principal
Usage : l'action la plus importante de l'écran. Un seul par vue.
Ne pas utiliser : pour une action destructrice (utiliser Bouton danger) ni pour une action secondaire (utiliser Bouton secondaire).
Accessibilité : libellé explicite, jamais « Cliquez ici » ; contraste texte/fond d'au moins 4,5:1.
Quatre lignes suffisent à trancher les cas courants. Le seuil de contraste de 4,5:1 pour un texte de taille normale est une exigence du critère 1.4.3 des WCAG 2.1, niveau AA (W3C), repris par le RGAA. Le reste de l'exemple relève de la bonne pratique.
Limites et points de vigilance
- Aucune étude ne mesure encore l'effet de la concision sur la qualité des interfaces générées. Les résultats cités portent sur des tâches de texte. Leur transposition au design system est plausible, pas démontrée.
- Trop couper est aussi un risque. Anthropic rappelle que minimal ne veut pas dire court : une consigne trop vague laisse Claude deviner. Le cas Miro montre même qu'il a fallu ajouter du texte pour corriger les erreurs.
- Les modèles progressent vite. Les fenêtres de contexte s'élargissent et la robustesse s'améliore. Les écarts mesurés en 2023 ou 2024 peuvent se réduire. Anthropic estime toutefois que la pollution du contexte restera un enjeu, quelle que soit la taille de la fenêtre.
- Chaque outil charge le contexte à sa manière. Claude Design, Claude Code ou un agent via l'API ne lisent pas la documentation de la même façon. La seule preuve valable reste le test sur votre propre configuration.
En conclusion, une documentation de design system destinée à Claude gagne à être pensée comme un briefing, pas comme une encyclopédie. La recherche montre qu'un contexte long ou bruité dégrade les réponses des modèles, et l'expérience de terrain montre qu'une règle claire vaut mieux qu'une page d'explications. L'objectif n'est pas d'écrire moins, mais d'écrire juste : chaque ligne doit aider Claude à choisir. Et comme aucune étude ne tranche encore pour les interfaces, le dernier mot revient au test.
Bibliographie
Publications scientifiques évaluées par des pairs
- Levy, M., Jacoby, A. et Goldberg, Y. (2024). Same Task, More Tokens: the Impact of Input Length on the Reasoning Performance of Large Language Models. Actes d'ACL 2024. aclanthology.org/2024.acl-long.818
- Liu, N. F., Lin, K., Hewitt, J., Paranjape, A., Bevilacqua, M., Petroni, F. et Liang, P. (2024). Lost in the Middle: How Language Models Use Long Contexts. Transactions of the Association for Computational Linguistics, 12, 157–173. aclanthology.org/2024.tacl-1.9
- Shi, F., Chen, X., Misra, K., Scales, N., Dohan, D., Chi, E., Schärli, N. et Zhou, D. (2023). Large Language Models Can Be Easily Distracted by Irrelevant Context. Actes d'ICML 2023. arxiv.org/abs/2302.00093
- Wilkins, G., Keshav, S. et Mortier, R. (2024). Offline Energy-Optimal LLM Serving: Workload-Based Energy Models for LLM Inference on Heterogeneous Systems. Atelier HotCarbon 2024. PDF
Rapports techniques et documentation officielle
- Anthropic (2025). Effective context engineering for AI agents. anthropic.com
- Anthropic. Skill authoring best practices. Documentation Claude, consultée le 29 septembre 2026. platform.claude.com
- Anthropic. Prompt caching. Documentation Claude, consultée le 29 septembre 2026. platform.claude.com
- Hong, K., Troynikov, A. et Huber, J. (2025). Context Rot: How Increasing Input Tokens Impacts LLM Performance. Rapport technique Chroma, non évalué par des pairs. research.trychroma.com
- W3C. Understanding Success Criterion 1.4.3: Contrast (Minimum). WCAG 2.1. w3.org
Retour d'expérience professionnel
- Bormüller, S. (2026). How Miro Made Their Design System AI-Ready with MCP and Claude Code Skills. Into Design Systems, compte rendu de conférence. intodesignsystems.com
