tereza/website-builder-agent

/website-build — construir um site corretamente

Destilado da construção, tradução em cinco idiomas, lançamento e reforço de um site de marketing real para uma empresa de aplicativos móveis. Cada regra nas referências surgiu de algo que realmente deu errado ou consumiu tempo. Este arquivo é a rota; as referências contêm os detalhes.

Abra isto	quando você estiver prestes a
references/01-architecture-pipeline-deploy.md	configurar a estrutura de pastas e a cadeia de build, escolher bibliotecas, adicionar uma etapa de build, fazer deploy, configurar hosting/CSP/redirecionamentos, configurar backups
references/02-design-typography-mockups.md	definir tokens e tipo, lidar com fontes e quebras de linha, criar mockups para celular, posicionar ícones/logotipos, construir componentes e movimento
references/03-i18n-seo-geo.md	traduzir, adicionar um mercado, escrever meta/JSON-LD, sitemap/robots/llms.txt, fazer GEO, otimizar performance, configurar análises
references/04-qa-devices-modes.md	testar qualquer coisa; a plataforma de teste, matriz de dispositivos/larguras/modos, navegadores in-app, a11y, fluxos de consentimento, QA adversarial e ao vivo
references/05-process-content-legal-launch.md	executar o projeto: papéis, aprovações, ciclo de feedback, IA, fatos, páginas legais, consentimento, ir ao ar
scripts/qa/	executar a plataforma de QA (raw CDP, nada para instalar) e a matriz de navegadores WebKit/in-app (Playwright)
scripts/backup/snapshot.py	versionar um arquivo antes de uma edição, listar versões, restaurar; ou instalá-lo como um hook PreToolUse

1. Fases (em ordem)

1. Brief (05): objetivo e CTA, mercados/idiomas, lista de páginas, ficha de fatos com fontes, ativos da marca, entidade legal por mercado, rastreamento e consentimento, hospedagem e quem faz merge da produção.
2. Estrutura (01): uma pasta fonte, idioma mestre editado manualmente, croma compartilhado injetado por blocos marcados idempotentes, construtores para todo o resto, _dist (otimizado) e _deploy (hospedagem) como cópias geradas unidirecionais, um bloqueio de build, git desde o primeiro arquivo.
3. Sistema de design (02): tokens por ground, clamp() com rem mais uma pequena inclinação vw, width/height reais em imagens, srcset absoluto, fontes subset auto-hospedadas cobrindo todos os diacríticos, um sistema de movimento por elemento, seguro para reduced-motion e JS desligado.
4. Imagens (02): telas de produto reais exportadas por mercado da ferramenta de design (3x PNG -> WebP). Nunca texto colado em rasters. Corrigir logotipos no arquivo, não com modos de mesclagem.
5. Texto e fatos (05): uma lista de fatos, um termo por conceito, entidade legal por mercado, tratamento formal/informal por público.
6. i18n (03): dicionário mais construtores de correspondência exata de texto, tipografia em tempo de execução, hreflang (+ x-default), tabelas de dados por mercado, QA de idioma.
7. SEO (03): um pós-processador idempotente entre marcadores, um @graph JSON-LD por página, sitemap com lastmod real, robots (crawlers de IA permitidos intencionalmente), um 404 real.
8. GEO (03): llms.txt (+ completo), facts.json, dados de entidade consistentes dentro e fora do site, texto que sobrevive à extração sem JS, então o protocolo de teste GEO, incluindo perguntar aos mecanismos de IA reais.
9. Performance (03): ativos inline -> arquivos com hash, WebP, lazy abaixo da dobra, bibliotecas auto-hospedadas, gerenciador de tags adiado, Lighthouse em dispositivos móveis e desktop.
10. Consentimento, análises, legal (03, 05): barra de consentimento, Consent Mode v2 (decidir basic vs advanced deliberadamente), tags somente após consentimento, cada rastreador listado na política de privacidade, páginas legais necessárias, CSP primeiro em Report-Only.
11. QA (04): a matriz completa de página x largura, modos, navegadores WebKit e sociais in-app, teclado/foco, cenários de consentimento, links/âncoras/troca de idioma, revisão adversarial e, em seguida, telefones reais.
12. Ir ao ar (05, 01): fazer backup do site antigo e DNS, redirecionar cada URL antiga (manter caminhos listados na loja exatos), testar a prévia contra a linha de base, trocar, executar a lista de verificação ao vivo.

2. Regras rígidas

1. Nunca editar manualmente arquivos gerados (versões de idioma, _dist, _deploy). Editar a fonte ou o construtor, depois reconstruir.
2. Nunca inserir manualmente  /<br> em texto que os construtores de tradução correspondem por texto exato. As quebras de linha são feitas em tempo de execução.
3. Uma sessão constrói e publica. O bloqueio de build verifica seu proprietário; aguardar se estiver retido, nunca excluí-lo. Verificar memória livre antes de um build completo.
4. Uma página que renderiza não prova nada: verificar sintaxe de cada script inline, escanear por caracteres de controle, executar a matriz completa.
5. Cada rodada de feedback se torna uma passagem idempotente no build que falha se seu texto alvo desaparecer.
6. A produção é mesclada pelo proprietário. Mudanças de hospedagem, CSP, consentimento, rastreamento e legal vão para o revisor técnico em um branch lateral primeiro.
7. Os fatos vivem em uma lista. Um número que difere entre duas páginas é um bug de confiança e um bug de GEO.
8. Backups: git por site com um commit em cada fase; scripts/backup/snapshot.py (ou seu hook) para tudo entre commits; backup do site antigo e DNS antes de ir ao ar.
9. Retestar overlays, barras fixas e o menu na saída construída e minificada. Minificadores podem remover especificidade de seletores.
10. Testar CSP e consentimento nos navegadores in-app onde seus anúncios são veiculados e em páginas que carregam estado (tokens em URLs).

3. QA em uma respiração

Os caminhos são relativos a esta pasta de skill. Execute node scripts/qa/jscheck.mjs site/_dist primeiro, depois node scripts/qa/audit.mjs <pasta-ou-url> com QA_WIDTHS=1440x900,1280x800,1024x768,768x1024,430x932,390x844,360x780,320x700, depois anchors.mjs, modes.mjs, console-sweep.mjs, shots.mjs (olhe as capturas de tela você mesmo) e inapp.mjs para WebKit mais os navegadores in-app do Instagram/Facebook/TikTok. Cada script segue um contrato de código de saída: 0 limpo, 1 achados (incluindo uma página que falha ao carregar), 2 uso incorreto, 3 não pôde executar (Chrome, axe-core ou Playwright ausentes). Listas de verificação: 04, seções "pré-publicação" e "pós-deploy".