site-upgrade

Atualização de site

Um método para transformar um site que parece montado em um que seu proprietário se orgulha de mostrar. Foi destilado de atualizações reais que foram lançadas e que os proprietários e suas equipes avaliaram muito bem: o site de marketing de um aplicativo móvel, um site de uma empresa B2B de nuvem que passou por duas direções completas e uma central de ajuda construída do zero. Reutilize o método, as receitas e as armadilhas. Nunca reutilize uma aparência: cada site tira sua direção de sua própria marca, produto e público.

O que significa "pronto"

A atualização está concluída quando todas as seguintes condições forem atendidas, e não antes:

• Cada afirmação no site remete a uma fonte que você pode nomear: código do produto, texto legal, o sistema de cobrança ou a resposta escrita do proprietário.
• O design vem do material da própria marca, e sua ideia falha no teste do concorrente (direction.md).
• Um ou dois momentos marcantes que o visitante faz ou assiste; todo o resto é disciplinado.
• Nada precisa de movimento para ser visto. Com movimento reduzido, os estados finais aparecem.
• Foi verificado em um navegador real em 1440, 1920×710, 390 e 320 px, em todos os temas, com movimento reduzido, em uma compilação de produção.
• Sua crítica escrita o pontua como 9/10 ou superior, ou seu relatório diz claramente onde fica aquém (critique.md).
• Ele chega como PRs que a equipe pode revisar, com uma breve atualização que eles podem colar.

Regras básicas

1. Verdade antes do design. Cada recurso, número, preço, data de disponibilidade e prova social remete a uma fonte. O próprio onboarding do produto e o texto de paywall frequentemente prometem demais: verifique no código. "Desconhecido" é uma resposta válida: torne o campo opcional e pergunte, nunca o preencha com um número plausível. Remova provas fabricadas.
2. A marca decide a aparência. Derive a paleta, o tipo e o dispositivo de assinatura do material da própria marca: logotipo, nome, interface do produto, vídeos, lugar. Um dispositivo que pareça gerado (tells.md) é permitido apenas quando o material da marca ou o proprietário o coloca lá, e o contrato de direção o nomeia.
3. O produto é o herói. Interface real e artefatos reais superam ícones, 3D genérico e abstrações. Uma demonstração se parece com a coisa real: uma fatura A4 real, um modelo renderizado real, o catálogo real.
4. Um site, não uma apresentação de slides. Evite pilhas de blocos centralizados de título mais imagem que aparecem gradualmente. Use composição, histórias de rolagem fixa, profundidade em camadas, demonstrações interativas e movimento baseado em estado.
5. Nunca esconda conteúdo atrás de movimento. Uma revelação que nunca dispara deixa uma página em branco. Respeite prefers-reduced-motion mostrando os estados finais.
6. Proprietário no loop, não no caminho. Mostre a direção antes da construção completa. Faça a página inicial primeiro e amplie para as outras páginas depois que ela for aprovada. Faça cada pergunta em aberto uma vez, com opções, e continue construindo em torno dela.
7. Configuração contém valores. As variáveis de ambiente carregam uma URL, um ID ou um token, nunca interruptores liga/desliga ou constantes codificadas. Derive valores dependentes deles. Commit apenas .env.example.
8. Siga o repositório alvo. Leia seus arquivos README, CONTRIBUTING, AGENTS.md e configuração commitlint. Use seu gerenciador de pacotes. Corresponda às versões do framework dele (Next 14 vs 16, Tailwind 3 vs 4, React 18 vs 19).
9. Segredos e partes internas ficam de fora. Nunca imprima, faça commit ou ecoe um token que o proprietário colou. Commits e PRs públicos não carregam nomes de clientes, preços privados ou lacunas de segurança não corrigidas.
10. Nunca considere pronto abaixo de 9/10. Pontue o trabalho a partir de capturas de tela antes de relatá-lo. Uma autoavaliação de 6 ou 7 oferecida após "pronto" é sinal de trabalho ignorado.

