Como um bot de revisão do Modern Web Guidance ajuda a MetaMask a lançar uma interface acessível e moderna

Gilberto Cocchi

Rick Viscomi

Publicado em: 10 de novembro de 2026

A MetaMask é uma plataforma financeira de autocustódia com mais de 100 milhões de downloads em aproximadamente 190 países. A extensão do navegador é desenvolvida de forma aberta, então há um fluxo constante de solicitações de pull de colaboradores de dentro e de fora da empresa.

O engenheiro de UX da MetaMask, Francis Nepomuceno, analisou muitas dessas solicitações de pull e queria uma maneira consistente de ajudar os colaboradores a aplicar as práticas recomendadas de acessibilidade e usar recursos modernos da Web. No editor, ele já usou as Modern Web Guidance do Chrome, um conjunto de habilidades que traz as práticas recomendadas da plataforma da Web e dados de compatibilidade do navegador para agentes de programação. Para oferecer a mesma orientação a outros colaboradores, ele configurou um bot para analisar cada solicitação de pull no repositório de código aberto da MetaMask, independentemente das ferramentas usadas pelo autor.

O desafio: acompanhar os recursos modernos da Web

O HTML e o CSS modernos continuam adicionando recursos que melhoram a acessibilidade e a experiência do usuário, e é difícil acompanhar quais deles funcionam em todos os navegadores. Com muitos colaboradores, esse conhecimento precisa chegar a todos que abrem uma solicitação de pull.

A segurança é outro motivo para se preocupar: o MetaMask coloca em sandbox todas as dependências de terceiros por padrão, o que torna um recurso nativo do navegador mais barato de adotar do que uma alternativa de biblioteca. Como Nepomuceno disse, "ter acesso a essas APIs modernas, como poder usar caixas de diálogo e menus suspensos sem JavaScript, foi uma grande vitória".

A solução: o Modern Web Guidance analisa cada solicitação de pull

Em 16 de setembro de 2026, uma solicitação de pull para MetaMask/metamask-extension adicionou uma página "Como funciona" com perguntas frequentes criadas da mesma forma que a maioria das perguntas frequentes do React:

// Before: Custom React state (removes content from DOM)
const [expanded, setExpanded] = useState(false);
<button type="button" aria-expanded={expanded} onClick={() => setExpanded(c => !c)}>
  <Text>{question}</Text>
</button>
{expanded ? <Text>{answer}</Text> : null}

Cerca de cinco minutos depois, o bot comentou. Citando o guia search-hidden-content, ele destacou três pontos:

• A renderização condicional de cada resposta a remove do DOM, de modo que o texto recolhido não pode ser encontrado com a pesquisa in-page do navegador e é mais difícil de ser descoberto pela tecnologia adaptativa.
• Uma declaração nativa de <details>/<summary> (Baseline desde 2020) mantém o conteúdo no DOM com a semântica correta. Para painéis mutuamente exclusivos, um atributo name compartilhado (disponível recentemente no Baseline desde 2024) fecha os outros automaticamente. Para uma seção de perguntas frequentes com vários painéis abertos, omita esse atributo.
• Se a equipe preferisse o componente Disclosure atual, ela deveria pelo menos manter as respostas no DOM com hidden="until-found" e um listener beforematch que sincroniza aria-expanded e o estado do ícone.

// After: Native <details> / <summary> disclosure (findable with find-in-page)
<details>
  <summary>
    <Text>{question}</Text>
  </summary>
  <Text>{answer}</Text>
</details>

Treze minutos depois, o autor enviou uma correção. O componente se tornou uma divulgação nativa de <details>/<summary>, as respostas recolhidas permaneceram no DOM para localização in-page e dois botões de navegação se tornaram links.

Esse bot é uma automação de cursor que executa o Modern Web Guidance, e Nepomuceno o configurou com um comando de três linhas. Até 21 de outubro de 2026, cinco semanas após o início:

