Visual Narrative Site Delivery (Visualização de Narrativa Interativa)
Princípios Centrais
Perguntar primeiro → Fazer plano → Revisão independente → Auto verificação → Medição real → Implementação em lotes → Cada lote implantável. Qualquer critério de aceitação que não possa ser verificado por script, como "não trava" ou "boa aparência", é proibido: cada critério deve ser capaz de ser afirmado por um headless browser.
Esta skill tem 6 componentes:
- Este arquivo: Processo de 7 fases + lista de perguntas + modelo de revisão + formato de relatório
references/verify-recipes.md: 13 técnicas de medição em tempo de execução + armadilhas de coordenadas/pipelinereferences/pitfalls.md: 22 armadilhas reais (fenômeno → causa raiz → correção → regra geral)references/animation-components.md: Padrões de integração para componentes canvas de terceiros (chave de cache / cleanup / condição de montagem / verificação de congelamento)references/content-sourcing.md: Números devem ter fontes ou serem explicitamente marcados como ilustração didática (obrigatório para科普/médico/dados)assets/:long-stage.tsx+long-stage.css(estrutura de três camadas do palco longo),tokens.css(temas duplos),verify-skeleton.mjs.md(esqueleto do script de verificação)
Relação de leitura por gatilho: Se for integrar componentes de animação de terceiros → leia animation-components; se a página tiver números ou conclusões científicas específicas → leia content-sourcing; caso contrário, siga a ordem das fases.
Fase 1: Pergunte primeiro, não adivinhe
Quando houver qualquer suposição não verificada nos requisitos, não escreva código. Desenhe as decisões pendentes como uma árvore, perguntando apenas aquelas cujas pré-condições já estão estabelecidas. Cada pergunta deve vir com uma resposta recomendada + justificativa, para que o usuário possa dizer sim diretamente. Tudo que puder ser verificado por conta própria (ler arquivos, executar comandos, consultar documentação) não deve ser perguntado ao usuário.
Lista obrigatória de perguntas (em ordem de dependência, pode ser adaptada ao projeto):
- Qual é o tópico específico (domínio/subdomínio/ângulo de apresentação)
- Para quem é (determina densidade de termos e tolerância a erros) — "perspectiva do avaliador/revisor" é uma necessidade oculta que deve ser ativamente explorada: perguntar "quem decide se está bom?" é mais eficaz do que "quão profundo escrever?"
- O que a pessoa deve entender na primeira olhada na página (uma frase de definição; oferecer opções como "impacto numérico/pergunta interativa/surpresa de contraste")
- Fonte dos dados: real rastreável / ilustração didática / mista
- Tom visual: imersivo escuro / profissional claro / alto contraste
- Formato de entrega: landing page única / rolagem longa com vários capítulos / várias páginas
- Precisa de 3D? (benefício vs custo de verificação)
- Aprimoramentos interativos: palco longo / mouse follow / componentes de animação de terceiros
- Localização do diretório do projeto
- Como o material de referência fornecido pelo usuário será usado (integração de código-fonte vs apenas referência visual)
- URL online / método de implantação
É normal que o usuário revise decisões no meio do caminho (ex: claro → temas duplos). A tabela de decisões deve manter um registro de "decisão original descartada", sem sobrescrevê-la silenciosamente.
Fase 2: Faça o plano, aguarde revisão
Escreva o plano em docs/plan-<tópico>.md e o submeta ao repositório. Deve conter:
- Análise do estado atual: ao modificar um projeto existente, cada frase deve vir com
file:line; ao criar um novo projeto, liste os arquivos a serem criados - Tabela de decisões D1–Dn: cada uma deve explicar "por que essa escolha", não "pretendo fazer isso"
- Lotes: cada lote deve ser independentemente implantável e reversível
- Critérios de aceitação devem ser verificáveis por script: "não trava" → "mediana do intervalo entre rAF ≤ 33ms"; "boa aparência" → "blur(3px) opacity .55 nos cards adjacentes"
- Deixe claro "o que NÃO será feito": liste exclusões para evitar expansão durante a implementação
Fase 3: Aguarde confirmação explícita
"Hum", "ok", "tá" são considerados vagos; confirme novamente. "Decida você" não conta como confirmação.
Fase 4: Revisão independente
Envie um subagente com contexto totalmente novo para revisar o plano. Ele não pode apenas ver o plano; deve receber também o código real e o script de verificação.
Você está revisando um plano que ainda não foi implementado. Sua tarefa é encontrar problemas, não aprovar.
## Leitura obrigatória
- Documento do plano: <caminho>
- Código real: <raiz do projeto>, com foco em <arquivos>
- Ferramenta de verificação: <caminho do script>
## Verifique por prioridade
1. Precisão factual (maior valor): cada `file:line` está correto? Cada afirmação sobre o comportamento existente é válida? Refute com linhas reais do código.
2. Completude: alega implementar N decisões, verifique se há tarefas para cada uma.
3. Contradições internas: o que a seção A promete, a seção B proíbe?
4. Riscos técnicos específicos: liste 3-5 pontos com maior probabilidade de erro nesta tarefa.
5. Omissões: o que o plano não escreveu e que o implementador precisará inventar?
6. Verificabilidade da aceitação: cada critério pode ser julgado objetivamente? Quais são vagos?
7. Ordem dos lotes: há dependência de lotes posteriores? Há algo que não pertence a nenhum lote?
## Saída
Lista numerada, cada item: gravidade (BLOCKING/MAJOR/MINOR), local, o que está errado (com evidência), como corrigir.
Conclusão final: pode prosseguir para implementação?
Não modifique nenhum arquivo. Não aprove por educação — uma revisão que não encontra nada é uma revisão fracassada.
Fase 5: As opiniões da revisão devem ser verificadas por você
O subagente pode errar. Verifique cada item no código para confirmar se procede antes de corrigir. Presuma que "uma das opiniões provavelmente está errada".
Dois resultados reais observados:
- Em uma revisão, todas as 16 opiniões estavam corretas (7 MAJOR + 9 MINOR, sendo 3 sobre "o mecanismo de vericação em si é falho" — asserção sempre verdadeira ou nunca falha)
- Em outra, ele atribuiu a verificação de idle do componente A ao componente B; descoberto lendo o número da linha no código-fonte
Fase 6: Medição real para correção
O agente de revisão infere pela leitura do código, não consegue ler tamanhos em tempo de execução, taxa de quadros ou comportamento de composição. Use um headless browser para medir. Todos os números documentados devem ser valores reais medidos.
Veja references/verify-recipes.md.
Fase 7: Implementação em lotes
Ao final de cada lote: execute a verificação completa → git tag → faça o commit. A mensagem de commit deve conter "o que foi alterado, por que, dados medidos".
Relatório fixo em três seções:
- O que foi feito: lista de arquivos + dados medidos (não "concluído", mas
pinTop=68.0,desvio travel 0.0px) - O que ainda falta
- O que foi descoberto: o plano estava errado ou o código? Em qual linha?
Composição mínima do sistema de verificação (neste projeto: 45 asserções / 7 testes unitários)
| Camada | Ferramenta | O que verifica |
|---|---|---|
| Tipo | tsc --noEmit | Integridade de tipos. vitest tudo verde ≠ consegue construir; esbuild remove tipos |
| Unitário | vitest run | Honestidade dos dados (campos de fonte não vazios, dois tipos devem coexistir), funções puras |
| Runtime | scripts/verify.mjs (puppeteer-core + Chrome do sistema) | Overflow de layout, contraste, taxa de quadros, estado de animação, ramos de degradação |
| Entrega | npm run build | O artefato real consegue ser construído |
Asserções devem poder falhar. Após escrever cada asserção, inverta o código uma vez para confirmar que ela FALHA. Caso contrário, você não saberá se ela é sempre verdadeira ou está realmente testando.
Asserções que dependem da viewport devem usar setViewportSettled. page.setViewport garante apenas que o tamanho da viewport foi submetido, não que o reflow foi concluído; ler scrollWidth logo em seguida pode pegar o valor antigo antes da redução, resultando em falhas intermitentes (veja references/pitfalls.md item 21). Esses problemas intermitentes só aparecem com execuções repetidas — uma única execução toda verde não é evidência de aceitação.
Equívocos comuns
| Equívoco | Realidade |
|---|---|
| "Testes unitários passaram, pode entregar" | esbuild remove tipos; tsc pode apontar erros enquanto vitest ainda está verde |
| "Diff de screenshots cobre todas as mudanças visuais" | O pipeline de screenshots headless pode não capturar repinturas de DOM, apenas texturas de canvas |
| "Esperar 500ms em polling é suficiente" | scroll-behavior:smooth + scrub:1 são assíncronos; é necessário instant explícito + polling até a condição ser atendida |
| "Responsivo é só mudar viewport e testar uma vez" | Estado de pin/toque/CDP pode contaminar entre casos; é necessário nova página ou novo processo do navegador |
| "reduced-motion é desligar animação" | Desligar animação, mas a informação não pode ser reduzida; deve-se afirmar que a quantidade de texto não diminuiu |
Relação com outras skills
- Direção visual / evitar estilo de IA:
frontend-design,design-taste-frontend - Disciplina de planos e revisão:
writing-plans,plan-sds-review - Localização de defeitos:
systematic-debugging - Verificação antes da conclusão:
verification-before-completion
Esta skill complementa apenas o que elas não cobrem: critério de coleta de dados em tempo de execução, armadilhas específicas de visualização, estrutura de narrativa de rolagem longa.