ux-quality-check

Verificação de qualidade de UX

Verifique as superfícies de UI que uma alteração toca contra as regras em references/rules.md. Cada regra ali tem um motivo, uma verificação no código, uma verificação no navegador e uma correção. A tabela no topo desse arquivo diz a quais tipos de alteração cada regra se aplica.

1. Encontre a alteração

1. Obtenha o diff que a solicitação nomeia: um PR, um branch, um commit ou as alterações não commitadas. Se não houver nome, use as alterações não commitadas. Se não houver nenhuma, use o branch contra sua base de merge com o branch padrão (git diff $(git merge-base HEAD origin/HEAD)...HEAD). Se o branch for o branch padrão, use o último commit. Informe no relatório qual diff você verificou.
2. Liste os arquivos de UI alterados: componentes, templates, estilos, e as strings e props que eles renderizam. Uma alteração em um componente compartilhado ou token também é uma alteração de UI.
3. Se nenhum arquivo no diff renderizar UI (apenas código de servidor, testes, configuração ou docs), diga isso em uma ou duas frases e pare. Não reporte descobertas.

2. Leia as regras de UI do próprio repositório e mapeie as superfícies

As regras de um repositório têm prioridade sobre os padrões do catálogo.

• Leia os docs do agente do repositório (AGENTS.md, CLAUDE.md, um README de design-system) em busca de uma seção "Regras de UI" ou similar. Anote cada controle, token ou componente que eles nomeiam para uma regra, como um helper de diálogo, um botão assíncrono, tokens de tipo ou uma marca de IA. Uma correção nomeia esse componente.
• Procure pelas próprias verificações de UX do repositório: um alvo make ux-check ou ux:check, um script de layout ou acessibilidade, regras de lint, ou testes que escaneiam fontes em busca de regras de UI. Execute cada uma que cubra a alteração e use sua saída como evidência.

Em seguida, mapeie cada arquivo alterado para as superfícies que um usuário vê: a rota, a visão e o controle. Um componente compartilhado mapeia para cada superfície que o utiliza. Nomeie uma superfície da forma como um usuário a encontra ("Página de revisão, formulário de comentário"). Para cada superfície, anote:

• Tipos. Marque a superfície com cada tipo na legenda de references/rules.md que o diff adiciona ou edita: write, data, form, list, control, overlay, layout, route, copy, chart, style. Um novo estilo de hover é control e list. Um botão salvar é write.
• Estados. Vazio, carregando, pendente, erro, hover, foco, selecionado e desabilitado. A maioria das descobertas reside em um estado que o autor não abriu.

3. Execute as verificações

Para cada superfície, execute cada regra cujo "Aplica-se a" compartilhe um tipo com a superfície. Leia a seção da regra antes de verificá-la. Anote cada regra que você pular e o motivo.

Leia o código primeiro. O "Verificação no código" de cada regra diz o que procurar. Isso captura a maioria dos defeitos e não precisa de navegador. Antes de relatar um estado ausente, leia os componentes que o código chama: um wrapper (um botão assíncrono, um hook de formulário, um pai que passa pending) geralmente o trata.

Em seguida, meça no navegador, quando puder. Uma página HTML estática abre do disco com uma URL file://. Para um aplicativo, procure um servidor de desenvolvimento em execução ou inicie um com o comando documentado do repositório. Use a ferramenta de navegador que o host fornecer: um painel de navegador embutido, um script Playwright ou Chrome headless. Se a página solicitar login, peça ao usuário para fazer login nesse navegador. Não digite credenciais você mesmo.

Carregue scripts/measure.js na página. Ele define os helpers que cada "Verificação no navegador" da regra nomeia, e references/rules.md lista o que cada um retorna. Cole-o novamente após cada carregamento de página. Verifique cada tema e esquema que o aplicativo oferece, e pelo menos uma largura de telefone e uma largura de desktop.