• O bot foi executado em cerca de 480 solicitações de pull e comentou em 64 delas (57 solicitações de pull de recursos e correções, além de 7 solicitações de pull de lançamento e sincronização automatizadas) de 26 autores.
• Nas solicitações de pull de recursos e correções, os engenheiros corrigiram 43 das descobertas e corrigiram parcialmente mais 3, em 22 solicitações de pull.
• Os engenheiros agiram rapidamente: das 38 correções com um commit identificável, 19 foram feitas em 15 minutos e 26 em uma hora, com uma mediana de 15,2 minutos do comentário à correção.

Veja como a MetaMask configurou o bot, o que ele detectou e onde ele foi ruidoso.

A configuração é um comando de três linhas

Quando perguntado sobre como a automação é configurada, Nepomuceno respondeu: "Não há nada de especial na nossa configuração. Nós apenas o mantemos conciso e com escopo." A instrução inteira:

- Run /modern-web-guidance for any client-facing changes
- Run /chrome-extensions for any relevant extension changes
- Comment on the PR only when there are issues to address. Keep the comment focused on actionable items

Como isso se comporta na prática:

• É consultivo: nos primeiros dois dias, o bot postou revisões de "solicitação de mudanças" (e uma aprovação), que os autores dispensaram depois de resolvê-las. Desde 18 de setembro, todas as revisões são comentários. Ele não bloqueia uma mesclagem, então os autores mantêm a decisão final sobre cada sugestão.
• Ele cita guias e arquivos específicos no repositório: nas 64 solicitações de pull comentadas, o bot levantou 122 descobertas. Das 102 solicitações de pull de recursos e correções, 63 nomeiam o guia específico do Modern Web Guidance que estão aplicando, como search-hidden-content, state-aware-sticky-headers ou sms-otp-form, e apontam para um arquivo existente no repositório quando ele já usa o padrão recomendado.
• Ele permanece silencioso, a menos que uma solicitação de pull toque na interface: das cerca de 480 solicitações de pull nessas cinco semanas, pelo menos 100 tocaram na interface ou no código do cliente, e o bot teve uma média de duas descobertas por solicitação de pull comentada. As equipes com repositórios principalmente de front-end podem esperar que ele comente em uma parcela maior.

O comando em si funciona com qualquer executor de agente. O Modern Web Guidance é instalado como uma habilidade ou plug-in para Cursor, Claude Code, Codex, GitHub Copilot, Antigravity e outros agentes de programação. Quando um agente executa a habilidade, ele procura os guias correspondentes em um índice local sem precisar de chaves de API e verifica a diferença em relação a eles, usando o modelo que o executor de agentes da equipe já fornece.

O que o Modern Web Guidance detectou que os linters não detectaram

Um linter estático pode sinalizar um atributo ausente em um único elemento, mas as descobertas a seguir se resumem ao comportamento de interação, à semântica do HTML e à forma como os componentes se encaixam nos arquivos.

Um campo de taxa de transação que parecia editável, mas ignorava silenciosamente as entradas

Nas configurações avançadas de taxa de transação da MetaMask, o campo de limite de gas (que limita a taxa de rede que uma transação pode consumir) parecia editável, mas ignorava silenciosamente a entrada dos usuários. Isso acontecia quando uma estimativa de taxa ainda estava carregando ou falhava. Enquanto isso, o botão "Salvar" foi desativado, sem nenhuma explicação que a tecnologia adaptativa pudesse ler.

Citando o guia de formulários, o bot sinalizou três correções:

• Desative o campo de limite de gás quando não houver estimativa disponível e conecte o texto de status visível ao campo para que a tecnologia adaptativa leia a explicação.
• Conecte o botão "Save" desativado ao mesmo texto de status para que os leitores de tela saibam por que ele está desativado.
• Mude o campo para um modo de entrada numérica para que os usuários de dispositivos móveis tenham um teclado numérico.

