Como revisar o front-end gerado pelo Claude antes de subir para produção

Fala aí, beleza? Tela que renderiza não é tela pronta pra produção

O Claude monta um front-end completo em poucos minutos, e aí o gargalo simplesmente muda de lugar: não é mais escrever a interface, é conferir o que veio

E não dá pra tratar isso como paranoia. No relatório GenAI Code Security 2026 da Veracode, a taxa média de aprovação em segurança do código gerado por IA é de 56%, com mais de 100 modelos testados ao longo de quatro anos, e a atualização Spring 2026 mantém o mesmo diagnóstico: a segurança do código gerado por IA segue estagnada enquanto o volume desse código nos pipelines só cresce

Então o recorte deste post é bem específico: controle de qualidade do resultado

Nada de prompt mágico, nada de "como pedir a tela perfeita". A tela já existe, tá no seu diff, e a pergunta é uma só: isso sobe ou não sobe?

O que ter antes de começar a revisão:

Antes de sair clicando, deixa quatro coisas prontas. Sem isso a revisão vira chute

• O projeto rodando localmente, porque metade dos problemas de interface só aparecem na tela, não no código
• O diff isolado do que o Claude gerou, separado do resto do seu trabalho, pra você saber exatamente o que está julgando
• A referência de tokens do design system do projeto: quais cores, espaçamentos, raios e sombras são permitidos
• Um verificador de acessibilidade, e aqui a escolha óbvia é o axe-core, a engine open source mantida pela Deque Labs que roda por trás de um monte de extensão e integração de teste

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Quer que o próprio modelo abra a página e inspecione? Aí entra o Playwright MCP, o servidor MCP oficial mantido pela Microsoft (microsoft/playwright-mcp), que interage com a página usando snapshots de acessibilidade estruturados em vez de sair adivinhando pixel

A documentação do Playwright indica este comando pra adicionar ele no Claude Code:

claude mcp add playwright npx @playwright/mcp@latest

E qual régua eu uso pra dizer que está certo?

Boa pergunta, porque tem MUITA confusão rolando nesse ponto

A referência vigente é a WCAG 2.2, que é a Recomendação atual do W3C: publicada em 5 de outubro de 2023 e atualizada em 12 de dezembro de 2024

A WCAG 3.0 ainda é Working Draft, ou seja, rascunho. Não é padrão de conformidade e não é exigível. Se alguém te disser que precisa "adequar pra WCAG 3", segura a onda: quem manda em auditoria e em legislação continua sendo a WCAG 2.2

Como revisar o front-end gerado pelo Claude, passo a passo:

A ordem importa. Começa no código, depois vai pra tela, depois pro teclado, aí liga o automatizado e fecha no olho humano, que é quem dá a palavra final

1. Ler o diff antes de abrir a tela

Esse é o passo que quase todo mundo pula, e é o mais barato de todos

Você está caçando valor solto: hex cravado no CSS, px chutado no espaçamento, box-shadow inventada, z-index: 9999 e afins. Tudo que deveria ser token do projeto e virou número mágico

git diff --stat
git diff -- 'src/components/**'

Depois passa uma varredura rápida atrás dos suspeitos de sempre:

grep -rnE "#[0-9a-fA-F]{3,8}|[0-9]+px|rgba?\(" src/components/NovaTela

Um parêntese útil aqui: o Design Tokens Community Group anunciou em 28 de outubro de 2025 a primeira versão estável da especificação de design tokens, o Design Tokens Format Module 2025.10

Só que é uma spec de community group, não é padrão W3C nem trilha de padronização. Traduzindo: a fonte da verdade pra você continua sendo o design system DO SEU projeto, não a spec

Se você já tem o hábito de revisar o diff antes de commitar, esse passo é só apontar a mesma lupa pra camada de interface

O erro comum deste passo: aceitar o valor solto porque "visualmente ficou igual". Ficou igual hoje. Quando o token mudar, essa tela vira a única fora do padrão

2. Responsividade nos breakpoints do projeto

Não nos breakpoints genéricos do framework, nos SEUS

