Congele o contrato de revisão primeiro
Não comece clicando aleatoriamente e coletando impressões. Primeiro, defina o que esta revisão deve provar. Sem esse contrato, os revisores tendem a inventar requisitos, tratar gosto pessoal como defeito ou aceitar uma tela atraente cuja tarefa principal nunca é concluída.
- Tarefa do usuário: Declare o resultado em termos do usuário, como "convidar um colega e ver a confirmação", em vez de "revisar a página de configurações".
- Requisitos do produto: Liste as ações aprovadas, permissões, dados, regras de validação, confirmações, comportamento de cancelamento e caminhos de recuperação aplicáveis.
- Autoridade de design: Indique o DESIGN.md, conjunto de tokens, arquivo de tema, guia de componentes, kit de referência ou design aprovado exato que rege a interface.
- Artefatos de entrega: Registre como essas decisões chegam ao projeto, como variáveis CSS, valores de tema do Tailwind, tokens DTCG, um item de registro do shadcn ou arquivos gerados.
- Plataformas e viewports: Inclua apenas os navegadores, dispositivos, larguras de container e modos de cor que o produto suporta.
- Fixuras de conteúdo: Prepare exemplos realistas curtos, típicos, longos, vazios, inválidos e restritos, onde for relevante.
- Estados necessários: Nomeie os estados de inatividade, carregamento, sucesso, vazio, erro, desativado, foco, selecionado, aberto e de permissão que a tarefa pode realmente alcançar.
- Exclusões: Registre o trabalho que está fora deste lançamento para que sua ausência não seja confundida com um defeito.
Um requisito não definido não é um defeito de implementação
Se o contrato de revisão não disser se uma ação precisa de confirmação, quem pode realizá-la ou o que a recuperação deve fazer, direcione essa descoberta para o requisito do produto. Não peça ao agente de código para inventar políticas.
Use quatro trilhas de evidências separadas
Uma interface gerada pode passar em um tipo de revisão e falhar em outro. Mantenha as evidências separadas para que um resultado visual forte não esconda uma tarefa quebrada, e uma tarefa funcional não justifique uma implementação inacessível ou frágil.
1. Completude da tarefa
Comece pelo resultado do usuário e percorra cada ramificação necessária. Um teste aprovado descreve um comportamento observável, não uma impressão.
- A ação primária está visível ou é descoberta no momento em que o usuário precisa dela.
- Os rótulos descrevem a ação resultante, em vez de uma intenção vaga.
- A navegação preserva o contexto do usuário onde o requisito indica que deve preservar.
- A validação identifica o campo ou ação afetada e oferece ao usuário um próximo passo possível.
- O sucesso produz a confirmação necessária ou a alteração de estado.
- O cancelamento deixa os dados e a navegação na condição esperada.
- Restrições de permissão impedem a ação e explicam o que o usuário pode fazer a seguir.
- Os fluxos de carregamento, estados vazios, falhas, tentativas de reenvio e recuperação funcionam quando estão no escopo.
- A interação via teclado consegue alcançar e operar os controles da tarefa onde o uso de teclado é suportado.
Escreva os critérios de aceitação como observações. Por exemplo: "Enviar um convite válido desativa o envio duplicado, mostra o progresso, retorna uma mensagem de sucesso contendo o endereço convidado e adiciona o membro pendente à lista". Isso pode ser verificado. "O fluxo de convite parece intuitivo" não pode.
2. Conformidade com o design system
Rastreie as decisões visíveis até a autoridade declarada. Verifique cores semânticas, papéis de tipografia, espaçamento, layout, motivos, tratamentos de componentes e comportamento de modo. Registre valores não explicados, mas não assuma que cada diferença esteja errada. Uma exceção local pode ser intencional, obsoleta ou inexistente no sistema.
- Papéis semânticos: Os componentes usam papéis como background, foreground, primary, border, ring, success, warning e destructive para seus significados pretendidos.
- Tipografia: Os papéis de heading, body, label, data e mono usam as famílias, pesos, tamanhos, alturas de linha e regras de capitalização declarados.
- Espaçamento: Lacunas repetidas seguem a escala documentada, a menos que exista uma exceção aprovada.
- Layout: Largura da página, grid, alinhamento, densidade e transições responsivas correspondem às regras declaradas.
- Componentes: Botões, inputs, cards, tabelas, navegação, overlays e tratamentos de feedback usam as variantes e estados pretendidos.
- Modos: Os valores de light e dark mantêm o mesmo significado semântico, e as exceções específicas de modo são documentadas.
- Motivos: Tratamentos decorativos aparecem apenas onde a autoridade os permite e não interferem no significado ou na interação.
- Valores hardcoded: Cores avulsas, declarações de fonte, raios, sombras e valores de espaçamento possuem um motivo documentado ou são encaminhados para correção.
Diferença não significa automaticamente desvio
Quando a UI gerada difere da autoridade, determine primeiro se a regra do sistema se aplica àquela superfície. O resultado pode ser um defeito de implementação, uma regra de design system ausente ou uma expectativa inválida no fixture.
3. Resiliência
Substitua conteúdos temporários (placeholders) por fixtures que estressem o layout real. Revise a mesma tarefa em diferentes viewports e estados obrigatórios, em vez de julgar screenshots separadas como composições isoladas.
- Use nomes, datas, preços, status, descrições e densidade de dados realistas.
- Teste rótulos longos e textos com extensões traduzidas sem alterar o significado pretendido.
- Verifique layouts estreitos e largos nos tamanhos de container ou viewport suportados.
- Verifique quebras de linha, truncamento, overflow, regiões fixas (sticky), overlays e comportamento de rolagem.
- Aumente o zoom ou o espaçamento de texto do usuário e registre cortes, sobreposições, perda de conteúdo ou controles bloqueados.
- Use todos os modos de cor declarados e qualquer configuração de cores forçadas (forced-colors) suportada.
- Inspecione os estados de foco, hover, active, selected, disabled, open, loading, empty, error e success que a tarefa pode alcançar.
- Repita a tarefa com dados lentos ou falhos onde o produto suporte essas condições.
O modo de cores forçadas merece sua própria observação quando é suportado. Os navegadores podem substituir as cores definidas por uma paleta selecionada pelo usuário, portanto, significados que existam apenas em um preenchimento, borda ou sombra personalizada podem desaparecer. Registre o que permanece perceptível em vez de assumir que o tema comum prevê o resultado.
4. Evidências de acessibilidade
Use esta revisão para identificar preocupações e coletar evidências, mas mantenha a afirmação delimitada. Inspeção visual, conformidade de tokens, verificações automatizadas e crítica de IA podem encontrar problemas. Nenhum deles, sozinho, certifica a acessibilidade.
- Registre a ordem do teclado, visibilidade do foco, operação de controles e comportamento do foco em torno de overlays.
- Verifique se os nomes dos controles, rótulos visíveis, instruções, erros e mudanças de estado são compreensíveis no contexto.
- Verifique se a informação não é transmitida apenas por cor ou posição visual.
- Observe o comportamento de reflow, zoom e espaçamento de texto do usuário nas superfícies obrigatórias.
- Teste conteúdos e controles relevantes em configurações de alto contraste ou cores forçadas suportadas.
- Envie marcações semânticas, comportamento de tecnologia assistiva, medições de contraste e perguntas formais de conformidade para a trilha de revisão apropriada baseada em evidências.
Não converta preocupação em certificação
Escreva "o foco não estava visível no estado testado" ou "o comportamento do leitor de tela não foi testado". Não escreva "acessível" apenas porque as cores vieram de um design kit ou porque um assistente de IA não encontrou problemas.
Execute a planilha de estados representativos
Escolha superfícies do produto que você está revisando. Uma landing page pode precisar de navegação, um formulário e feedback. Uma aplicação também pode precisar de visualizações de dados, visualizações de detalhes, overlays e estados de permissão. Omita superfícies que o produto não utilize.
- 1
Selecione uma tarefa do usuário
Nomeie um resultado e a condição exata de início. Mantenha a tarefa estreita o suficiente para ser repetível.
- 2
Selecione uma superfície e um estado representativos
Escolha a navegação, formulário, visualização de dados, visualização de detalhes, overlay ou estado de feedback que possua a maior consequência ou exponha uma regra distinta do sistema.
- 3
Aplique um cenário fixo
Registre o viewport, modo, conteúdo, estado de conta ou permissão e a condição dos dados. Reutilize esse cenário após as alterações.
- 4
Escreva o resultado esperado antes da inspeção
Cite o requisito ou a regra de design e descreva o resultado observável. Se não houver uma autoridade definida, pare e encaminhe a lacuna.
- 5
Capture a observação e a evidência
Registre o que aconteceu, onde aconteceu e o menor screenshot, gravação, observação de DOM, saída de console ou resultado de teste necessário para reproduzir o erro.
- 6
Atribua severidade, responsável e disposição
Escolha entre aprovado, revisar ou bloquear. Encaminhe a causa para a camada correta em vez de atribuir todos os problemas à implementação gerada.
Review ID: UI-REVIEW-____
Build or revision: ____
Reviewer: ____
Date: ____
User task: ____
Start condition: ____
Required outcome: ____
Surface: ____
Required state: ____
Viewport or container: ____
Color mode: ____
Input and content fixture: ____
Permission or account fixture: ____
Requirement authority: ____
Design-system authority: ____
Delivery artifact: ____
Expected rule or behavior: ____
Observed result: ____
Evidence reference: ____
Evidence track:
- task completeness: pass | fail | not tested
- design-system conformance: pass | fail | not tested
- resilience: pass | fail | not tested
- accessibility: pass | concern | not tested
Finding route: requirement | design system | delivery mapping | implementation | fixture
Severity: low | medium | high | release blocking
Owner of next decision: ____
Known limitation: ____
Disposition: pass | revise | block
Retest required: yes | no
Retest result: ____Encaminhe cada descoberta para a camada responsável pela decisão
Um defeito visível geralmente é consequência de um problema em outro ponto. Corrigir a regra de CSS mais próxima pode fazer com que uma tela seja aprovada, mas mantém a mesma falha para a próxima geração.
- Lacuna de requisito de produto: O comportamento pretendido, permissão, regra de conteúdo, confirmação, cancelamento ou caminho de recuperação está ausente ou é contraditório. Exemplo: ninguém decidiu se a remoção de um membro precisa de confirmação. Próximo responsável: tomador de decisão de produto.
- Lacuna de fonte do design system: O requisito está claro, mas o sistema autoritativo carece de um papel ou regra necessária para expressá-lo de forma consistente. Exemplo: ações de aviso e destrutivas não possuem tratamento documentado distinto. Próximo responsável: proprietário do design system.
- Lacuna de entrega ou mapeamento: A fonte contém a decisão correta, mas o token exportado, mapeamento de framework, item de registro, arquivo de tema ou artefato instalado a perde ou a atribui incorretamente. Exemplo: a fonte define um papel de anel de foco, mas o tema entregue mapeia o componente para um papel de borda. Próximo responsável: proprietário do artefato ou da integração.
- Defeito de implementação gerada: Os requisitos e as regras entregues são suficientes, mas a interface gerada os ignora, sobrescreve ou os implementa incorretamente. Exemplo: um botão utiliza uma cor hardcoded em vez de usar o papel destrutivo entregue. Próximo responsável: proprietário da implementação ou operador do agente de código.
- Cenário de revisão inválido: A expectativa utiliza dados não suportados, uma plataforma excluída, o estado de conta errado, um build desatualizado ou uma superfície fora do contrato de lançamento. Exemplo: um revisor espera uma ação de administrador ao testar uma conta de apenas leitura. Próximo responsável: revisor ou proprietário do teste.
Se mais de uma camada contribuiu, nomeie a falha autoritativa mais precoce como a rota primária e liste os defeitos subsequentes separadamente. Isso evita que um ajuste local esconda a ausência de uma decisão.
Execute um teste de alteração controlada
A inspeção mostra se o snapshot atual parece conectado ao seu sistema. Uma alteração controlada testa se essa conexão ainda funciona. Altere uma decisão delimitada na autoridade declarada, propague-a através da rota de entrega normal e verifique tanto a atualização pretendida quanto os valores não relacionados.
- 1
Escolha uma decisão semântica
Use um papel reversível e de escopo restrito, como o fundo de aviso, anel de foco, peso do título ou etapa de espaçamento compacto. Não combine várias edições.
- 2
Registre o estado anterior
Capture o valor autoritativo, o valor entregue, os consumidores pretendidos, o cenário representativo e alguns valores próximos que devem permanecer inalterados.
- 3
Altere a autoridade declarada
Faça a alteração onde a equipe define que a decisão pertence. Editar o componente renderizado diretamente não testa a propagação.
- 4
Execute o caminho de entrega normal
Regenere, exporte, instale ou aplique o artefato da mesma maneira que o projeto normalmente recebe as decisões de design.
- 5
Verifique a cadeia
Confirme se a autoridade, o artefato de entrega e o consumidor da interface pretendido contêm a nova decisão.
- 6
Verifique desvios não relacionados
Compare os papéis vizinhos registrados e as superfícies representativas. Qualquer alteração não explicada reprova o teste, mesmo que o alvo tenha sido alterado corretamente.
- 7
Restaure ou aprove o valor de teste
Trate a alteração como um teste, a menos que o responsável a aprove como a nova decisão de design. Registre o estado final na revisão.
Um teste de propagação reprovado estreita a investigação
Se a fonte muda, mas a exportação não, inspecione o mapeamento de entrega. Se a exportação muda, mas a interface não, inspecione a instalação, as sobrescritas e o uso do componente. Se papéis não relacionados mudarem, inspecione o escopo de geração ou o acoplamento de tokens.
Defina critérios de aprovado, revisar e bloquear
- Aprovado: Todas as tarefas obrigatórias e estados representativos atendem aos seus critérios observáveis; as diferenças de conformidade são explicadas; as verificações de resiliência obrigatórias possuem evidências; as limitações de acessibilidade são explícitas; não resta nenhuma descoberta não resolvida que bloqueie o lançamento.
- Revisar: A autoridade está clara e o defeito é delimitado, reproduzível, possui um responsável e é seguro de testar novamente antes do lançamento. O registro nomeia o cenário com falha e o resultado esperado.
- Bloqueio: Uma tarefa obrigatória falha; uma ação destrutiva ou irreversível comporta-se de forma ambígua; as permissões estão incorretas; a recuperação está indisponível onde é necessária; o requisito governante ou a autoridade de design não foi resolvido; faltam evidências para um estado crítico de lançamento; ou a mudança controlada revela propagação quebrada ou drift não relacionado.
A severidade deve descrever a consequência, não a proeminência visual. Um erro sutil de permissão pode bloquear o lançamento. Uma incompatibilidade de espaçamento conspícua pode ter severidade baixa se não prejudicar a tarefa e o proprietário do design a aceitar.
Como os artefatos do Identity Forge se encaixam na revisão
O Identity Forge pode fornecer entradas declaradas para este processo: design tokens semânticos de cores claras e escuras, tipografia, orientações de espaçamento e layout, motivos, regras de uso, DESIGN.md e formatos de entrega como Tailwind, DTCG e artefatos orientados ao shadcn/ui. Essas entradas reduzem a ambiguidade ao questionar se a UI gerada segue um sistema escolhido.
Eles não fornecem requisitos de produto, comportamento de componentes finalizados, uma auditoria de UI concluída ou prova de que uma interface é acessível ou está pronta para produção. Eles também não decidem se uma diferença é uma exceção aprovada. Esse julgamento permanece com as pessoas responsáveis pelo produto, design system, implementação e lançamento.
Se um projeto não tiver uma autoridade de design declarada, estabeleça uma antes de alegar conformidade. Os guias relacionados sobre design systems para agentes de código de IA, DESIGN.md e design tokens semânticos de cores explicam as entradas possíveis. O método de revisão em si permanece independente de ferramenta.
O checklist final de pré-lançamento
- A tarefa do usuário revisada, a condição inicial e o resultado esperado estão documentados.
- As autoridades de requisitos e do design system estão nomeadas e versionadas ou são identificáveis de outra forma.
- Os artefatos de entrega e as plataformas suportadas estão registrados.
- Conteúdo representativo, permissões, modos, viewports e estados obrigatórios estão definidos.
- Caminhos primários, de cancelamento, confirmação, erro e recuperação passam onde for necessário.
- Cores semânticas, tipografia, espaçamento, layout, tratamentos de componentes, motivos e modos rastreiam até a autoridade declarada ou uma exceção aprovada.
- Conteúdos longos, layouts estreitos, zoom ou espaçamento de texto, operação por teclado e estados não padrão relevantes possuem evidências.
- Preocupações de acessibilidade e áreas não testadas são explícitas; nenhuma revisão visual ou de IA é apresentada como certificação.
- Cada descoberta é encaminhada para requisitos, a fonte do design system, mapeamento de entrega, implementação ou fixture.
- Uma mudança autoritativa controlada atinge seu artefato e consumidor pretendidos sem drift não relacionado.
- Todo problema não resolvido possui severidade, um responsável pela próxima decisão e uma condição de reteste.
- O registro de lançamento termina com aprovado, revisar ou bloquear, em vez de um comentário de aprovação vago.
Para a próxima revisão, escolha uma tarefa crítica de lançamento e complete o registro antes de inspecionar o restante da interface. Se o comportamento esperado ou a autoridade de design não puderem ser nomeados, pare por aí e encaminhe essa lacuna. Mais screenshots não resolverão a falta de uma decisão.
FAQ do checklist de revisão de UI de IA
Um assistente de IA pode realizar toda esta revisão de UI?
Ele pode ajudar a inspecionar screenshots, código, componentes e requisitos escritos, mas o resultado ainda precisa de fixtures verificadas, entradas autoritativas, evidências reproduzíveis e a responsabilidade humana sobre as decisões de produto e lançamento. Trate o feedback da IA como evidência para avaliar, não como a decisão de lançamento.
A conformidade com o design system é suficiente para lançar?
Não. A conformidade pode mostrar que a interface segue as regras visuais e de uso declaradas. Ela não prova a lógica da tarefa, permissões, comportamento de dados, resiliência, acessibilidade ou prontidão para produção.
Quantas telas a revisão deve cobrir?
Revise as superfícies e estados exigidos pela tarefa e pelo contrato de lançamento. Use navegação representativa, formulários, visualizações de dados, visualizações de detalhes, overlays e estados de feedback apenas quando o produto realmente os contiver. A cobertura deve seguir o risco e a acessibilidade, não uma contagem fixa de telas.
O que deve bloquear o lançamento?
Bloqueie quando uma tarefa obrigatória falhar, permissões ou ações irreversíveis estiverem incorretas ou ambíguas, um caminho de recuperação obrigatório estiver indisponível, a autoridade governante não for resolvida, evidências críticas estiverem faltando ou uma mudança controlada expuser propagação quebrada ou drift não relacionado.
E se a UI gerada diferir do design system?
Verifique se a regra se aplica e, em seguida, encaminhe a diferença. Pode ser uma regra de sistema ausente, um problema de mapeamento de entrega, um defeito de implementação, uma exceção aprovada ou uma fixture inválida. Não corrija o componente mais próximo até que a causa autoritativa seja conhecida.
Este checklist prova a conformidade de acessibilidade?
Não. Ele ajuda a registrar preocupações visuais e de interação, estados testados e áreas não testadas. Alegações formais exigem a avaliação apropriada baseada em normas, medições, revisão semântica, testes com tecnologias assistivas e evidências para o contexto suportado do produto.
Fontes
- 7-point checklist to review any AI-generated UI: O artigo capturado explica que telas polidas geradas por IA podem ocultar lógicas fracas e decisões de produto ausentes, portanto, o acabamento visual não deve ser tratado como prontidão.
- AI Generated UI Quality Checklist: O checklist recomenda revisar a hierarquia, a consistência do sistema, conteúdo real, comportamento responsivo, layouts móveis e estados não padrão antes de lançar a UI gerada.
- AI design review assistant for modern designers: O Figma apresenta a revisão de design como um fluxo de trabalho de feedback contextual e iteração, incluindo revisões de frames selecionados, componentes e fluxos.
- A pre-ship design review checklist for AI-generated UI: O artigo capturado separa problemas mecanicamente verificáveis da revisão de design qualitativa e abrange paleta, tipografia, layout, espaçamento, estados, foco e movimento.
- forced-colors CSS media feature: A MDN documenta que o modo forced-colors permite que o navegador imponha uma paleta de cores selecionada pelo usuário e pode alterar várias propriedades de CSS relacionadas a cores.
- Identity Forge: O Identity Forge fornece kits de design com tokens semânticos, tipografia, regras de layout, orientações de DESIGN.md e rotas de entrega para fluxos de trabalho de agentes de código.
- Como gerar um DESIGN.md (e o que ele é): Um DESIGN.md pode documentar a intenção do design, sistemas de cores e tipografia, regras de layout e espaçamento, tratamentos de componentes, motivos e restrições explícitas de uso para um agente de código.
- Explicação sobre design tokens de cores semânticas: Design tokens de cores semânticas nomeiam as cores por suas funções na interface e permitem que os componentes se refiram a funções estáveis entre temas claros e escuros.
- Geradores de design system shadcn/ui: você precisa de um tema, de um sistema ou de um handoff para agente?: O artigo distingue um tema visual de um design system mais amplo e recomenda a inspeção do significado dos tokens, mapeamentos de componentes, tipografia, orientações de layout, rotas de instalação e lacunas conhecidas.
Fontes
- 7-point checklist to review any AI-generated UI: O artigo explica que telas geradas por IA com acabamento polido podem ocultar lógicas frágeis e a ausência de decisões de produto; portanto, o acabamento visual não deve ser confundido com a prontidão para lançamento.
- AI Generated UI Quality Checklist: O checklist recomenda revisar a hierarquia, a consistência do sistema, o conteúdo real, o comportamento responsivo, os layouts mobile e os estados não padrão antes de publicar a UI gerada.
- AI design review assistant for modern designers: O Figma apresenta a revisão de design como um fluxo de trabalho de feedback contextual e iteração, incluindo revisões de frames selecionados, componentes e fluxos.
- A pre-ship design review checklist for AI-generated UI: O artigo separa problemas verificáveis mecanicamente da revisão de design qualitativa e abrange paleta, tipografia, layout, espaçamento, estados, foco e movimento.
- forced-colors CSS media feature: A MDN documenta que o modo forced-colors permite que o navegador imponha uma paleta de cores selecionada pelo usuário e pode alterar diversas propriedades de CSS relacionadas a cores.
- Identity Forge: O Identity Forge fornece kits de design com tokens semânticos, tipografia, regras de layout, orientações de DESIGN.md e rotas de entrega para fluxos de trabalho com agentes de código.
- How to generate a DESIGN.md (and what it is): Um DESIGN.md pode documentar a intenção do design, sistemas de cores e tipografia, regras de layout e espaçamento, tratamentos de componentes, motivos e restrições explícitas de uso para um agente de código.
- Semantic color tokens explained: Design tokens de cores semânticas nomeiam as cores por suas funções na interface e permitem que os componentes se refiram a funções estáveis entre temas claros e escuros.
- Shadcn design system generators: do you need a theme, a system, or an agent handoff?: O artigo distingue um tema visual de um design system mais amplo e recomenda a inspeção do significado dos tokens, mapeamentos de componentes, tipografia, orientações de layout, rotas de instalação e lacunas conhecidas.