UI Audit — Revisão de Interface e Interação
Padrão de Design: Minimalismo + Animação Narrativa + Mínimo de Texto.
Princípio Central: Se der para resolver com visual, não use texto. Se der para substituir um aviso por animação, use animação. Quando o texto for inevitável, use o mínimo possível.
Scripts Acompanhantes
scripts/scan-ui.sh [DIRECTORY]: Script de varredura automatizada (somente leitura) para detectar símbolos de texto, texto de botão muito longo, strings hardcoded em chinês, loadings estáticos, classes CSS não definidas e outros problemas comuns de UI.
Passo 0: Verificação da Linha de Base de UI (deve ser executada antes de qualquer revisão)
Linha de Base de Navegação
□ O usuário consegue voltar para a página inicial a partir de qualquer página
□ O usuário consegue voltar da página de detalhes para a página de listagem
□ O usuário consegue ir da página de listagem para o fluxo de criação/novo
□ A posição atual não é perdida ao recarregar a página
Linha de Base de Tratamento de Estados
□ Cada carregamento de dado possui estado de loading (skeleton/spinner)
□ Cada chamada de API possui estado de erro (mensagem de erro visível ao usuário)
□ Cada lista possui estado vazio (mensagem amigável + guia de ação)
□ O envio de formulário possui estado desabilitado (prevenção de envio duplicado)
Linha de Base de Autenticação
□ A página de login tem entrada para "Registrar"
□ A página de registro tem entrada para "Login"
□ Após o login, redirecionar para uma página significativa (não tela em branco)
□ Limpar o estado ao fazer logout
□ Redirecionar automaticamente para a página de login quando o token expirar
Se a linha de base não for aprovada, corrija-a primeiro. Não realize nenhuma outra revisão de UI.
Filosofia de Design
Minimalismo
□ Cada página tem apenas um ponto focal visual
□ Espaços em branco são parte do design
□ Use no máximo 2 cores principais + 1 cor de destaque
□ use no máximo 1 tipo de fonte
□ Sem sombras, sem gradientes, sem cantos arredondados maiores que 4px
□ Espaçamentos devem ser múltiplos de 8px/16px/24px/32px
Animação Narrativa
□ Cada mudança de estado tem uma animação de transição (150-300ms)
□ Itens de lista entram com animação escalonada (intervalo de 30-50ms)
□ Clique em botão tem feedback de pressão (scale: 0.98)
□ Use Skeleton para carregamento, não placeholders estáticos
□ Erro usa animação de tremor ou mudança de cor, não pop-up
□ Sucesso usa uma animação de destaque curta, não toast
Mínimo de Texto
□ Texto do botão não excede 4 caracteres (no original, caracteres chineses; em português, máximo de 2-3 palavras)
□ Botões de ícone não têm texto (use tooltip como substituto)
□ Sem "Confirmar", "Cancelar" ou textos vagos (use "Salvar", "Descartar" como substitutos)
□ Mensagens de erro não excedem 10 caracteres (no original, caracteres chineses; em português, máximo de 4-5 palavras)
□ Itens de navegação não excedem 2 caracteres (no original, caracteres chineses; em português, máximo de 1-2 palavras) + ícone
Símbolos de Texto não são permitidos
□ Sem → ← ↑ ↓ (use ícones de seta)
□ Sem × (use ícone de fechar)
□ Sem + - (use ícones de adicionar/subtrair)
□ Sem > < (use ícone Chevron)
□ Sem ✓ ! (use ícones Check/Alerta)
□ Sem ~ (use separador visual)
□ Sem % (use barra de progresso ou anel)
Lista de Verificação
1. Verificação de Símbolos de Texto (Prioridade Máxima)
Execute scripts/scan-ui.sh para varredura automática e, em seguida, confirme manualmente cada correspondência para verificar se precisa ser substituída por um ícone.
2. Verificação do Sistema de Ícones
□ Ícones de operação comuns completos: save / trash / edit / arrow-left / x (close)
□ Ícones de navegação completos: search / plus / download / upload / external-link
□ Todos os ícones têm estilo uniforme (outline ou filled, escolha um)
□ Tamanho dos ícones uniforme (16px para ações, 24px para navegação, 32px para estado vazio)
□ Ícones da mesma biblioteca (ex.: Lucide / Heroicons / Phosphor), sem misturar
3. Verificação de Animação
□ Transição entre páginas tem animação (fade/slide)
□ Itens de lista entram com animação escalonada
□ Clique em botão tem feedback de pressão
□ Carregamento usa animação Skeleton
□ Modal/dropdown tem animação de abertura
□ Operações longas têm animação de progresso
Proibido: Spinner girando por mais de 2 segundos, tags piscando, animações em loop infinito, animações complexas que afetam performance.
4. Integridade da Internacionalização (i18n)
□ Todo texto visível ao usuário usa a função t()
□ Sem strings hardcoded em chinês (exceto nos arquivos de tradução)
□ Mensagens de erro usam chaves i18n
□ aria-label usa i18n
5. Consistência de CSS
□ Todas as classes CSS referenciadas no JSX estão definidas
□ Sem classes CSS não utilizadas
□ Hierarquia de z-index consistente (modal: 200, drawer: 100, backdrop: 99, toast: 300)
□ Cores usam variáveis CSS ou cores do tema, sem hex hardcoded
□ Sem !important (a menos que haja uma razão clara)
6. Verificação de Código Morto
□ Todos os arquivos de componentes são importados por pelo menos um outro arquivo
□ Sem arquivos com o mesmo nome (componentes duplicados em diretórios diferentes)
□ Sem imports não utilizados
7. Tratamento de Estados
□ Cada carregamento de dado possui estado de loading
□ Cada chamada de API possui estado de erro
□ Cada lista possui estado vazio
□ O envio de formulário possui estado desabilitado
□ Operações longas têm suporte para cancelamento/interrupção
8. Fluxo de Navegação
□ Todas as rotas possuem um componente de página correspondente
□ Rotas protegidas têm guard de autenticação
□ O erro 404 tem uma página de fallback amigável
□ Navegação por breadcrumbs/botão voltar está correta
□ Links externos abrem em nova aba
9. Responsividade e Acessibilidade
□ Layout móvel não transborda
□ Todos os elementos interativos têm aria-label
□ Operável por teclado (Tab para navegação, Escape para fechar, Enter para confirmar)
□ Modal/painel tem focus trap
□ Contraste de cores conforme WCAG AA
Fluxo de Trabalho
Fase 1: Varredura Automatizada
Execute scripts/scan-ui.sh, colete os resultados. Foco em: símbolos de texto, texto de botão muito longo, falta de animação, strings hardcoded em chinês, classes CSS não definidas.
Fase 2: Verificação Manual
Compare com a filosofia de design e lista de verificação, verifique página por página. Use Playwright para capturar screenshots de cada página e verificar.
Fase 3: Correção
Corrija por ordem de prioridade:
- Substituir símbolos de texto por ícones
- Simplificar texto
- Completar animações
- Completar classes CSS
- Completar i18n
- Remover código morto
- Tratamento de estados
- Fluxo de navegação
Fase 4: Re-varredura de Regressão
Após a correção, execute novamente a varredura automatizada para confirmar que não há novos problemas.
Relação com polish-loop-v2
- polish-loop-v2: Revisão de código geral (lógica, segurança, performance, runtime)
- ui-audit: Foco em Frontend UI e experiência do usuário
Execução paralela, com verificação de linha de base compartilhada. Problemas de ui-audit têm prioridade maior que os de polish-loop-v2.