review

ultrahand: review

Revise um design de UI da mesma forma que um inspetor especializado faria. Percorra cada fluxo, interação e controle comparando com os princípios da plataforma, as 10 heurísticas de Nielsen e a WCAG 2.2 AA, e verifique se o design ainda se sustenta em outros tamanhos. A saída é uma lista de achados classificados por severidade. Cada achado nomeia o elemento, o princípio e sua fonte, e fornece uma correção concreta.

Todas as verificações estão em references/checklist.md, e cada verificação cita references/sources.md. Para as regras da plataforma em profundidade, use os princípios dos próprios skills de design: mobile, tablet e desktop. Para um projeto com um tema, verifique o design contra ele com o skill theme-review: uso de tokens, reuso de componentes e consistência entre telas são responsabilidade dele, não deste.

1. Obter o design e saber o que ele pode mostrar

Use a evidência mais rica que o usuário puder fornecer. Diga qual tipo você tem, porque isso limita o que você pode confirmar.

• Artefato do canvas ultrahand (um link de artefato claude.ai): leia seu HTML. Ele contém a marcação, rótulos, cores e cada tela e estado. Se uma ferramenta de navegador estiver disponível, abra o artefato. Configure cada visualização através de window.ultrahandCanvas (veja o README do canvas em shared/canvas/): usePreset(id), setSize(w, h), setScheme('dark'), setTextScale(2), setState('error'), navigate(id). Ative mostrar alvos de toque e leia seu resultado (#uh-targets-result), que conta os alvos abaixo do mínimo da plataforma. Chame refresh() depois de abrir uma folha ou menu para que a contagem o inclua. O README do canvas lista os IDs dos elementos da barra de ferramentas. Os stubs de um protótipo (sem rede real, sem teclado na tela) vão em Não verificado, não nos achados. O teclado físico é real: dirija todos os fluxos com ele.
• Build local do canvas (um index.html de build.mjs) ou qualquer página que você possa abrir: trate-o como o artefato e use-o com o driver de entrada (passo 4).
• Código (HTML, SwiftUI, Compose, Flutter e assim por diante): você pode verificar rótulos, papéis, ordem de foco, cores e pontos de quebra, mas não a aparência, a menos que possa executá-lo.
• Captura de tela ou mockup: você pode avaliar layout, hierarquia, texto e contraste e tamanhos aproximados. Você não pode confirmar rótulos, ordem de foco ou comportamento; marque esses achados como Provável ou liste-os em Não verificado.

Marque a evidência de cada achado: Confirmado (visto no código ou medido no canvas) ou Provável (inferido de uma imagem). Nunca apresente um palpite sobre comportamento oculto como fato.

2. Estabelecer o contexto

Escreva estas informações antes de julgar qualquer coisa; um achado só faz sentido contra elas.

• Plataforma: iOS, iPadOS, Android, macOS, Windows ou web. Leia do canvas (size.platform), do código ou do estilo visual. Se não estiver claro, pergunte uma vez.
• Tamanho atual: largura × altura, e a classe de tamanho de largura: compacto < 600, médio 600–839, expandido 840–1199, grande 1200–1599, extra-grande 1600+. Altura compacto < 480, médio 480–899, expandido 900+. Anote a orientação e qualquer divisão.
• Entradas: toque, ponteiro, teclado ou uma mistura. Um tablet ou um laptop com tela sensível ao toque pode ter todos os três.
• Usuários e tarefa principal: quem usa cada tela e a única coisa para a qual ela serve. Pergunte se você não puder inferir; uma revisão sem tarefa se torna uma lista de opiniões.
• Produto ou ferramenta: um design para usuários finais, ou uma ferramenta construída para o proprietário (o próprio canvas, um editor, um visualizador). Uma ferramenta é um aplicativo de desktop usado em uma janela de navegador de qualquer tamanho: revise-a com as regras de desktop e passe 8. Seu chrome recebe as verificações do passe 7 que o passe 8 lista (tamanhos de janela, zoom do navegador, seus próprios temas), não os presets do design, e o passe de composição como qualquer tela.

Escolha as regras da plataforma pela classe de tamanho de janela e entrada, não pelo nome do dispositivo: toque compacto → princípios mobile; toque médio e expandido, ou qualquer divisão → tablet; uma janela com ponteiro e teclado → desktop. Um design responsivo recebe todos os conjuntos que seus tamanhos cobrem.

3. Inventariar o design

Liste cada tela e estado, cada fluxo entre telas, as seções de cada tela (barras de ferramentas e seus grupos, painéis, cabeçalhos de painéis, grupos de formulários, cartões, listas, barras) e cada controle interativo em cada seção (botões, links, campos, alternadores, abas, menus, gestos, alvos de arrasto). O inventário é a cobertura da revisão: uma seção ou controle que você não listou é um que você não verificou.

Revise em três níveis: a tela inteira, cada seção e cada componente. Uma tela cujos controles passam ainda pode ser desordenada, desorganizada e confusa; isso é um achado por si só, não um polimento.

4. Inspecionar em passes

Trabalhe através dos passes em references/checklist.md em ordem. Percorra o design duas vezes: uma para aprendê-lo, outra para encontrar problemas.

Use cada controle com entrada real, em vários tamanhos. Ler a marcação, ou chamar el.click(), dispatchEvent ou um setter, ignora teste de hit, foco, ações padrão e encadeamento de rolagem, então um botão coberto ou uma roda presa ainda parecem bons. Use a página da mesma forma que uma pessoa: eventos confiáveis de mouse, roda, tecla e toque de node "${CLAUDE_PLUGIN_ROOT}/shared/input/drive.mjs" (seu README tem os passos e receitas), ou cliques e teclas reais de uma ferramenta de navegador. Script é apenas para configurar uma visualização e ler o estado depois.

• Faça isso em três tamanhos ou mais: o maior, um médio e o menor suportado (para um design, seus presets; para uma ferramenta, janelas de navegador como 1440×900, 1024×700 e 640×480).
• Em cada tamanho, liste os controles (controls), então use cada um da forma que seu tipo deve ser usado: clique ou toque, digite, arraste e cancele com Esc, clique com o botão direito, abra e feche com o teclado, e role ou deslize sobre cada scroll até o final.
• Alguns controles nativos não podem ser acionados com entrada confiável headless: o popup de um select, seletores de arquivo e seletores de cor e data. Escolha uma opção de um select com o passo choose do driver e liste o restante em Não verificado.
• Leia cada resultado: um controle que está covered, fora de vista sem maneira de alcançá-lo, ou ausente em um tamanho; um scrolled que mostra a roda presa; foco perdido para body; erros de página. Cada um é um achado naquele tamanho.

1. Percorrer a tarefa: para cada fluxo, faça as quatro perguntas de percurso cognitivo em cada etapa.
2. Composição: cada tela como um todo, depois cada seção, contra as regras de composição (shared/composition/principles.md). Execute sua auditoria no maior e no menor tamanho e leia primeiro a captura de tela desfocada, antes de olhar para qualquer controle. Ao revisar uma revisão, compare-a também com a versão anterior: o que o ciclo adicionou, e a tela está mais carregada por causa disso?
3. Controle por controle: cada controle do inventário contra as verificações de controle.
4. Heurísticas: cada tela contra as 10 de Nielsen.
5. Acessibilidade: WCAG 2.2 AA. Calcule o contraste; não olhe de relance.
6. Plataforma: as regras para a plataforma e classe de tamanho do passo 2.
7. Redimensionar e variantes: cada preset, as larguras de divisão, refluxo a 320px, texto a 200%, modo escuro, cada estado de dados, e em dispositivos de toque ambas as orientações e o teclado levantado (janelas de desktop não giram: verifique o mínimo, o máximo e a janela curta).
8. Ferramentas: para uma ferramenta construída para o proprietário, o trabalho permanece visível em todos os tamanhos de janela, o palco desliza além de suas bordas, o zoom tem limites e atalhos e arrastos se comportam.

Registre um problema no momento em que o vir, com onde o viu (tela › elemento, mais o tamanho, esquema e estado). Um problema que aparece em vários lugares é um achado com vários locais.

5. Classificar severidade

Use a escala 0–4 de Nielsen. Pese quantos usuários encontram o problema, o quanto ele os prejudica e se continua prejudicando depois que eles sabem dele. Veja o guia de severidade no checklist.

Classificação	Significado
4 Catástrofe	Impede as pessoas de concluir uma tarefa ou perde seus dados. Corrigir antes do lançamento.
3 Grave	Retarda ou confunde muitas pessoas, ou falha WCAG AA em um fluxo primário. Corrigir em breve.
2 Menor	Retarda algumas pessoas, ou existe uma alternativa óbvia.
1 Cosmético	Polimento. Corrigir se houver tempo.

Não relate 0s. Uma falha de WCAG AA nunca é abaixo de 2.

6. Relatar

Comece com um veredito de um parágrafo: a plataforma, os tamanhos revisados, a evidência que você tinha, a primeira impressão (o que a tela desfocada mostra, e se a tela parece organizada ou desordenada), as contagens por severidade e o principal problema. Pondere uma superfície primária desorganizada contra bugs em termos iguais: ela retarda cada uso, não apenas um caminho. Em seguida, liste os achados, primeiro a maior severidade e em ordem de fluxo dentro de uma severidade, usando o modelo no checklist:

• ID e severidade, ex. R3 · 3 Grave
• Elemento: tela › seção › elemento (ou tela › seção, ou a tela inteira, para um achado de composição), e o tamanho, esquema ou estado onde aparece
• Evidência: Confirmado ou Provável
• Problema: o que dá errado para o usuário, em uma ou duas frases
• Princípio: a regra que ele quebra, com sua chave de fonte (WCAG 1.4.3, NNG-H4, tablet:AND-T2)
• Correção: uma mudança concreta com valores (elevar o rótulo para #595959 para 7.0:1, não melhorar o contraste)

Conclua com o que funciona bem (seja breve), o que você não pôde verificar e por quê (saída do leitor de tela, dispositivos reais, movimento), e uma observação de que um revisor perde problemas que outros detectam, então um segundo revisor ou um teste de usabilidade vale a pena.

Se o relatório for para outra pessoa, ofereça-se para publicá-lo como um artefato. Ofereça-se para aplicar as correções com o skill de design ultrahand correspondente.