Brandrail, Brandrails ou Modern Web Guidance : garde-fous du code UI généré par IA pour votre design system
Brandrail, Brandrails et Modern Web Guidance protègent chacun un rail différent de l'UI générée par IA : la conformité à la marque, les design tokens et les règles des agents, et le code moderne de la plateforme web. Ce guide présente le modèle à trois rails, indique quel outil détecte quelle dérive, montre comment les intégrer comme points de contrôle en CI et précise ce que les données montrent, et ce qu'elles ne montrent pas.
Les équipes qui livrent de l'UI avec Claude Code, Cursor, Copilot ou Codex se retrouvent avec des écrans qui fonctionnent mais qui ne ressemblent pas à un seul et même produit. Le code sous-jacent est aussi souvent d'un style plus ancien que ce qu'écrirait aujourd'hui un développeur frontend senior.
Le modèle à trois rails : trois outils, trois niveaux de dérive de l'UI générée par IA
Le projet Brandrail résume clairement le problème de fond : les outils de code IA ne connaissent pas votre design system, si bien que chaque écran sort avec des couleurs, des boutons et des espacements différents. Nous découpons cette dérive selon ce que nous appelons le modèle à trois rails : un rail marque, un rail tokens et un rail plateforme. Chacun des outils présentés ici se concentre sur l'un d'eux.
Rail marque. Brandrail (brandrail-app/brandrail) est un serveur MCP. Il transmet à l'agent votre Brand Kit et vos composants avant qu'il n'écrive l'UI, puis vérifie le résultat et renvoie des corrections pour que l'agent puisse se corriger lui-même.
Rail tokens. Brandrails (matejholek/brandrails) est un outil distinct dont les fichiers d'agent toujours chargés, comme AGENTS.md et les instructions Copilot, ne listent que les noms des tokens et renvoient vers design/tokens.md, afin qu'un design system volumineux n'accapare pas la fenêtre de contexte.
Rail plateforme. Modern Web Guidance s'attaque à un autre type d'échec. Ses mainteneurs soulignent que les agents de code se rabattent souvent sur des pratiques anciennes, car les données d'entraînement des LLM contiennent d'énormes quantités de code legacy. Un bouton peut correspondre parfaitement à votre marque tout en utilisant une pratique que la plateforme web a remplacée depuis des années.
Une remarque sur les noms : Brandrail et Brandrails se confondent facilement, nous conseillons donc d'installer chacun à partir de l'URL exacte de son dépôt.
| Outil | Rail | Quand il intervient | Où il s'exécute | Licence ou gouvernance |
|---|---|---|---|---|
| Brandrail (brandrail-app/brandrail) | Marque : Brand Kit et composants | Avant la génération (contexte) et après (validation) | Serveur MCP local via stdio et vérificateur en CLI, plus un service de compte hébergé | MIT, selon la couverture tierce de Tech Bytes |
| Brandrails (matejholek/brandrails) | Tokens et fichiers d'instructions d'agent allégés | Avant la génération (fichiers d'agent) | Dans votre dépôt | Vérifiez le dépôt avant de l'adopter |
| Modern Web Guidance | Code web moderne et fondé sur les standards | Avant la génération (recommandations pour l'agent) | Dans le contexte de travail de l'agent | Piloté par les équipes Chrome, Edge, Firefox et MDN avec la communauté |
Quel rail détecte quelle dérive
La matrice ci-dessous reflète notre propre lecture de l'objectif déclaré de chaque projet, et non une comparaison mesurée. Aucune colonne ne couvre entièrement l'accessibilité ni le comportement multinavigateur : nous conseillons donc de confier ces vérifications à des personnes.
| Type de dérive | Rail marque (Brandrail) | Rail tokens (Brandrails) | Rail plateforme (Modern Web Guidance) |
|---|---|---|---|
| Couleurs, typographie ou composants hors charte | Principal | Partiel | Non |
| Valeurs codées en dur au lieu de tokens | Partiel | Partiel (agents orientés vers les tokens) | Non |
| L'agent ne voit jamais vos règles | Partiel (contexte MCP) | Principal (fichiers allégés toujours chargés) | Non |
| Pratiques legacy, comme des infobulles en JavaScript sur mesure | Non | Non | Principal |
| Sémantique, formulaires et accessibilité | Non | Non | Partiel |
| Comportement multinavigateur | Non | Non | Pas fiable |
Brandrail : le contexte de marque en entrée, un score de marque en sortie
Brandrail fonctionne en boucle. Avant la génération, son serveur MCP transmet à l'agent votre Brand Kit et vos composants comme contexte, de sorte que la première version parte de vos règles plutôt que des choix par défaut du modèle. Après la génération, la validation passe par un outil appelé validate_snippet. Selon sa description publiée, il renvoie un score de marque et liste chaque violation accompagnée de sa correction.
L'usage prévu est précis : l'appeler une fois après avoir écrit l'UI, lui transmettre tous les fichiers modifiés, et corriger chaque erreur et chaque avertissement avant de terminer. Un agent qui ne transmet que le dernier fichier modifié obtiendra un score flatteur. Nous conseillons de considérer le score de marque comme un signal parmi d'autres, avec des vérifications distinctes pour l'accessibilité, la mise en page et la qualité du code.
Côté distribution, la couverture tierce de Tech Bytes indique que Brandrail fournit un paquet sous licence MIT comprenant un serveur MCP local, un vérificateur autonome en CLI et un moteur de règles en TypeScript pur sans dépendances d'exécution. Le vérificateur en CLI compte, car un outil MCP ne s'exécute que lorsque l'agent décide de l'appeler, alors qu'une étape CLI en CI s'exécute à chaque pull request.
Ce que Brandrail garde en local et ce qui passe par son service hébergé
Les équipes sécurité, juridique et achats demanderont toutes où va le code. Pour la partie vérification, le dépôt de Brandrail est clair : le serveur s'exécute en local via stdio, et le code est vérifié sur votre machine sans jamais être envoyé.
Brandrail propose aussi un service hébergé avec comptes et clés d'API. Sa page sécurité décrit ce volet :
- Clés d'API : seul un hachage SHA-256 est stocké. Les clés ont une portée limitée, expirent au bout de 90 jours et indiquent leur dernière utilisation, et la révocation d'une clé prend effet immédiatement.
- Chiffrement : les données en transit utilisent partout TLS 1.2 ou supérieur, avec HSTS activé. Le fournisseur de base de données de Brandrail chiffre les données au repos en AES-256.
- Certification : interrogé sur une certification formelle, Brandrail répond « Not yet. » (pas encore). L'éditeur propose de remplir des questionnaires de sécurité et peut signer un accord de traitement des données.
Profitez de cette offre de questionnaire et d'accord de traitement des données pour obtenir une confirmation écrite de la manière dont les données du compte hébergé et du Brand Kit sont traitées. Vérifiez ensuite vous-même l'affirmation selon laquelle tout reste en local en observant le trafic réseau pendant une vérification locale, avec la même rigueur que pour n'importe quel outil de développement.
Brandrails : des fichiers d'agent allégés qui renvoient vers vos tokens
Brandrails garde les fichiers toujours chargés de petite taille : AGENTS.md et les instructions Copilot ne listent que les noms des tokens et renvoient vers design/tokens.md. Ainsi, un design system volumineux n'évince pas le reste du contexte de l'agent.
Pour le fichier de tokens lui-même, un format partagé peut être utile aux équipes. Le Design Tokens W3C Community Group se présente comme une communauté de designers, de développeurs et d'éditeurs d'outils qui standardise la manière dont les design tokens sont définis et échangés. Nous conseillons de vérifier comment Brandrails attend que les tokens soient structurés avant d'arrêter un format, et de privilégier un format standard lorsque vos outils le permettent, afin que le même fichier puisse alimenter d'autres outils.
Nous conseillons aussi d'ajouter, au moment de la pull request, une vérification de dérive des tokens qui signale les valeurs codées en dur qui auraient dû être des tokens. Les fichiers d'agent allégés guident l'agent avant la génération, et une vérification en CI renforce ces consignes par une étape que l'agent ne peut pas contourner.
DesignSystems.one affirme que Claude Code ne lit pas AGENTS.md et qualifie cette idée reçue d'erreur la plus courante de la catégorie. DesignSystems.one ajoute que l'idée selon laquelle AGENTS.md aurait supplanté CLAUDE.md n'est pas confirmée par le nombre de fichiers, et que CLAUDE.md est en tête. Les deux conventions étant largement utilisées, nous conseillons de prendre en charge les deux par défaut.
Modern Web Guidance : empêcher les agents d'écrire du code web legacy
Modern Web Guidance est piloté par les équipes Google Chrome, Microsoft Edge, Mozilla Firefox et MDN, aux côtés de la communauté du développement web. Les chiffres d'évaluation et les résultats des adoptants ci-dessous proviennent de la documentation et du blog de Chrome : nous les considérons donc comme déclarés par l'éditeur, Search Engine Journal servant de principale vérification indépendante.
Sur le tableau de bord d'évaluation de Chrome, les agents guidés atteignent un taux de réussite de 91%, contre environ 51% pour les modèles de pointe non guidés. Lorsque Search Engine Journal a consulté ce tableau de bord, il a relevé 88% avec guidage contre 56% sans.
Le blog Chrome met aussi en avant trois adoptants :
- note inc. : le taux de réussite aux vérifications web modernes est passé de 61% à 94% sur 180 exécutions. Les gains viennent du fait d'orienter les agents vers les fonctionnalités natives HTML et CSS plutôt que vers du JavaScript sur mesure pour les animations au défilement, les infobulles et les accordéons.
- WeTV : le temps de débogage et de résolution a baissé de 87%, passant de quatre heures à 30 minutes. L'agent diagnostiquerait et corrigerait automatiquement 90% des vérifications de performance en échec, et le chiffre de quatre heures à 30 minutes inclut l'évaluation manuelle.
- MetaMask : un bot de revue a examiné environ 480 PR, a commenté 64 d'entre elles et a vu 43 de ses remarques corrigées. La plupart concernaient l'accessibilité, la sémantique HTML et les formulaires, des problèmes que les linters ne détectent pas, avec un délai médian de 15 minutes entre le commentaire et la correction.
Search Engine Journal a par ailleurs rapporté que le bot de MetaMask a signalé 102 problèmes sur 57 PR de fonctionnalités et de correctifs au cours de ses cinq premières semaines.
Le test de LogRocket illustre le type d'erreur ciblé, avec une interaction de filtrage en React où la mémoïsation semble être la solution évidente. Comme l'explique LogRocket, useMemo évite des recalculs inutiles d'un rendu à l'autre, mais ne rend pas le filtrage non bloquant, et c'est précisément ce qui compte pour l'Interaction to Next Paint (INP). Nous conseillons de lire l'exemple de LogRocket comme une illustration de l'échec plutôt que comme une preuve de la correction.
Comment combiner les trois outils : un guide pratique de design ops
Le modèle fonctionne au mieux lorsque chaque rail a une seule mission et un seul responsable, et lorsque l'application des règles ne dépend pas de la mémoire de l'agent quant à ses instructions.
Étape 1 : faire du fichier de tokens la source de vérité
Définissez ou exportez les tokens dans un fichier unique, idéalement dans un format standard comme DTCG, et versionnez-le avec un responsable nommément désigné. Faites pointer les fichiers d'agent allégés vers ce fichier, selon le modèle utilisé par Brandrails. Vérifiez avant le pilote si Brandrail peut importer directement votre fichier de tokens. Si ce n'est pas le cas, mettez à jour le Brand Kit dans la même modification que les tokens et confiez les deux au responsable des tokens.
Étape 2 : garder des fichiers d'agent allégés et couvrir chaque agent
Les fichiers toujours chargés doivent contenir les noms des tokens et un renvoi vers la référence complète des tokens, selon le modèle utilisé par Brandrails. Comme Claude Code ne lit pas AGENTS.md, associez l'AGENTS.md allégé à un CLAUDE.md qui l'importe. Tous les agents travaillent alors à partir des mêmes règles.
Étape 3 : ajouter les recommandations de plateforme
Installez Modern Web Guidance pour chaque agent utilisé, afin que les agents privilégient le HTML et le CSS natifs plutôt que du JavaScript sur mesure pour des motifs courants comme les infobulles, les accordéons et les animations au défilement.
Étape 4 : boucler la boucle de génération
Connectez le serveur MCP local de Brandrail pour que l'agent reçoive d'abord le Brand Kit, et intégrez validate_snippet à la définition de « terminé » : un seul appel, tous les fichiers modifiés, chaque erreur et chaque avertissement corrigés.
Étape 5 : contrôler au niveau de la pull request
Exécutez les vérificateurs en CI pour retirer l'application des règles des mains de l'agent, mais ne rendez pas tout bloquant dès le premier jour.
- Vérification de dérive des tokens : bloquante. Une valeur correspond à un token ou non. Nous conseillons de l'appliquer dès le départ aux lignes modifiées, avec l'outil de lint de tokens que votre stack prend en charge.
- Vérificateur CLI de Brandrail : consultatif dans un premier temps. Pendant le pilote, enregistrez les scores de marque par PR sans bloquer. Une fois une référence établie, bloquez sur les erreurs et laissez les avertissements en consultatif. Fixez un éventuel score de marque minimal à partir des données de votre propre pilote.
- Faux positifs. N'autorisez les exceptions qu'avec une justification écrite et un approbateur nommément désigné. Si une règle se déclenche à tort de façon répétée, corrigez le token ou la règle plutôt que de la désactiver une fois de plus.
- Bot de revue : consultatif. Un bot comme celui de MetaMask peut signaler des problèmes de sémantique, de formulaires et d'accessibilité, pendant que des personnes décident de ce qu'il faut corriger.
Étape 6 : confier l'accessibilité à des personnes
Étape 7 : mesurer le coût et la latence
Les exécutions avec Modern Web Guidance activé étaient généralement plus lentes et consommaient davantage de tokens. Mesurez la consommation de tokens et la durée d'exécution avant et après le pilote.
Erreurs courantes avec les garde-fous du code UI généré par IA
Considérer un design system prêt pour les agents comme une garantie. DesignSystems.one rapporte que le propre design system de Meta, Astryx, a obtenu un score global de 87 sur le benchmark nocturne de Meta, en dessous d'une simple référence shadcn/ui. Lisez ce résultat comme une tendance plutôt que comme une mesure d'ampleur, et conservez des points de contrôle en CI sur l'UI générée, même lorsqu'un design system est présenté comme prêt pour les agents.
Confondre conformité à la marque et accessibilité. Une étude présentée comme publiée à CHI 2026 a relevé 541 problèmes sur 300 interfaces générées, soit environ 1.8 par UI, principalement des libellés de boutons génériques, des textes de liens vagues et des textes alternatifs médiocres, suivis de problèmes d'ARIA et de libellés de formulaires. Nous n'avons pas pu confirmer le titre ni les auteurs de l'article, ce qui rend ces chiffres indicatifs plutôt que définitifs, et aucun de ces types de problèmes ne relève de ce que vérifie un score de marque.
Mises en garde : ce que les données montrent et ce qu'elles ne montrent pas
La plupart des chiffres de Modern Web Guidance proviennent de Chrome. Le chiffre phare de 91% vient du tableau de bord de Chrome, et les résultats des adoptants viennent d'entreprises que Chrome a choisi de mettre en avant. Le relevé distinct de Search Engine Journal, évoqué plus haut, montrait un écart plus réduit. Les deux vont dans le même sens, mais l'ampleur de l'effet dépend du moment et de la méthode de mesure, c'est pourquoi les scores de benchmark nécessitent un protocole d'évaluation explicite avant toute comparaison.
Les recommandations ne remplacent pas les tests. Dans une revue publiée, le consultant en accessibilité Adrian Roselli a constaté que le code produit par la version préliminaire n'était pas conforme aux WCAG et que son animation ne fonctionnait pas dans Firefox.
Considérez les affirmations sur Brandrail et Brandrails comme non vérifiées tant que vous ne les avez pas testées. Ce que cet article dit des deux projets provient de leur documentation et de comptes rendus tiers : nous conseillons donc de valider leur comportement sur votre propre base de code pendant le pilote.
Les fichiers d'instructions et les noms diffèrent selon les agents et les projets. Selon DesignSystems.one, Claude Code ne lit pas AGENTS.md. Avant de standardiser, vérifiez à nouveau quels fichiers d'instructions chacun de vos agents charge et confirmez chaque URL de dépôt.
Points clés
- Le modèle à trois rails découpe la dérive de l'UI générée par IA en marque, tokens et règles, et plateforme. Brandrail, Brandrails et Modern Web Guidance se concentrent chacun sur un rail.
- Faites d'un fichier de tokens unique la source de vérité et dérivez-en le Brand Kit de Brandrail, ce qui évite que les vérifications signalent des violations contradictoires.
- Rendez tôt bloquante une vérification de dérive des tokens, et exécutez le vérificateur CLI de Brandrail en mode consultatif jusqu'à ce que les données du pilote fournissent un score de marque de référence.
- Brandrail affirme que le code est vérifié en local et jamais envoyé. L'outil n'est pas encore certifié : faites confirmer par écrit le traitement des données du compte hébergé et du Brand Kit.
- Claude Code ne lit pas AGENTS.md nativement. Associez un AGENTS.md allégé à un CLAUDE.md qui l'importe.
- Chrome annonce 91% avec guidage contre environ 51% sans. Le relevé distinct de Search Engine Journal montrait 88% contre 56%, un écart plus réduit.
- Aucun rail ne couvre à lui seul l'accessibilité ni le comportement multinavigateur, et les exécutions guidées coûtent généralement plus de tokens et de temps.
Conclusion
Pour un premier pilote, choisissez un périmètre produit et attribuez un responsable à chaque rail. Notez les URL exactes des dépôts de Brandrail et de Brandrails, faites d'un fichier de tokens unique la source de vérité et gardez des fichiers d'agent toujours chargés allégés, avec un CLAUDE.md aux côtés de l'AGENTS.md allégé. Rendez bloquante une vérification de dérive des tokens sur les lignes modifiées, exécutez le vérificateur CLI de Brandrail en mode consultatif jusqu'à disposer d'une référence, et vérifiez le périmètre des données de Brandrail par une analyse réseau lors d'une exécution locale. Mesurez la consommation de tokens et la durée d'exécution avant et après l'activation de Modern Web Guidance, et traitez les chiffres déclarés par les éditeurs comme une hypothèse à tester sur votre propre base de code. Confiez du début à la fin la revue d'accessibilité et multinavigateur à des personnes.
À lire aussi sur Optijara : Playwright et axe sur des états réels de l'UI et Le traçage GenAI OpenTelemetry pour les exécutions d'agents.
Questions fréquentes
Que sont les garde-fous du code UI généré par IA ?
Ce sont des outils et des vérifications qui maintiennent l'UI générée par des agents de code comme Claude Code, Cursor, Copilot ou Codex en cohérence avec votre design system et les pratiques web actuelles. Dans le modèle à trois rails utilisé ici, Brandrail couvre le rail marque, Brandrails couvre les design tokens et les fichiers d'instructions d'agent allégés, et Modern Web Guidance couvre le rail plateforme.
Brandrail et Brandrails sont-ils le même projet ?
Non. Brandrail (github.com/brandrail-app/brandrail) est un serveur MCP et un vérificateur qui transmet votre Brand Kit aux agents et renvoie un score de marque. Brandrails (github.com/matejholek/brandrails) est un outil distinct dont les fichiers d'agent toujours chargés ne listent que les noms des tokens et renvoient vers une référence de tokens plus complète. Référencez-les et installez-les toujours à partir de l'URL exacte du dépôt.
Si Brandrail et Brandrails se contredisent, lequel l'emporte ?
Tranchez cette question avant le pilote. Une règle pratique consiste à faire du fichier de tokens de votre dépôt la source de vérité et à en dériver le Brand Kit de Brandrail. Si le Brand Kit ne peut pas être généré à partir des tokens, mettez-le à jour dans la même modification et confiez les deux à un seul responsable.
Brandrail envoie-t-il mon code source ?
Brandrail indique que son serveur MCP s'exécute en local via stdio et que le code est vérifié sur votre machine sans jamais être envoyé. Le service de compte hébergé est une question distincte. Consultez la section sur ce que Brandrail garde en local pour savoir quoi faire confirmer par écrit et comment vérifier ce périmètre par une analyse réseau.
Claude Code lit-il AGENTS.md, ou faut-il aussi un CLAUDE.md ?
Claude Code ne lit pas AGENTS.md nativement. Il vous faut un CLAUDE.md qui importe ou reprend ces règles. DesignSystems.one rapporte que le nombre de fichiers ne confirme pas l'idée selon laquelle AGENTS.md aurait supplanté CLAUDE.md : nous conseillons donc de prendre en charge les deux par défaut.
Faut-il les trois outils, ou par lequel une équipe doit-elle commencer ?
Commencez par le rail d'où provient votre dérive. Si les écrans générés ignorent vos couleurs et vos espacements, commencez par le rail tokens (Brandrails) ou le rail marque (Brandrail). Si le code fonctionne mais repose sur des pratiques dépassées, commencez par Modern Web Guidance. Beaucoup d'équipes finiront par les combiner, mais piloter d'abord un seul rail permet de mesurer plus facilement l'effet.
Modern Web Guidance rend-il à lui seul l'UI générée par IA accessible et compatible avec tous les navigateurs ?
Non. Il relève le niveau de base du code généré, mais l'accessibilité et la compatibilité multinavigateur doivent toujours être testées. Une revue indépendante de la version préliminaire a relevé des problèmes dans ces deux domaines. Conservez dans le pipeline des tests d'accessibilité automatisés et une revue multinavigateur humaine.
Sources
- https://github.com/brandrail-app/brandrail
- https://www.brandrail.com.au/security
- https://glama.ai/mcp/connectors/au.com.brandrail/brandrail/tools/validate_snippet
- https://techbytes.app/posts/brandrail-make-claude-code-and-cursor-follow-your-design-system/
- https://github.com/matejholek/brandrails
- https://www.designtokens.org/
- https://www.designsystems.one/ai-ready/agent-files
- https://developer.chrome.com/docs/modern-web-guidance
- https://developer.chrome.com/blog/modern-web-guidance-v1
- https://github.com/GoogleChrome/modern-web-guidance
- https://blog.logrocket.com/chromes-modern-web-guidance-prevent-ai-coding-agents/
- https://www.searchenginejournal.com/google-releases-modern-web-guidance-1-0-for-ai-coding-agents/596495/