Meça cada linha, cartão e controle alterado em seus estados de interação também. Um estado de hover, foco ou selecionado frequentemente adiciona um preenchimento, borda, sombra ou controle. Dois itens em caixa então se tocam, um item cresce e move seus vizinhos, ou uma ação somente em hover empurra uma contagem para fora da linha. Para cada lista, grupo de cartões ou grupo de controle na superfície:

1. Execute snapshot(sel, "rest") e gaps(sel) com os itens em repouso.
2. Passe o mouse sobre um item com a ferramenta do navegador, então execute snapshot(sel, "hover") e gaps(sel) novamente. Faça o mesmo com o foco do teclado (pressione Tab), e com o item selecionado próximo a um item em hover.
3. Execute moved("rest", "hover"). Uma lacuna de 0px entre dois itens em caixa, ou um item que se moveu quando outro estava em hover, é uma descoberta.

Faça o mesmo em torno de cada ação que abre um menu, popover ou painel: tire um snapshot dos blocos principais, abra-o, tire outro snapshot e compare. No código, leia cada regra :hover, :focus-visible e de classe selecionada em busca de propriedades que adicionam uma caixa ou alteram tamanho: background, border, box-shadow, padding, margin, width e display.

Sem navegador, ou sem página para abrir, reporte as descobertas de código e liste as verificações de navegador que não foram executadas.

4. Verifique cada descoberta

Antes de relatar uma descoberta, verifique-a mais uma vez:

• Descoberta de código. Confirme que um usuário pode alcançar o estado: o branch é executado, a prop é passada, e nenhum wrapper ou pai a trata.
• Descoberta de navegador. Meça uma segunda vez, após um recarregamento, no estado que a descoberta nomeia. Descarte um valor que não se repita.
• Na alteração ou antes dela. Um defeito em uma linha que o diff adicionou ou alterou pertence à alteração. Também um estado que o diff adiciona sem sua contraparte, mesmo quando a linha ausente iria para outro lugar: uma nova regra :hover sem uma regra :focus-visible, ou um novo write sem estado pendente. Um defeito em uma linha que o diff não tocou existia antes dele. Reporte-o em "Defeitos existentes", separado das descobertas da alteração, e apenas quando ele estiver em uma superfície alterada.

Descarte uma descoberta que falhe em sua verificação. Reporte uma descoberta que você não pôde verificar como "Não confirmada", com o motivo.

5. Reporte as descobertas

Comece com uma linha que nomeie o diff que você verificou e as superfícies. Em seguida, forneça uma descoberta por defeito, primeiro o mais grave. Gravidade:

• Alta: o usuário perde dados ou entrada, envia um write duplicado, não consegue alcançar um controle ou não consegue ler texto.
• Média: o controle engana (ícone errado, estado apenas por cor, marca de IA ausente) ou o layout está visivelmente quebrado.
• Baixa: inconsistência com o sistema do repositório (valores de tipo brutos, controles de seleção mistos, preenchimento).

Cada descoberta tem quatro partes:

Parte	Conteúdo
Superfície	A visão e o controle, mais o arquivo e a linha (ReviewForm.tsx:42)
Regra	O id da regra do catálogo, ou a regra do repositório que ela quebra
Evidência	O que você leu ou mediu: a linha de código, os valores medidos, o estado, tema e largura
Correção	A alteração, em uma ou duas frases, com o componente ou token do repositório onde ele nomeia um

Exemplo:

Superfície: Barra lateral da pilha, lista de filtros de autor (AuthorList.tsx:58) Regra: no-cramped-controls Evidência: gaps(".author-row") a 1440px, com linha 2 em hover: y: 0 entre linha 1 (selecionada) e linha 2. Em repouso a lacuna também é 0, mas apenas a linha selecionada desenha uma caixa. Correção: Adicione gap: 2px à lista, ou recue o preenchimento de hover em 2px.

Em seguida, adicione estas seções:

1. Defeitos existentes: os defeitos da etapa 4 que a alteração não introduziu, um por linha.
2. Não verificado: as regras que você pulou e por quê, e as verificações de navegador que não foram executadas.

Quando o usuário solicitar correções, faça-as e então execute as mesmas verificações novamente nas mesmas superfícies.