O autor aplicou as três correções nos dois modais de configurações e os consolidou em um único componente.

Botões de banner que ocultavam os URLs

Em um banner de status de um dos recursos de negociação da MetaMask, as ações inline "FAQ" e "contact MetaMask Support" foram criadas como botões que abriam uma nova guia com JavaScript, em vez de links. Em três minutos, o bot, citando os guias de HTML e acessibilidade, sinalizou que os leitores de tela os anunciam como botões e que os usuários perdem recursos de link, como copiar o URL ou abri-lo em uma nova guia no menu de contexto. Ele também apontou para um componente de banner existente na base de código da MetaMask que já renderiza essas ações como links reais.

Doze minutos depois, o autor mudou as duas ações para links. "Acho muito útil que, depois que uma orientação é adotada, as avaliações futuras a mencionem como um exemplo de referência", disse Nepomuceno.

Entradas de verificação com rótulos em outro lugar

A capacidade do bot de ler vários arquivos também foi útil em um formulário de várias etapas. Um linter estático só vê um campo de texto com texto de preenchimento dentro de cada etapa e não consegue identificar que o título e as instruções visíveis estão em um componente de layout pai. Citando os guias de formulários e acessibilidade, o bot percebeu que o marcador de posição era o único rótulo do campo, que o título da etapa e as instruções no layout pai não estavam associados à entrada e que as mensagens de erro e "código reenviado" não eram anunciadas para leitores de tela. Quinze minutos depois, todos os três foram corrigidos, e essa fiação de acessibilidade permaneceu intacta quando uma solicitação de pull de acompanhamento reestilizou a entrada de código como seis caixas de dígitos visuais.

Mais algumas coisas que o bot encontrou

Mais cinco descobertas da mesma execução de cinco semanas:

• Um detalhe de CSS que o engenheiro por trás do bot não percebeu: a própria solicitação de pull de Nepomuceno para guias iniciais fixas aninhava consultas de estado de rolagem CSS sem nomear os contêineres e alternava uma borda de uma forma que mudava o layout no meio da rolagem. O bot citou o guia de cabeçalhos fixos com reconhecimento de estado, e ele corrigiu ambos. Ele achou as avaliações úteis para consultas de posicionamento de âncora e estado de rolagem.
• Deslizamento limitado no meio da digitação: as entradas de deslizamento personalizadas (o movimento de preço que um usuário tolera em uma negociação) limitavam valores acima de 100% a cada pressionamento de tecla, transformando 101 em 100 enquanto o usuário ainda estava digitando. Seguindo o guia de formulários, a correção moveu a validação para quando o campo perde o foco e adicionou um banner de aviso visível.
• Um indicador de carregamento que os leitores de tela não conseguiram usar: um esqueleto de carregamento de lista de tokens colocou o rótulo "carregando" em um elemento genérico sem função, o que é proibido pela ARIA. O bot apontou para dois componentes na base de código que já usavam o padrão somente para leitores de tela da MetaMask (ambos atualizados após uma revisão do Modern Web Guidance seis dias antes), e o autor alinhou o esqueleto com esse padrão oito minutos depois.
• Ação assíncrona desprotegida: um botão assíncrono "Ver no provedor" não tinha proteção em andamento, então um clique duplo podia abrir guias duplicadas e observadores em segundo plano. O autor adicionou uma proteção menos de quatro minutos após o comentário.
• Validação de pressionamento de tecla sem um formulário: uma página de importação de NFT validada a cada pressionamento de tecla e sem um elemento <form> para semântica de envio. Ambos foram corrigidos 19 minutos após a análise.

Todas as avaliações são públicas. Os comentários completos do bot estão em cada solicitação de pull vinculada, e você pode conferir todos eles no GitHub.

O que não foi corrigido e o nível de ruído

