portão-de-pré-visualização-de-ui

Portão de Pré-Visualização de UI

Cada mudança que altera uma tela passa por quatro fases. Não pule uma fase porque a mudança parece pequena; as imagens são o que os revisores aprovam.

1. Inspecionar o estado atual
2. Pré-visualizar e obter aprovação (antes do início do trabalho)
3. Implementar
4. Verificar se o resultado corresponde à pré-visualização aprovada (após o término do trabalho)

Exceção: uma correção de bug que não altera a tela pretendida pode pular a fase 2. Se os usuários ainda puderem ver uma diferença, reporte imagens antes/depois com a correção. Mostrar uma tela, diálogo, folha ou mensagem diferente do que antes é uma alteração de tela, não esta exceção — mesmo quando reutiliza um componente existente. Obtenha aprovação da fase 2 primeiro.

Quando isso se aplica

• Aplique sem ser solicitado. Os usuários nunca devem precisar nomear essa habilidade.
• Verifique a cada turno, não apenas no primeiro. Uma conversa que começou como suporte, pesquisa, revisão ou relatório de bug frequentemente se transforma em "e se a tela fizesse X?" no meio; a partir desse turno, essa habilidade se aplica.
• "O que você acha?", "alguma ideia?" e "como ficaria?" sobre uma tela contam como propostas.
• Uma vez iniciada, continue seguindo-a em turnos posteriores até que a mudança aprovada seja verificada (fase 4) ou o usuário desista da mudança.
• Uma proposta respondida apenas em prosa ou tabela de casos está incompleta. Anexe a imagem antes/depois na mesma resposta, ou diga por que ela ainda não pode ser feita e quando será.
• Enquanto uma mudança de UI estiver aguardando aprovação ou em andamento, relatórios de progresso, listas de opções e perguntas sobre ela também devem reanexar sua imagem antes/depois ou fornecer o caminho da imagem. Nunca descreva a tela alterada apenas em prosa.

Habilidades são geralmente selecionadas por turno a partir de sua descrição, então turnos no meio da conversa podem ser perdidos. agent-instructions.md ao lado deste arquivo é uma regra curta para adicionar a AGENTS.md / CLAUDE.md para que o agente verifique novamente a cada turno.

1. Inspecionar o estado atual

Nunca proponha a partir da memória ou suposições.

• Capture a tela real de um servidor de desenvolvimento ou build em execução. A janela de visualização padrão é mobile 375px de largura; adicione desktop quando a mudança também afetar layouts de desktop.
• Leia o código que a renderiza: estrutura de abas/rotas, componentes, texto atual.
• Registre evidências como caminho/para/arquivo:linha mais a captura. Cada alegação sobre a UI atual deve apontar para um deles.
• Prefira componentes, padrões e textos existentes. Se um novo padrão for necessário, indique por que os existentes não se encaixam.

Capture com scripts/capture.mjs (consulte Scripts) para que a foto antes, a pré-visualização e a foto de verificação compartilhem uma janela de visualização, escala e estado de dados.

Inventário de casos (faça isso sem ser solicitado, antes da primeira pré-visualização)

O aprovador nunca deve ter que perguntar "e depois de tocar nisso?" ou "e se houver dados?". Antes de enviar qualquer pré-visualização, liste cada caso que a mudança abrange, a partir do código e do aplicativo real:

• Estados da tela alterada: vazio / tem dados / muitos itens (truncamento, "ver todos") / carregando / erro / bloqueado por plano, função ou permissão / outras configurações (loja única vs. múltiplas, flags de recurso).
• Cada tela alcançada a partir de um controle novo ou alterado: formulários, seletores, diálogos, erros de validação, cancelar/voltar, confirmação, sucesso, falha.
• Após a ação: como a tela de origem fica quando a ação é concluída (novo item aparece, contadores mudam) e como desfazer ou editá-la.
• Outros lugares que mostram os mesmos dados: listas, telas de detalhes, histórico, relatórios, exportações, outras plataformas (desktop, Web, LINE, lado do cliente). Marque cada um como: alterado / inalterado-mas-mostra-novos-dados / não afetado.

Envie o inventário como uma tabela com a primeira pré-visualização: caso, o que o usuário vê, componente existente reutilizado e status da imagem (anexada / precisa de dados de teste - como será preparado / fora do escopo - por quê). As pré-visualizações podem chegar em lotes, mas a primeira mensagem sempre mostra o inventário completo, e a aprovação de uma imagem nunca implica aprovação de casos ainda não mostrados. Proponha padrões sensatos para decisões em aberto em vez de apenas listar perguntas.

2. Pré-visualizar e obter aprovação

Antes de escrever código de implementação, mostre ao aprovador uma imagem lado a lado e um breve resumo, então aguarde um OK explícito.

Regras de imagem:

