Olhos Frescos
Desenhe a tela para a pessoa que vai usá-la, a partir do trabalho que ela veio fazer e do conteúdo que verá. O julgamento lidera; as referências o afiam e os scripts o verificam. Nada aqui supera o senso comum: se uma tela é confusa e nenhuma regra nomeia o motivo, ela ainda é confusa.
<skill> abaixo é o diretório deste skill: ${CLAUDE_SKILL_DIR} (se isso aparecer como uma variável literal,
use a pasta de onde este arquivo foi lido).
Configuração
Os scripts precisam do Node 20 ou superior. Quando um script disser que precisa de configuração, execute o que
imprime: um ou ambos de npm --prefix "<skill>" install e node "<skill>/node_modules/playwright/cli.js" install chromium, que funcionam
de qualquer pasta e em qualquer shell.
Se os scripts não puderem ser executados aqui (sem shell, sem Node, sem rede para baixar o navegador), não pare:
tire capturas de tela com qualquer ferramenta de navegador disponível na sessão, ou verifique o código linha a
linha contra references/floor.md, e diga no relatório que a verificação de renderização não foi executada. Nunca
relate uma verificação visual feita apenas a partir do código.
O ciclo
Use-o para criar e para revisar. Para uma revisão, leia references/review.md primeiro: seus passos substituem
os passos 1 a 4, e a versão melhorada é uma cópia ao lado da original, a menos que a pessoa tenha pedido para
seus arquivos serem alterados.
- Entenda. Quem usa esta tela, para qual trabalho, com que frequência, em qual dispositivo, com qual
conteúdo real. Leia o
DESIGN-CONTEXT.mddo projeto, se houver (references/design-context.md). Se não houver, infira a partir do código, da cópia e da solicitação, e anote suas suposições. Não pare para entrevistar o usuário primeiro. - Decida antes de estilizar. Escreva, brevemente, em suas anotações de trabalho ou na resposta, antes de
construir: a única finalidade desta tela; onde o olho deve pousar primeiro; o que a primeira tela deve conter
para a decisão principal, no desktop e no celular; a ordem de todo o resto; a única ação primária; o que você
está deixando de fora. Nomeie dois ou três produtos que os usuários desta categoria já gostam, cujas
estruturas você segue, e o movimento característico que este produto possui (
references/modern.md). Esta é sua intenção, e o passo 6 a testa. - Escreva as palavras primeiro. Títulos, rótulos, botões, estados vazios e de erro, nas palavras da
pessoa, a partir dos dados reais (
references/words.md). Nunca invente figuras, nomes, depoimentos ou tendências; sem dados reais, use um espaço reservado visível. - Construa em ordem: estrutura, depois hierarquia, depois acabamento, com os componentes e tokens do
próprio projeto quando os tiver (para React com shadcn/ui, leia
references/stacks/react-shadcn.md). Um novo sistema visual começa a partir denode "<skill>/scripts/tokens.mjs" --accent "<hex>" --out <dir>, que verifica cada par de cores. - Renderize e olhe. Para um app, inicie seu servidor de desenvolvimento e passe a URL. Escreva
--outpara uma pasta temporária fora do projeto:node "<skill>/scripts/render.mjs" <page.html | url> --out <dir>(se pedir configuração ou não puder ser executado, veja Configuração); atrás de um login, adicione--storage-state <file>. Ele salva capturas de tela desktop e celular, claro e escuro, imprime os problemas que pode medir (contraste, foco, rolagem lateral, alvos pequenos, botões primários concorrentes, bordas coloridas, travessões), depois uma lista de "verificar visualmente". Corrija cada problema, ou nomeie no relatório por que um permanece; uma revisão corrige problemas básicos, bordas coloridas e travessões, e oferece as outras marcas medidas como descobertas. Se avisar que claro e escuro parecem idênticos, execute novamente com--theme-mode class. Olhe as capturas de tela, os quatro-first.pngprimeiro, e cada item de "verificar visualmente": uma lista vazia significa que o básico está limpo, não que a tela esteja boa. Renderize uma vez com conteúdo de estresse: o nome real mais longo, o maior valor, a conta vazia. - Olhos frescos. Inicie um novo subagente que não tenha nada desta conversa (não uma ramificação dela); use
o tipo de agente
first-lookse um estiver listado. Seu prompt completo:Leia <skill>/agents/first-look.md e siga-o. O trabalho: <uma frase>. Imagens: <caminhos absolutos, imagens da primeira tela primeiro>. Não abra nenhum outro arquivo.Não adicione nada sobre sua intenção ou o que você construiu ou mudou. Compare suas respostas com o passo 2: um "o que é isso" errado, um primeiro clique errado, uma hesitação ou um "parece estranho" é uma correção; em uma revisão de uma página que já funciona, uma hesitação que nem bloqueia nem engana o trabalho é uma sugestão opcional, não uma correção. Sem subagentes, responda você mesmo às perguntas do first-look a partir apenas das imagens da primeira tela, antes de reler seu código. - Corrija e pare. Corrija cada hesitação primeiro com estrutura (um rótulo, uma lista, um visual, uma
reagrupamento); adicione uma frase apenas quando nada mais puder carregá-la. Uma dúvida sobre um nome é
corrigida por um nome melhor, nunca por uma linha de explicação abaixo dele, e nada é explicado dentro de um
menu. No máximo mais duas rodadas dos passos 5 e 6, depois nomeie o que ainda está em aberto. Responda às três
perguntas do teste em
references/modern.md(qual produto da categoria chamaria isso de atual; onde está a assinatura; isso poderia pertencer a qualquer startup), e relate.
O caminho mais simples primeiro. A ação principal funciona no momento em que a tela abre; capacidade extra
(editar cada linha, ferramentas em lote) fica um nível abaixo, nunca no caminho da primeira tela
(references/structure.md).
Finalizado, não básico. Evitar marcas não é o objetivo. Uma tela deve parecer um produto finalizado:
unidades nas quais a pessoa age em seus próprios contêineres, ícones e pequenos visuais onde carregam
significado, a decisão inteira na primeira tela. Uma coluna larga de frases cinzas também é uma falha
(references/hierarchy.md).
Dimensione para a solicitação. Apenas palavras (rótulos, uma mensagem de erro): passos 1 a 3. Um componente ou uma pequena correção: passos 1 a 5. Uma tela inteira ou uma revisão: todos os sete.
As perguntas que decidem a maioria das telas
| Pergunte | Leia |
|---|---|
| Quem vem aqui, com que frequência, para qual trabalho? Quão denso deve ser (postura)? Como as coisas são agrupadas, nomeadas e alcançadas? | references/structure.md |
| Onde o olho deve pousar primeiro? Há exatamente uma ação primária? Cada número tem sua comparação, unidade e data? | references/hierarchy.md |
| Um novato consegue dizer o que é isso, onde está e o que fazer a seguir? | references/clarity.md |
| Em que estado está cada região, e é exatamente um? Quando alguém erra, desfazer ou confirmar? | references/states.md |
| As palavras nomeiam as coisas como a pessoa faz? Cada erro diz a correção? | references/words.md |
| A tipografia, o espaçamento, a cor, o modo escuro e a animação são deliberados? | references/craft.md |
| Parece finalizado, ou como um documento? A primeira tela contém a decisão? | references/hierarchy.md |
| Parece atual sem parecer gerado? Qual é sua assinatura? | references/modern.md |
| Esta tela poderia pertencer a qualquer produto? O que pode sair dela? | references/tells.md |
| É uma página de destino, home ou preços? O que um visitante deve decidir? | references/landing.md |
| Teclado, contraste, reflow, nomes, alvos, em ambos os temas? | references/floor.md |
Leia uma referência quando sua pergunta estiver em aberto na tela à sua frente, não todas de uma vez. Cada cartão nelas tem uma Decisão, um Faça, o Porquê com sua fonte, o que Procurar e quando não se aplica (A menos que). As exceções importam tanto quanto as regras.
Linhas que não mudam
- Apenas conteúdo real: sem números, pessoas, citações ou histórias inventados.
- O piso de acessibilidade (
references/floor.md) vale em claro e escuro. - Nenhuma faixa colorida em uma borda de um elemento como acento, e nenhum travessão em cópia (
references/tells.md). - Em uma revisão, mantenha cada dado e cada ação que a página tinha; mova ou despromova, não remova.
- "Nenhuma alteração necessária" é uma revisão completa quando nada custa nada à pessoa. Nunca mude apenas por gosto.
Relatório
Palavras simples, curtas:
- o que você construiu ou mudou, cada um ligado ao trabalho da pessoa e ao que economiza para ela; em uma revisão, cada alteração, por menor que seja (um tamanho, um espaço, uma cor), por exemplo como uma tabela curta de era, agora e o que economiza para a pessoa: uma alteração que você não nomeia é uma promessa quebrada;
- o que você assumiu, no máximo três itens, e o que mudaria se uma suposição estiver errada;
- o que você verificou: os problemas de renderização antes e depois, e como a primeira impressão se comparou com sua intenção;
- o que você não testou (gestos, um celular real, Safari, um leitor de tela), e se a renderização foi executada.
Sem pontuações, IDs ou números de regra. Se o projeto não tiver DESIGN-CONTEXT.md, ofereça-se para escrever um
a partir de suas suposições.