Brandrail vs Brandrails vs Modern Web Guidance: guardrails de código de UI com IA para seu design system
Brandrail, Brandrails e Modern Web Guidance protegem, cada um, um trilho diferente da UI gerada por IA: conformidade com a marca, design tokens e regras para agentes, e código moderno da plataforma web. Este guia apresenta o Modelo de Três Trilhos, mostra qual ferramenta detecta qual desvio e como colocá-las como gates no CI, e expõe o que as evidências mostram e o que não mostram.
Equipes que entregam UI com Claude Code, Cursor, Copilot ou Codex acabam com telas que funcionam, mas não parecem pertencer a um mesmo produto. O código por trás delas também costuma ter um estilo mais antigo do que o que um engenheiro frontend sênior escreveria hoje.
O Modelo de Três Trilhos: três ferramentas, três camadas de desvio na UI gerada por IA
O projeto Brandrail descreve o problema central sem rodeios: as ferramentas de programação com IA não conhecem seu design system, então cada tela sai com cores, botões e espaçamentos diferentes. Dividimos esse desvio no que chamamos de Modelo de Três Trilhos: um trilho de marca, um trilho de tokens e um trilho de plataforma. Cada ferramenta aqui se concentra em um deles.
Trilho de marca. O Brandrail (brandrail-app/brandrail) é um servidor MCP. Ele entrega ao agente seu Brand Kit e seus componentes antes que ele escreva a UI, depois verifica o resultado e devolve correções para que o agente possa se corrigir.
Trilho de tokens. O Brandrails (matejholek/brandrails) é uma ferramenta separada cujos arquivos de agente sempre carregados, como o AGENTS.md e as instruções do Copilot, listam apenas os nomes dos tokens e apontam para design/tokens.md, para que um design system grande não consuma a janela de contexto.
Trilho de plataforma. O Modern Web Guidance ataca outra falha. Seus mantenedores observam que os agentes de programação frequentemente recorrem a padrões antigos porque os dados de treinamento dos LLMs contêm uma quantidade enorme de código legado. Um botão pode combinar perfeitamente com sua marca e ainda assim usar um padrão que a plataforma web substituiu há anos.
Uma observação sobre os nomes: Brandrail e Brandrails são fáceis de confundir, por isso sugerimos instalar cada um a partir da URL exata do seu repositório.
| Ferramenta | Trilho | Quando atua | Onde roda | Licença ou governança |
|---|---|---|---|---|
| Brandrail (brandrail-app/brandrail) | Marca: Brand Kit e componentes | Antes da geração (contexto) e depois (validação) | Servidor MCP local via stdio e um verificador CLI, além de um serviço de contas hospedado | MIT, segundo cobertura de terceiros da Tech Bytes |
| Brandrails (matejholek/brandrails) | Tokens e arquivos de instrução enxutos para agentes | Antes da geração (arquivos de agente) | No seu repositório | Verifique o repositório antes de adotar |
| Modern Web Guidance | Código web moderno e baseado em padrões | Antes da geração (orientação ao agente) | No contexto de trabalho do agente | Mantido pelas equipes do Chrome, Edge, Firefox e MDN junto com a comunidade |
Qual trilho detecta qual desvio
A matriz abaixo é a nossa própria leitura do foco declarado de cada projeto, não uma comparação medida. Nenhuma coluna cobre totalmente acessibilidade ou comportamento entre navegadores, então sugerimos manter essas verificações com pessoas.
| Tipo de desvio | Trilho de marca (Brandrail) | Trilho de tokens (Brandrails) | Trilho de plataforma (Modern Web Guidance) |
|---|---|---|---|
| Cores, tipografia ou componentes fora da marca | Principal | Parcial | Não |
| Valores fixos no código em vez de tokens | Parcial | Parcial (agentes direcionados aos tokens) | Não |
| O agente nunca vê suas regras | Parcial (contexto MCP) | Principal (arquivos enxutos sempre carregados) | Não |
| Padrões legados, como tooltips customizados em JavaScript | Não | Não | Principal |
| Semântica, formulários e acessibilidade | Não | Não | Parcial |
| Comportamento entre navegadores | Não | Não | Não confiável |
Brandrail: contexto de marca na entrada, pontuação de marca na saída
O Brandrail funciona como um ciclo. Antes da geração, seu servidor MCP envia ao agente o Brand Kit e os componentes como contexto, para que o primeiro rascunho parta das suas regras e não dos padrões do modelo. Depois da geração, a validação passa por uma ferramenta chamada validate_snippet. Segundo sua descrição publicada, ela retorna uma pontuação de marca e lista cada violação junto com a respectiva correção.
O uso previsto é específico: chamá-la uma vez depois de escrever a UI, passar todos os arquivos alterados e corrigir todos os erros e avisos antes de concluir. Um agente que passa apenas o último arquivo que tocou vai receber uma pontuação lisonjeira. Sugerimos tratar a pontuação de marca como um sinal entre vários, com verificações separadas para acessibilidade, layout e qualidade de código.
Quanto ao empacotamento, a cobertura de terceiros da Tech Bytes informa que o Brandrail distribui um pacote com licença MIT que inclui um servidor MCP local, um verificador CLI independente e um motor de regras em TypeScript puro, sem dependências de runtime. O verificador CLI é importante porque uma ferramenta MCP só roda quando o agente decide chamá-la, enquanto uma etapa CLI no CI roda em todo pull request.
O que o Brandrail mantém local e o que passa pelo serviço hospedado
As áreas de segurança, jurídico e compras vão todas perguntar para onde vai o código. No caminho de verificação, o repositório do Brandrail é claro: o servidor roda localmente via stdio, e o código é verificado na sua máquina e nunca é enviado.
O Brandrail também opera um serviço hospedado com contas e chaves de API. Sua página de segurança descreve esse lado:
- Chaves de API: apenas um hash SHA-256 é armazenado. As chaves têm escopo definido, expiram após 90 dias e mostram quando foram usadas pela última vez, e a revogação tem efeito imediato.
- Criptografia: os dados em trânsito usam TLS 1.2 ou superior em todos os pontos, com HSTS ativado. O provedor de banco de dados do Brandrail criptografa os dados em repouso com AES-256.
- Certificação: questionado sobre certificação formal, o Brandrail responde "Ainda não". A empresa se oferece para preencher questionários de segurança e pode assinar um acordo de processamento de dados.
Use a oferta de questionário e de acordo de processamento de dados para obter confirmação por escrito de como os dados da conta hospedada e do Brand Kit são tratados. Depois, verifique você mesmo a afirmação de processamento apenas local observando o tráfego de rede durante uma verificação local, a mesma diligência que você aplicaria a qualquer ferramenta de desenvolvimento.
Brandrails: arquivos de agente enxutos que apontam para seus tokens
O Brandrails mantém pequenos os arquivos sempre carregados: o AGENTS.md e as instruções do Copilot listam apenas os nomes dos tokens e apontam para design/tokens.md. Assim, um design system grande não ocupa o espaço do restante do contexto do agente.
Para o arquivo de tokens em si, as equipes podem achar útil um formato compartilhado. O Design Tokens W3C Community Group se descreve como uma comunidade de designers, desenvolvedores e fornecedores de ferramentas que padroniza como os design tokens são definidos e trocados. Sugerimos verificar como o Brandrails espera que os tokens sejam estruturados antes de escolher um formato, e preferir um formato padrão quando suas ferramentas permitirem, para que o mesmo arquivo possa alimentar outras ferramentas.
Também sugerimos adicionar uma verificação de desvio de tokens no momento do pull request que sinalize valores fixos no código que deveriam ter sido tokens. Arquivos de agente enxutos orientam o agente antes da geração, e uma verificação no CI reforça essa orientação com uma etapa que o agente não consegue pular.
O DesignSystems.one afirma que o Claude Code não lê o AGENTS.md e chama isso de a suposição equivocada mais comum da categoria. O DesignSystems.one também diz que a narrativa de que o AGENTS.md substituiu o CLAUDE.md não é sustentada pela contagem de arquivos, e que o CLAUDE.md está à frente. Com as duas convenções amplamente usadas, sugerimos dar suporte a ambas como padrão.
Modern Web Guidance: impedindo que agentes escrevam código web legado
O Modern Web Guidance é mantido pelas equipes do Google Chrome, Microsoft Edge, Mozilla Firefox e MDN, junto com a comunidade de desenvolvimento web. Os números de avaliação e os resultados de adotantes abaixo vêm da documentação e do blog do Chrome, então os tratamos como dados informados pelo fornecedor, tendo o Search Engine Journal como principal verificação independente.
No painel de avaliações do Chrome, agentes orientados atingem uma taxa de aprovação de 91%, contra cerca de 51% para modelos de fronteira sem orientação. Quando o Search Engine Journal consultou o painel, registrou 88% com orientação contra 56% sem orientação.
O blog do Chrome também destaca três adotantes:
- note inc.: a taxa de aprovação nas verificações de web moderna subiu de 61% para 94% ao longo de 180 execuções. Os ganhos vieram de direcionar os agentes para recursos nativos de HTML e CSS em vez de JavaScript customizado para animações de rolagem, tooltips e acordeões.
- WeTV: o tempo de depuração e resolução caiu 87%, de quatro horas para 30 minutos. Segundo o relato, o agente diagnostica e corrige automaticamente 90% das verificações de desempenho que falham, e o número de quatro horas para 30 minutos inclui avaliação manual.
- MetaMask: um bot de revisão analisou cerca de 480 PRs, comentou em 64 e teve 43 apontamentos corrigidos. A maioria dos apontamentos envolvia acessibilidade, semântica HTML e problemas de formulários que os linters não detectam, com uma mediana de 15 minutos entre o comentário e a correção.
O Search Engine Journal informou separadamente que o bot da MetaMask sinalizou 102 problemas em 57 PRs de funcionalidades e correções nas suas primeiras cinco semanas.
O teste da LogRocket mostra o tipo de erro que o pacote tenta evitar, usando uma interação de filtragem em React na qual a memoização parece a correção óbvia. Como a LogRocket explica, o useMemo evita recálculos desnecessários entre renderizações, mas não torna a filtragem não bloqueante, e é isso que importa para o Interaction to Next Paint (INP). Sugerimos ler o exemplo da LogRocket como ilustração da falha, e não como evidência da correção.
Como combinar as três ferramentas: um playbook de design ops
O modelo funciona melhor quando cada trilho tem uma função e um responsável, e quando a aplicação das regras não depende de o agente lembrar das instruções.
Passo 1: torne o arquivo de tokens a fonte da verdade
Defina ou exporte os tokens em um único arquivo, de preferência em um formato padrão como o DTCG, e faça o commit com um responsável nomeado. Aponte os arquivos de agente enxutos para esse arquivo, o padrão que o Brandrails usa. Confirme antes do piloto se o Brandrail consegue importar seu arquivo de tokens diretamente. Se não conseguir, atualize o Brand Kit na mesma alteração que os tokens e torne o responsável pelos tokens responsável por ambos.
Passo 2: mantenha os arquivos de agente enxutos e cubra todos os agentes
Os arquivos sempre carregados devem conter os nomes dos tokens mais um ponteiro para a referência completa de tokens, o padrão que o Brandrails usa. Como o Claude Code não lê o AGENTS.md, combine o AGENTS.md enxuto com um CLAUDE.md que o importe. Assim, todos os agentes trabalham com as mesmas regras.
Passo 3: adicione orientação de plataforma
Instale o Modern Web Guidance para cada agente em uso, para que os agentes prefiram HTML e CSS nativos em vez de JavaScript customizado para padrões comuns como tooltips, acordeões e animações de rolagem.
Passo 4: feche o ciclo de geração
Conecte o servidor MCP local do Brandrail para que o agente receba o Brand Kit primeiro, e torne o validate_snippet parte da definição de pronto: uma chamada, todos os arquivos alterados, todos os erros e avisos corrigidos.
Passo 5: crie o gate no pull request
Rode os verificadores no CI para tirar a aplicação das regras das mãos do agente, mas não torne tudo bloqueante no primeiro dia.
- Verificação de desvio de tokens: bloqueante. Um valor corresponde a um token ou não. Sugerimos aplicá-la nas linhas alteradas desde o início, usando o linting de tokens que sua stack suportar.
- Verificador CLI do Brandrail: consultivo no início. Durante o piloto, registre as pontuações de marca por PR sem bloquear. Quando tiver uma linha de base, bloqueie em caso de erros e mantenha os avisos como consultivos. Defina qualquer pontuação mínima de marca a partir dos dados do seu próprio piloto.
- Falsos positivos. Permita exceções apenas com uma justificativa por escrito e um aprovador nomeado. Se uma regra continuar disparando de forma errada, corrija o token ou a regra em vez de suprimi-la de novo.
- Bot de revisão: consultivo. Um bot como o da MetaMask pode sinalizar problemas de semântica, formulários e acessibilidade enquanto pessoas decidem o que corrigir.
Passo 6: mantenha pessoas cuidando da acessibilidade
Passo 7: meça custo e latência
As execuções com o Modern Web Guidance ativado geralmente foram mais lentas e usaram mais tokens. Meça o uso de tokens e o tempo de execução antes e depois do piloto.
Erros comuns com guardrails de código de UI com IA
Tratar um design system pronto para agentes como garantia. O DesignSystems.one relata que o design system Astryx, da própria Meta, obteve 87 no geral no benchmark noturno da Meta, abaixo de uma linha de base simples com shadcn/ui. Leia o resultado como indicação de direção e não de magnitude, e mantenha gates de CI na UI gerada mesmo quando um design system for descrito como pronto para agentes.
Confundir conformidade com a marca e acessibilidade. Um estudo apresentado, segundo relatos, na CHI 2026 encontrou 541 problemas em 300 interfaces geradas, cerca de 1.8 por UI, liderados por rótulos de botão genéricos, textos de link vagos e textos alternativos ruins, seguidos de problemas de ARIA e de rótulos de formulário. Não conseguimos confirmar o título nem os autores do artigo, o que torna os números indicativos e não definitivos, e nenhum desses tipos de problema está dentro do que uma pontuação de marca verifica.
Ressalvas: o que as evidências mostram e o que não mostram
A maioria dos números do Modern Web Guidance vem do Chrome. O destaque de 91% vem do painel do Chrome, e os resultados de adotantes vêm de empresas que o Chrome escolheu destacar. O levantamento separado do Search Engine Journal, mencionado acima, mostrou uma diferença menor. Ambos apontam na mesma direção, mas o tamanho do efeito depende de quando e como você mede, e é por isso que pontuações de benchmark precisam de um protocolo de avaliação declarado antes de serem comparadas.
Orientação não substitui testes. Em uma análise publicada, o consultor de acessibilidade Adrian Roselli constatou que o resultado da versão preview não estava em conformidade com as WCAG e que sua animação não funcionava no Firefox.
Trate as afirmações sobre Brandrail e Brandrails como não testadas até que você as teste. O que este artigo diz sobre os dois projetos vem da documentação dos projetos e de análises de terceiros, então sugerimos validar o comportamento deles na sua própria base de código durante o piloto.
Arquivos de instrução e nomes variam entre agentes e projetos. Segundo o DesignSystems.one, o Claude Code não lê o AGENTS.md. Antes de padronizar, confira novamente quais arquivos de instrução cada um dos seus agentes carrega e confirme cada URL de repositório.
Pontos principais
- O Modelo de Três Trilhos divide o desvio da UI gerada por IA em marca, tokens e regras, e plataforma. Brandrail, Brandrails e Modern Web Guidance focam, cada um, em um trilho.
- Torne um único arquivo de tokens a fonte da verdade e derive dele o Brand Kit do Brandrail, o que evita que as verificações apontem violações conflitantes.
- Torne bloqueante desde cedo uma verificação de desvio de tokens e rode o verificador CLI do Brandrail como consultivo até que os dados do piloto deem uma pontuação de marca de base.
- O Brandrail diz que o código é verificado localmente e nunca enviado. Ele ainda não tem certificação, então confirme por escrito como os dados da conta hospedada e do Brand Kit são tratados.
- O Claude Code não lê o AGENTS.md nativamente. Combine um AGENTS.md enxuto com um CLAUDE.md que o importe.
- O Chrome informa 91% com orientação contra cerca de 51% sem orientação. O levantamento separado do Search Engine Journal mostrou 88% contra 56%, uma diferença menor.
- Nenhum trilho cobre sozinho acessibilidade ou comportamento entre navegadores, e as execuções orientadas geralmente custam mais tokens e tempo.
Conclusão
Para um primeiro piloto, escolha uma área do produto e dê a cada trilho um responsável. Registre as URLs exatas dos repositórios do Brandrail e do Brandrails, torne um único arquivo de tokens a fonte da verdade e mantenha enxutos os arquivos de agente sempre carregados, com um CLAUDE.md ao lado do AGENTS.md enxuto. Torne bloqueante uma verificação de desvio de tokens nas linhas alteradas, rode o verificador CLI do Brandrail como consultivo até ter uma linha de base e verifique a fronteira de dados do Brandrail com uma checagem de rede durante uma execução local. Meça o gasto de tokens e o tempo de execução antes e depois de ativar o Modern Web Guidance, e trate os números informados pelo fornecedor como uma hipótese a ser testada na sua própria base de código. Mantenha a revisão de acessibilidade e de compatibilidade entre navegadores com pessoas durante todo o processo.
Leituras relacionadas na Optijara: Playwright e axe em estados reais de UI e Rastreamento GenAI com OpenTelemetry para execuções de agentes.
Perguntas frequentes
O que são guardrails de código de UI com IA?
São ferramentas e verificações que mantêm a UI gerada por agentes de programação como Claude Code, Cursor, Copilot ou Codex consistente com seu design system e com as práticas web atuais. No Modelo de Três Trilhos usado aqui, o Brandrail cobre o trilho de marca, o Brandrails cobre design tokens e arquivos de instrução enxutos para agentes, e o Modern Web Guidance cobre o trilho de plataforma.
Brandrail e Brandrails são o mesmo projeto?
Não. O Brandrail (github.com/brandrail-app/brandrail) é um servidor MCP e verificador que entrega aos agentes seu Brand Kit e retorna uma pontuação de marca. O Brandrails (github.com/matejholek/brandrails) é uma ferramenta separada cujos arquivos de agente sempre carregados listam apenas os nomes dos tokens e apontam para uma referência de tokens mais completa. Sempre faça referência e instale a partir da URL exata do repositório.
Se Brandrail e Brandrails discordarem, qual prevalece?
Decida isso antes do piloto. Uma regra prática é que o arquivo de tokens no seu repositório seja a fonte da verdade e que o Brand Kit do Brandrail seja derivado dele. Se o Brand Kit não puder ser gerado a partir dos tokens, atualize-o na mesma alteração e atribua a um único responsável a responsabilidade por ambos.
O Brandrail envia meu código-fonte?
O Brandrail afirma que seu servidor MCP roda localmente via stdio e que o código é verificado na sua máquina e nunca é enviado. O serviço de contas hospedado é uma questão à parte. Veja a seção sobre o que o Brandrail mantém local para saber o que confirmar por escrito e como verificar a fronteira com uma checagem de rede.
O Claude Code lê o AGENTS.md ou também preciso de um CLAUDE.md?
O Claude Code não lê o AGENTS.md nativamente. Você precisa de um CLAUDE.md que importe ou reproduza essas regras. O DesignSystems.one relata que a contagem de arquivos não sustenta a ideia de que o AGENTS.md substituiu o CLAUDE.md, então sugerimos dar suporte a ambos como padrão.
Preciso das três ferramentas ou por qual uma equipe deve começar?
Comece pelo trilho de onde vem o seu desvio. Se as telas geradas ignoram suas cores e espaçamentos, comece pelo trilho de tokens (Brandrails) ou pelo trilho de marca (Brandrail). Se o código funciona, mas depende de padrões ultrapassados, comece pelo Modern Web Guidance. Muitas equipes acabarão combinando as ferramentas, mas fazer o piloto de um trilho primeiro torna o efeito mais fácil de medir.
O Modern Web Guidance, sozinho, torna a UI gerada por IA acessível e compatível entre navegadores?
Não. Ele eleva o patamar do código gerado, mas acessibilidade e compatibilidade entre navegadores ainda precisam ser testadas. Uma análise independente da versão preview encontrou problemas nas duas áreas. Mantenha testes automatizados de acessibilidade e revisão humana entre navegadores no pipeline.
Fontes
- 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/