• Antes à esquerda, depois à direita, em uma única imagem.
• Destaque cada região alterada: vermelho no antes, verde no depois.
• Emparelhe os destaques: cada alteração recebe um destaque em ambos os lados no local correspondente. Para uma adição, marque o ponto de inserção no antes com um marcador fino no espaço ("pad": 0, h pequeno); para uma remoção, marque o espaço no depois. Nunca destaque um vizinho não relacionado (por exemplo, a linha abaixo) para representar um elemento ausente.
• Obtenha as coordenadas dos destaques da saída de capture.mjs --selector (ou retângulos de elementos medidos com Playwright em um teste e2e quando o estado exigir interação, por exemplo, um diálogo que abre após entrada de dados), não a olho nu. Olhe para a imagem composta antes de enviá-la para confirmar que cada destaque está sobre seu alvo.
• Mesma janela de visualização, posição de rolagem e dados de amostra em ambos os lados.
• Se a tela ramificar por estado (dados presentes/ausentes, erro, vazio, por função ou por configuração), mostre um par antes/depois para cada estado que a mudança abrange. Um estado que você não mostrou não está aprovado. Faça uma imagem por estado; nunca coloque vários pares em uma única imagem.
• Uma tela real alcançada apenas por staging (código temporariamente alterado para abri-la) deve conter "staged" na especificação para que a imagem informe isso.
• Verificação pré-envio: compose.mjs rejeita especificações que quebram essas regras e imprime uma lista de verificação. Abra a imagem, responda a cada item e coloque as respostas na mensagem (consulte os modelos). Se um item falhar, corrija e recomponha; nunca explique um item reprovado em texto.
• Siga a política de imagem abaixo.

Política de imagem

O usuário ou projeto decide se maquetes são permitidas. Procure a escolha na solicitação ou nas instruções do projeto (AGENTS.md, CLAUDE.md, docs de contribuição). Se nada for declarado, use real-only. Nunca mude para mockup-allowed por conta própria porque capturar é difícil; pergunte.

• real-only (padrão): ambos os lados são capturas de tela cheia do aplicativo real em execução. Construa o lado depois em um branch protótipo ou atrás de uma flag de recurso e capture-o. Nunca use fragmentos recortados ou colados, maquetes redesenhadas a partir do código ou à mão (incluindo imagens geradas), capturas que cortam uma linha ao meio ou dados fictícios que diferem do que o aplicativo real mostra.
• mockup-allowed: o lado depois pode ser uma maquete somente quando o usuário ou projeto explicitamente permitir. O lado antes ainda é uma captura real. Marque cada painel de maquete com "mockup": true na especificação de composição para que a imagem mostre isso, e declare isso na solicitação de aprovação. Uma maquete nunca conta como evidência da fase 4: a verificação sempre usa uma captura real da tela implementada.

Uma regra de projeto mais rigorosa sempre prevalece sobre uma preferência de usuário mais flexível; se entrarem em conflito, aponte isso e siga a regra do projeto.

Resumo (use references/templates.md):

• Onde: qual tela/aba e onde nela a mudança aparece
• O que se torna possível, por tipo de usuário (por exemplo, admin, cliente)
• O que não muda, e as plataformas/superfícies afetadas

A aprovação cobre exatamente o que foi mostrado. Qualquer coisa fora disso precisa de uma nova pré-visualização.

3. Implementar

Construa de acordo com a pré-visualização aprovada. Se a implementação forçar um desvio visível (layout, texto, comportamento, novo impacto de plataforma), pare e retorne à fase 2 com uma pré-visualização atualizada em vez de enviar a diferença.

Isso inclui pequenas edições de texto e correções feitas em resposta à revisão de código: se uma correção mudar o que os usuários veem além das imagens aprovadas, pare e obtenha uma nova pré-visualização aprovada primeiro. Relatar isso depois em texto não conta.

4. Verificar em relação à pré-visualização aprovada

Não reporte conclusão apenas a partir da diferença de código.

1. Recapture a tela implementada com as mesmas configurações de captura e estado usadas para a pré-visualização.
2. Componha uma imagem de verificação: pré-visualização aprovada | resultado real. Destaque cada mudança prometida; destaque cada diferença da pré-visualização aprovada em âmbar, mesmo um pequeno deslocamento. Uma diferença descrita apenas em texto não está verificada.
3. Verifique, item por item:
   • cada mudança prometida está presente e corresponde à pré-visualização;
   • tudo listado como "não muda" está inalterado;
   • nada fora das regiões destacadas se moveu, quebrou ou transbordou;
   • a interação alterada realmente funciona quando executada, não apenas renderiza. Testes e2e que passam confirmam o comportamento apenas; eles não substituem a verificação de imagem para cada estado que deve parecer inalterado.
4. Decida:
   • Correspondência: reporte com a imagem de verificação e o resultado da lista de verificação.
   • Pequena discrepância dentro da intenção aprovada: corrija, recapture, reverifique.
   • Discrepância que altera o que foi aprovado: reporte-a e obtenha aprovação novamente.

Liste separadamente qualquer coisa que você não pôde verificar (uma plataforma, um dispositivo, dados reais) em vez de considerar como concluído.

Scripts

Ambos os scripts precisam de Node 18+ e Playwright (npm i -D playwright && npx playwright install chromium). Defina PLAYWRIGHT_MODULE como um caminho de módulo para reutilizar uma instalação existente.

Capture uma tela e obtenha coordenadas de destaque para elementos:

node scripts/capture.mjs --url http://localhost:3000/menu --out before.png \
  --width 375 --selector ".category-tabs" --selector ".menu-list"

Ele imprime os retângulos dos seletores em pixels CSS, prontos para colar como boxes.

Componha painéis a partir de uma especificação JSON:

node scripts/compose.mjs spec.json

O formato da especificação, tons e o layout de verificação estão em references/compose-spec.md.