Primeiro, escolha o modo

O que o visitante veio fazer decide até onde o design pode ir. Um projeto pode conter várias superfícies em modos diferentes; dê a cada uma o seu próprio.

Modo	Superfícies	O visitante	O que lidera	Leia
Persuadir	produto, marketing, empresa, campanha, preços	decide e age	o produto provando a si mesmo; uma ação real na primeira tela	building-blocks.md
Ler	central de ajuda, docs, changelog, blog	entende algo	a pergunta do leitor; a marca possui o quadro, nunca a coluna de leitura	read-mode.md
Experiência	portfólio, showcase, galeria	explora o trabalho	o trabalho em si, desde o primeiro viewport	building-blocks.md § Experiência

O site de marketing de um produto é Persuadir mesmo que mostre o aplicativo. Sua central de ajuda é Ler mesmo quando é bonita.

Fluxo de trabalho

Trabalhe através das fases em ordem. Leia cada referência quando chegar à sua fase, não antes.

Fase	Faça	Leia
0. Kickoff	Crie um branch a partir do branch padrão, inicie o servidor de desenvolvimento (anote a porta real), capture o conjunto "antes" para o relatório	verification.md § 1
1. Descoberta	Audite o site, encontre as fontes de verdade, escreva o registro de afirmações e o inventário de assuntos, colete material da marca, relate as descobertas	discovery.md
2. Direção	Encontre a ideia e passe no teste do concorrente, defina paleta e tipo, escolha os momentos marcantes, escreva o contrato de direção, mostre-o	direction.md, tells.md
3. Construção estática	Tokens, o herói, cada ato com conteúdo real, as páginas internas. Movimento desligado mentalmente	building-blocks.md, media.md, read-mode.md
4. Movimento e assinatura	Uma introdução coreografada, momentos baseados em estado, a assinatura. 3D apenas quando merece seu lugar	motion.md, three-d.md
5. Contato e conversão	Validação compartilhada, o formulário, uma rota de borda, um e-mail de notificação projetado, agendamento ou pré-preenchimento de lead	contact-email.md
6. SEO e padrões	Renderização no servidor, metadados, cartões sociais, dados estruturados, arquivos de rastreador, cabeçalhos. Seu próprio PR empilhado	seo-standards.md
7. Verificar e criticar	Loops de navegador em cada largura e tema, as verificações com script, uma compilação de produção, então a crítica pontuada, até três rodadas	verification.md, critique.md
8. Entregar	Commits, PRs, a atualização da equipe, o relatório antes/depois, DESIGN.md, notas de memória	delivery.md

Verifique gotchas.md sempre que algo se comportar estranhamente. Leia feedback.md sempre que o proprietário reagir: ele transforma o que os proprietários dizem ("não tem tempero suficiente", "cores desequilibradas", "réplica barata") no que mudar.

Se uma habilidade de direção de design estiver instalada (frontend-design, impeccable, taste-skill), carregue-a na fase 2 para obter alcance extra. Esta habilidade funciona sozinha sem ela.

Stack. As receitas foram enviadas em Next.js, React, Tailwind e GSAP, hospedadas no Cloudflare Pages, e os trechos mostram essa stack. O método, as verificações e a maioria dos scripts não dependem dela: no Astro, SvelteKit, Nuxt ou HTML simples, mantenha a regra e traduza a receita para o framework e versões alvo.

Scripts

Execute a partir da raiz do repositório alvo. <skill> é a pasta desta habilidade.