Abre a tela e vai estreitando. O que você procura: overflow horizontal (o clássico scroll lateral que ninguém pediu), texto que quebra em lugar feio, botão que sai do container e tabela que estoura a largura

Tabela é a campeã de problema, porque no mock tem três colunas curtinhas e na produção tem oito com nome completo de cliente

O erro comum deste passo: testar só reduzindo a janela do desktop. Testa também com o conteúdo real, que é bem mais comprido que o placeholder

3. Os quatro estados que a IA costuma esquecer

Carregando, vazio, erro e desabilitado

A IA pula esses estados porque o mock dela sempre tem dado. Na vida real a lista volta vazia, a API cai, o botão precisa ficar travado durante o submit

Força cada um na mão: comenta o fetch, devolve array vazio, joga um erro de propósito

O erro comum deste passo: aceitar um spinner solto no meio da tela como "estado de carregando". Se o layout pula quando o dado chega, o estado não está resolvido

4. Navegação só com Tab

Tira a mão do mouse. Sério, tira 😀

Percorre a tela inteira no Tab e confirma duas coisas: dá pra chegar em tudo que é clicável, e dá pra VER onde você está

O critério 2.4.11 Focus Not Obscured (Minimum) é nível AA na WCAG 2.2 e diz o seguinte: quando um componente recebe foco de teclado, nenhuma parte dele pode ficar escondida por conteúdo criado pelo autor. Header fixo, banner de cookie e modal são os vilões de sempre

Já o 2.4.13 Focus Appearance é nível AAA, não AA. Ele pede área do indicador de foco pelo menos igual à de um perímetro de 2 pixels CSS de espessura do componente, e contraste mínimo de 3:1 entre os estados focado e não focado

Tome cuidado com artigo antigo aqui: muita gente lista o 2.4.13 como AA porque escreveu o texto na fase de Proposed Recommendation, antes da versão final

O erro comum deste passo: o famoso outline: none que a IA herda de algum reset e ninguém repõe depois

5. Alvos de toque

O critério 2.5.8 Target Size (Minimum) é nível AA e pede alvos de no mínimo 24 por 24 pixels CSS, com exceção quando existe espaçamento suficiente entre os alvos

Onde isso quebra na prática: ícone de fechar modal, botão de deletar linha de tabela, chip com um X minúsculo do lado

Mede no inspetor mesmo, é rápido. E lembra que a área clicável pode ser maior que o desenho do ícone

O erro comum deste passo: olhar só o tamanho do ícone e esquecer que dois alvos pequenos colados são pior que um sozinho

6. Rodar a checagem automatizada

Agora sim liga o axe na página e resolve o que ele apontar

Rótulo faltando, contraste reprovado, atributo ARIA inventado, estrutura de heading fora de ordem: esse tipo de coisa o automatizado acha em segundos e não faz sentido você caçar na unha

O erro comum deste passo: rodar só na tela inicial. Roda com o modal aberto, com o formulário em erro, com a lista vazia. Cada estado é uma página diferente pro verificador

7. Passe manual do que sobrou

O automatizado terminou verde? Ótimo, você fez metade do trabalho

A outra metade é julgamento: a ordem do foco faz sentido, o texto alternativo descreve de fato a imagem, a mensagem de erro diz o que fazer, o contraste se mantém no hover e no estado desabilitado

O erro comum deste passo: tratar build verde como aprovação. É exatamente sobre isso a próxima seção

O que o teste automatizado não pega (e como cobrir):

Sintoma: o pipeline passa, o relatório de acessibilidade não acusa nada, e mesmo assim o usuário trava na tela. Ele chega no campo e não sabe que chegou, ou lê "Erro ao processar" e não faz ideia do que corrigir

Causa: ferramenta automática cobre o que é verificável por regra, e boa parte do problema não é regra, é sentido

Um estudo da Deque com dados anonimizados de mais de 2.000 auditorias, mais de 13.000 páginas e cerca de 300.000 problemas apontou que, em média, 57% das ocorrências de acessibilidade foram cobertas por teste automatizado, usando a suíte axe (a mesma baseada no axe-core)