Nem todas as descobertas foram registradas. A tabela a seguir mostra como o MetaMask contabilizou as 102 descobertas em solicitações de pull de recursos e correções (mais 20 foram encontradas em sete solicitações de pull de lançamento e sincronização, em que uma revisão não deve mudar o código):

Dividido por tema em todas as 122 descobertas (incluindo as 20 sobre solicitações de pull de lançamento e sincronização):

Alguns padrões nesses números:

• As correções que permanecem dentro de um componente são muito mais frequentes do que as mudanças de acessibilidade transversais. As correções de formulários e HTML permanecem dentro do componente em análise, então os autores geralmente as aplicam imediatamente (19 de 31 corrigidas). A acessibilidade teve o maior número de descobertas (38), mas apenas 12 foram corrigidas, geralmente porque a correção estava fora do escopo da solicitação de pull ou precisava de um componente compartilhado do sistema de design que ainda não existia.
• "Outros" é onde ele se desvia das orientações da plataforma da Web. Dezesseis descobertas cobriram a consistência do sistema de design, bugs lógicos, cópia, qualidade do teste, modo escuro e higiene do código. Três foram resolvidas, uma delas uma regressão real (uma mudança na lista de redes que interrompeu o preenchimento automático do formulário). A maioria desses 16 foi fácil de ignorar, mas detectar essa regressão fez com que valesse a pena dar uma olhada rápida.
• Os falsos positivos vieram da forma como o agente aplicou os guias, e a maior parte do ruído pode ser corrigida na configuração. Como o bot de revisão é um agente que lê uma diferença em vez de um linter estático, os falsos positivos vieram de uma leitura incorreta do código ao redor ou da aplicação de uma regra de forma mais rigorosa do que o guia vinculado. Pular as ramificações de lançamento e sincronização e restringir o comando para que o agente siga as regras explicitamente declaradas em um guia são os próximos ajustes óbvios.

Nepomuceno descreve o efeito mais amplo na equipe e no tempo de resposta da revisão:

O engenheiro da MetaMask, David Murdoch, também contribuiu para as próprias orientações: quando o guia de layout CSS (link em inglês) apresentou um erro em um dos exemplos, ele registrou um problema (link em inglês), e a equipe do Modern Web Guidance mesclou uma correção dois dias depois.

O que a MetaMask diria a uma equipe que está considerando usá-la

• Leia as orientações antes de escrever qualquer coisa. Execute npx modern-web-guidance@latest search "accordion find in page" para ver quais guias um agente recuperaria para uma tarefa. Você também pode navegar pelo conjunto completo de Modern Web Guidance guides.
• Comece com o comando de três linhas e o agente que você já executa. Instale a habilidade (npx modern-web-guidance@latest install ou o comando de plug-in de um agente), aponte o que pode ser executado em solicitações de pull para ela e diga para comentar apenas quando houver algo acionável e para seguir as regras explicitamente declaradas em um guia. Manter o bot quieto quando nada está errado é o motivo pelo qual os engenheiros da MetaMask ainda leem os comentários dele.
• Algumas descobertas não serão abordadas. Das 102 descobertas sobre solicitações de pull de recursos e correções, 43 foram corrigidas e 36 foram recusadas ou não resolvidas. Essa proporção funciona bem para um bot de revisão consultiva, mas seria prejudicial como uma verificação de bloqueio.
• Mantenha a revisão humana. O bot é bom em semântica de plataforma da Web, CSS moderno e padrões de interação, mas não conhece o produto.

Também há o que a MetaMask ainda não mediu: em cinco semanas, a equipe não rastreou o custo por solicitação de pull, o ambiente de execução, as comparações de modelos ou como o bot de revisão se comporta fora de uma base de código React.

Com três linhas de configuração, a MetaMask recebeu um bot de revisão que cita um guia específico para a maioria das descobertas (e um exemplo no repositório, quando existe). As sugestões aceitas geralmente são corrigidas em até uma hora.