• node <skill>/scripts/slop-scan.mjs [dir] [--json] [--strict] [--allow <rules>] [--list-rules]: escaneia o código-fonte em busca de sinais de site gerado, prova inventada, texto genérico, links quebrados, segredos e armadilhas conhecidas. Sai com código 1 em erros (ou em avisos com --strict). Nomeie uma exceção permitida com um comentário site-upgrade-allow: <rule> <reason> (ele cobre as linhas abaixo dele até a próxima linha em branco) ou um arquivo .site-upgrade-allow na raiz do repositório. Node 18+, sem dependências.
• <skill>/scripts/ssr-audit.sh <base-url> [path]...: por página (todas as páginas do sitemap quando nenhum caminho é fornecido): status, contagem de <h1>, blocos JSON-LD, canônico, imagem social, saídas de renderização do cliente e o título; então cabeçalhos de segurança e arquivos de rastreador. Sai com código 1 quando uma página falha. Execute-o contra um servidor de produção.
• <skill>/scripts/video-prep.sh <source> <out-dir> [name] [poster-second]: imprime cortes de cena como candidatos a capítulo e escreve codificações web silenciosas com keyframes em cada corte, um pôster e um clipe de pré-visualização quadrado. Recai para o binário imageio_ffmpeg.
• <skill>/scripts/playwright/*.js: para a ferramenta Playwright MCP browser_run_code_unsafe. O MCP lê apenas arquivos dentro do workspace, então copie-os primeiro (mkdir -p .playwright-mcp && cp <skill>/scripts/playwright/*.js .playwright-mcp/) e passe filename: ".playwright-mcp/<name>.js". Mantenha .playwright-mcp/ fora do git.
  • reveal-scroll.js rola para que cada revelação dispare antes de uma captura de tela e lista o texto ainda oculto depois.
  • page-audit.js mede o quadro: um <h1>, cabeçalhos com mais de duas linhas, texto pequeno, alvos de toque pequenos, controles sem nome, imagens sem alt, seções sem título e superfícies de navegador sem tema.
  • overflow.js encontra o que causa rolagem horizontal de 320 a 1440 px e nomeia os culpados mais externos.
  • console-scan.js visita cada URL do sitemap e relata erros de console, erros de página, requisições com falha, 4xx/5xx e violações de CSP.

Ativos e modelos

Copie para o repositório alvo ou bloco de notas e adapte:

• assets/render-email.ts: renderiza modelos de React Email para HTML sem react-dom/server, para rotas de borda.
• assets/JsonLd.tsx: uma tag de script JSON-LD segura para incorporar.
• assets/ScrollTriggerRefresh.tsx: remede os disparadores de rolagem do GSAP sempre que a altura da página mudar.
• assets/templates/claims-ledger.md: enviado, não enviado, desconhecido e números, cada um com uma fonte (fase 1).
• assets/templates/direction-contract.md: a tese, ideia, mundo próprio, primeiro viewport, assinatura e exceções de marca (fase 2).
• assets/templates/critique-round.md: a crítica pontuada, um bloco por rodada (fase 7).
• assets/templates/DESIGN.md: o sistema de design construído, escrito no final para que agentes posteriores permaneçam na marca (fase 8).
• assets/templates/team-update.md: a atualização copiável para o chat da equipe (fase 8).

Pontos de verificação com o proprietário

Confirme isso antes de publicar qualquer coisa que dependa deles. Pergunte uma vez com opções; não pare a construção:

• status de lançamento e disponibilidade na loja, a partir da listagem ao vivo da loja em vez de flags de ambiente
• preços e planos, e sua fonte
• números que ninguém pode fornecer ainda (uptime, datacenters, contagens de clientes): deixe-os de fora até que alguém os aprove
• a caixa de entrada de contato, e uma caixa de entrada que o proprietário possa ler para testes
• itens ainda não lançados em qualquer lista, catálogo ou carrossel
• identidade legal, endereço e telefone, idênticos em todos os lugares que aparecem
• qualquer terceiro que receberia dados do visitante (analytics, embeds, fontes, e-mail), e as linhas de política de privacidade que ele precisa
• os arquivos de origem para qualquer mascote, modelo 3D ou vídeo antes de reconstruir um
• cada etapa de produção: domínios, DNS, configurações de implantação, migrações. O proprietário executa ou as aprova