57% é um número ótimo pra uma ferramenta e péssimo pra um critério de aprovação. O resto depende de gente olhando: ordem de foco coerente com a leitura, texto alternativo que descreve de verdade em vez de repetir o nome do arquivo, contraste no estado hover, feedback de erro que explica o próximo passo

Solução: dois passes manuais fixos na sua revisão

• Um passe de teclado, do começo ao fim da tela, sem mouse
• Um passe de leitura, lendo em voz alta cada texto que a IA escreveu: label, placeholder, mensagem de erro, texto alternativo

Parece bobo o de leitura, mas é onde aparece o "Ocorreu um erro inesperado" genérico que a IA adora colocar

Como prevenir isso desde a geração:

Deixa os estados e o comportamento de foco escritos na especificação da tela antes de mandar gerar. O que não está escrito, o modelo preenche do jeito dele

E tem o lado de compliance, que deixou de ser assunto só de empresa grande: o European Accessibility Act passou a ser exigível em 28 de junho de 2025, e a versão do EN 301 549 citada como referência técnica (a V3.2.1, de março de 2021) incorpora a WCAG 2.1 nível AA

Ou seja: acessibilidade saiu da coluna de "seria legal" e entrou na de requisito

Como travar a régua no projeto para a próxima geração:

Revisar tela por tela na mão funciona, mas não escala. A ideia agora é a revisão não recomeçar do zero toda vez

1. Escreve as regras de front-end no CLAUDE.md do projeto

O CLAUDE.md pode ficar em ./CLAUDE.md ou em ./.claude/CLAUDE.md, e é carregado no início de cada sessão. Se você ainda não tem, o comando /init gera um arquivo inicial a partir da análise do repositório

O que entra ali: quais tokens são permitidos, quais são os breakpoints do projeto, quais estados são obrigatórios em toda tela com dado remoto

Se a tela conversa com base de verdade, vale um cuidado extra antes de apontar o agente para dados reais

O erro comum deste passo: escrever regra vaga tipo "seguir o design system". Regra boa é específica e verificável

2. Transforma o checklist em comando customizado

O formato recomendado no Claude Code é .claude/skills/<nome>/SKILL.md, invocável como /nome. O diretório .claude/commands/ é o formato legado

Aí a revisão vira uma coisa só, sempre na mesma ordem, sem depender da sua memória numa sexta às 18h 😛

.claude/
  skills/
    revisar-front/
      SKILL.md

O erro comum deste passo: colar o checklist inteiro e nunca atualizar. Toda vez que a revisão pegar um problema novo, o problema vira linha nesse arquivo

3. Automatiza o que é mecânico com hook

Formatação não merece atenção humana. No Claude Code, o evento de hook PostToolUse com matcher Edit|Write dispara um comando depois das ferramentas de edição de arquivo, e a configuração fica em .claude/settings.json

A própria documentação traz um exemplo que roda o Prettier no arquivo editado:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATHS"
          }
        ]
      }
    ]
  }
}

O erro comum deste passo, e esse é o mais importante da seção: contar com o hook pra BARRAR código ruim. O PostToolUse não desfaz a ação, porque a ferramenta já foi executada quando ele dispara. Ele serve pra arrumar e pra avisar, não pra impedir

Conclusão

Gerar interface ficou barato. Entregar interface, não

O que fecha essa distância não é um prompt melhor, é uma régua fixa: mesma ordem, mesmos critérios, mesmo checklist em toda tela que sai da IA. Sem isso, a velocidade de geração só empurra o problema pra frente, até estourar no usuário

Próximo passo bem concreto pra hoje: pega a ÚLTIMA tela que o Claude gerou pra você, roda o checklist na ordem deste post (diff, breakpoints, estados, teclado, alvo de toque, automatizado, manual) e anota os três itens que mais falharam

Esses três viram regra no CLAUDE.md do projeto ainda hoje

Aí na próxima tela você começa a revisão de um degrau acima, e por aí vai…

até o próximo post! 🙂