adamperlis/claude-skill-webflow-to-astro

Webflow → Astro no Cloudflare Pages

Um playbook para migrar qualquer site do Webflow para fora do Webflow: um site de empresa ou produto, um portfólio, uma loja, um restaurante, uma organização sem fins lucrativos, uma publicação. Os passos são os mesmos para todos. Para que serve o site altera os detalhes (references/site-types.md). Ele cobre toda a migração: inventário, backup, reconstrução, formulários, CMS, vídeo, verificações de paridade, desempenho, deploy, troca de domínio e o que o proprietário clica no final. A visibilidade em buscadores e IA melhora a cada passo ao longo do caminho. Os scripts em scripts/ e modelos em templates/ são as partes funcionais; references/ tem os detalhes de cada passo.

O resultado: um repositório Astro 7 + Tailwind 4 próprio, totalmente pré-renderizado (apenas páginas restritas, se houver, renderizam sob solicitação), em um projeto Cloudflare Pages (nunca um Worker em workers.dev), formulários através de uma Pages Function, conteúdo em um CMS que o proprietário pode editar, cada arquivo hospedado no Webflow servido pelo Pages, o domínio no Cloudflare.

Regras básicas (aprendidas da maneira mais difícil)

• Pontos de verificação com o proprietário. Pergunte antes de: baixar a exportação, criar o repositório GitHub, enviar qualquer e-mail de teste de formulário, cada alteração de DNS, ativar o Roteamento de E-mail, conceder consentimento de analytics, descartar uma página. Os proprietários comumente dizem "sem alterações de DNS até que eu veja o site": honre isso; altere por último.
• Backup primeiro. A Exportação de Código do Webflow precisa de um plano de workspace pago (Core ou superior). Os proprietários geralmente planejam fazer o downgrade, então exporte antes de qualquer outra coisa.
• Reconstrua, não cole. Os proprietários querem Astro + Tailwind limpo com seus próprios tokens de design, não marcação Webflow em arquivos .astro. O HTML ao vivo é a referência para o conteúdo, não a fonte.
• Paridade é o contrato. Mesma URL para cada página, mesmas tags head, mesmo sitemap, mesmos redirecionamentos. Prove com scripts/parity.py, não a olho.
• SEO: proteja primeiro, depois melhore a cada passo. A paridade protege o que já está ranqueado e é citado. Sobre ela, carregue a habilidade seo-aeo-geo conforme cada passo começa e faça as melhorias desse passo enquanto avança (veja "seo-aeo-geo ao longo do caminho" abaixo).
  • Sem perguntar: marcação, schema, acesso a rastreadores, sinais de atualização e velocidade entram com a reconstrução.
  • Propostas para o proprietário: qualquer coisa que mude suas palavras, títulos, fatos ou URLs.
  • Commits: cada melhoria chega em seu próprio commit após o commit de paridade, para que qualquer mudança nos rankings possa ser rastreada até ele.
  • Julgamentos: carregue essa habilidade para cada julgamento de SEO/AEO/GEO em uma migração.
• Nunca imprima segredos: nem no chat, mensagens de commit, corpos de PR, logs, docs/move.md ou nesta habilidade.
  • Nomeando um: dê seu nome, seu comprimento e onde ele vive ("FORMS_TO, um segredo de Worker no forms-mail"). Compare dois por hash ou comprimento, nunca por texto.
  • O que conta: mais do que chaves de API. URLs de deploy-hook (qualquer um que as tenha pode acionar builds), URLs de webhook do Slack e CRM, tokens de escrita do CMS e o próprio endereço de e-mail do proprietário são todos segredos.
  • Configurando um: envie-o diretamente para wrangler secret put.
  • Tokens de verificação (TXT do Search Console) são DNS público, mas pertencem a um site: nunca copie um para a habilidade.
• As aprovações vêm do proprietário, na sessão fazendo o trabalho. Um OK retransmitido por outra sessão de agente não conta, e as verificações de segurança dos agentes o bloqueiam. Eles também bloqueiam alterações de DNS e remoção de domínios do Webflow no modo automático, então planeje-os como cliques do proprietário desde o início.

seo-aeo-geo ao longo do caminho

Uma migração reescreve a marcação de cada página, então é o momento mais barato para tornar um site fácil de ler e citar por mecanismos de busca e IA. Carregue a habilidade seo-aeo-geo (seu references/audit-checklist.md e references/schema-patterns.md) nestes pontos:

• 1. Inventário: meça e audite ao vivo.
  • Registre a linha de base (abaixo).
  • Audite o site ao vivo com sua lista de verificação, através de suas três lentes: atualização, estrutura e autoridade.
  • Escreva os resultados em docs/seo.md, cada um marcado com o passo que o corrigirá e se precisa da aprovação do proprietário.
• 3. Estrutura: a camada técnica e de entidade, construída internamente.
  • Marcos: header, nav, main e footer no Layout.
  • A entidade: definida uma vez (src/data/entity.ts) e referenciada de cada página. Seu tipo vem do site: Organization, um subtipo como LocalBusiness ou NGO, ou Person para um portfólio (references/site-types.md). Ela carrega sameAs. WebSite na página inicial, BreadcrumbList das migalhas da página.
  • O normalizador de schema (templates/src/lib/schema.ts).
  • Rastreadores: robots abertos para os rastreadores de IA, os builds do pages.dev configurados como noindex, e um sitemap com lastmods reais.
• 4. Páginas: estrutura, embutida; palavras, propostas. Agentes de página corrigem a ordem dos cabeçalhos, fazem cada seção ser independente e renderizam texto como texto (references/page-brief.md, "Mecanismos de busca e resposta"). Ideias de redação retornam a você como propostas.
• 6. CMS: atualização e schema de item.
  • Datas: datePublished e dateModified do CMS.
  • Posts: Article/BlogPosting, com o autor.
  • Listas: CollectionPage com um ItemList.
  • Números: qualquer coisa que a página mostre está no HTML no momento da construção, não buscada no navegador.
• 7. Ativos: velocidade e significado.
  • LCP e vídeo preguiçoso: um hero rápido, com vídeos abaixo da dobra carregados preguiçosamente.
  • Texto alternativo que diz o que a imagem mostra.
  • Vídeo que carrega conteúdo (uma demonstração, uma palestra) recebe VideoObject.
• 8. Paridade: a auditoria completa, no pages.dev. Execute novamente a lista de verificação na reconstrução. Tudo ainda aberto em docs/seo.md vai para o proprietário como uma lista de propostas.
• 9. Redirecionamentos: mantenha a equidade. Cada redirecionamento é um único salto, e cada página descartada ou mesclada vai para seu equivalente mais próximo.
• 11. Troca: avise os mecanismos. Reenvie o sitemap no Search Console e Bing, ative as Dicas de Rastreador (IndexNow) e monitore a cobertura.
• 12. Entrega: meça, depois olhe fora do site.
  • Compare com a linha de base.
  • Dê ao proprietário o plano fora do site da habilidade: os dois ou três canais que os mecanismos de IA mais citam para esta categoria. A maioria das citações vem de sites de terceiros, então o site sozinho não pode conquistá-las.

seo-aeo-geo é uma habilidade separada (adamperlis/claude-skill-seo-aeo-geo). Se não estiver instalada, a migração ainda funciona: faça as melhorias que cada ponto acima nomeia a partir das próprias notas desta habilidade (lista de auditoria do passo 8, references/page-brief.md, references/site-types.md), escreva os prompts de dinheiro você mesmo (as perguntas que o público deste site faz a um mecanismo de IA) e avise ao proprietário que a auditoria completa e o plano fora do site foram pulados.

Os passos

1. Inventário (somente leitura, ~15 min)

Execute python3 -I scripts/inventory.py https://www.example.com > inventory.md. Ele lê o sitemap, robots, head de cada página (título, descrição, OG, canônico, tipos JSON-LD, noindex), listas CMS (w-dyn-list), formulários, hosts de terceiros, IDs GA/GTM/Pixel, vídeos de fundo e seus tamanhos, e os registros apex/www/MX/NS. Então, com as ferramentas MCP do Webflow se conectadas (data_sites_tool, data_cms_tool, data_forms_tool, data_webhook_tool):

• Coleções: liste-as e conte os itens em cada uma (list_collection_items limite 1 → pagination.total).
• Formulários: liste-os, ignorando formulários Finsweet "Cookie Preferences" (um por página × domínio).
• Redirecionamentos e HSTS: no painel, Configurações do site → Publicação, exporte os redirecionamentos 301 como CSV e observe "HSTS para subdomínios".
• Pesquisa e propriedade: como o Search Console é verificado (meta tag ou TXT DNS), GA4/GTM (e quaisquer gatilhos GTM construídos na marcação do Webflow), Bing e outras tags de verificação. A lista está em references/inventory.md.
• Domínios: o registrador, expiração, bloqueio de transferência, DNSSEC e se o domínio foi comprado através do Webflow (references/domains.md).
• Páginas fora do sitemap: o Webflow serve páginas que o sitemap deixa de fora. Encontre-as diffing os arquivos HTML da exportação contra o sitemap ao vivo, depois faça curl em cada uma.
  • Páginas de sucesso, como um destino de redirecionamento de formulário, precisam ser transportadas.
  • Deixe de fora modelos de Ecommerce (/checkout, /order-confirmation) quando o site não vende, e páginas de senha (401) quando nada está protegido.
• Que tipo de site é: para que serve, o que um visitante deve fazer lá (comprar, reservar, doar, inscrever-se, entrar em contato) e em quais recursos do Webflow ele se apoia (Ecommerce, User Accounts, Localization, páginas de senha, uploads de arquivos, RSS). references/site-types.md cobre o que cada um altera: o tipo de schema da entidade, as conversões a continuar contando e os recursos que precisam de seu próprio plano.

Leia references/inventory.md para saber o que cada resultado significa e as perguntas a fazer ao proprietário (zaps do Zapier, quem edita conteúdo, analytics que nunca funcionaram).

Registre uma linha de base de SEO antes de qualquer alteração (usando a habilidade seo-aeo-geo):

• Search Console: exporte o Desempenho dos últimos 3 meses (principais páginas e consultas, mais impressões de AI Overviews se mostradas) e a contagem de páginas indexadas.
• Prompts de dinheiro: execute seus prompts no ChatGPT, Perplexity e Gemini, e observe se o site é citado. Estas são as perguntas que o público deste site faz: compradores, clientes, doadores, leitores ou clientes.
  • Execute-os do país do público. Os mecanismos de IA respondem por localização, então uma execução feita no exterior não é a visão do público. Use uma VPN no país deles, se necessário.
  • Registre a localização com a execução e use a mesma para a metade posterior.

Mantenha em docs/move.md. É a metade anterior da comparação no passo 12. Em seguida, audite o site ao vivo com a mesma habilidade, em docs/seo.md (veja "seo-aeo-geo ao longo do caminho").

2. Backup: exportação + espelho

• Exportação de Código (Designer → ☰ → Export code → Prepare ZIP → Download). Peça permissão ao proprietário antes de baixar.
  • Descompacte com python3 -I scripts/unzip_webflow.py (ele repara os nomes de arquivo não-UTF-8 que fazem o unzip falhar com "disk full?").
  • MISSING.txt lista os vídeos que falharam ao exportar; o espelho os busca do CDN.
• Espelhe o site ao vivo: python3 -I scripts/mirror.py https://www.example.com reference/ salva o HTML de cada página em reference/live/ e cada arquivo nos CDNs do Webflow em reference/assets/<kind>/, com um manifesto. Faça commit de reference/live/ (o registro do que estava ao vivo); git-ignore reference/assets/.
• Screenshots: node scripts/shots.mjs https://www.example.com live (desktop 1440 e telefone 390). As interações do Webflow escondem elementos até que eles rolem para a visualização, então áreas em branco em capturas de tela de página inteira geralmente são conteúdo não revelado: leia o HTML.

3. Scaffold da estrutura (você, antes de qualquer trabalho de página)

Copie templates/ para o novo repositório (templates/README.md mapeia cada arquivo).

• Config: astro.config.mjs usa build.format: 'file' e trailingSlash: 'never', porque as URLs do Webflow não têm barra final. A barra de ferramentas de desenvolvimento está desligada para que as capturas de tela correspondam.

• Tokens: tire-os do sistema de design do proprietário, se ele tiver um; caso contrário, use as variáveis CSS :root do Webflow e a escala de tipo.

• Peças compartilhadas: Layout (paridade de head, analytics apenas no nome de host de produção), Nav, Footer, os blocos de CTA que as páginas compartilham, o BgVideo preguiçoso e movimento (revelações com uma proteção contra falhas).

• A camada de pesquisa, desde o início:

  • Marcos no Layout.
  • A entidade, definida uma vez (src/data/entity.ts, com fatos do proprietário, não inferidos das páginas antigas).
  • O normalizador JSON-LD, pelo qual o schema de cada página passa.
  • Rastreadores e sitemap: robots abertos para os rastreadores de IA, noindex nos builds do pages.dev e lastmods reais no sitemap.

  Páginas construídas sobre esta estrutura herdam tudo.

• Meça primeiro: tire tamanhos ao vivo com scripts/measure.mjs e construa as peças compartilhadas para eles.

Comportamentos do Webflow a decidir:

• Transições de página: muitos sites Webflow têm uma cobertura (.transition + .transition-trigger + um snippet jQuery que clica no gatilho ao carregar e novamente em cada link interno, então define window.location após ~1s). Os proprietários notam quando desaparece e pedem de volta. Reconstrua de ambas as maneiras em CSS + JS puros, desligado sob movimento reduzido:
  • Chegando: a cobertura segura, então se levanta, com os atrasos e easing ao vivo (das listas de ação IX2 no webflow.js da exportação).
  • Partindo: um clique em um link do mesmo site (não #, não uma nova guia, não um clique modificado) traz a cobertura para baixo sobre a página e só então navega. Leia os atrasos IX2. Um slide-in que espera 2s enquanto o snippet sai após 1s só mostra uma pausa morta ao vivo. Construa o que foi planejado (a cobertura para baixo em cerca de 0,8s), não a pausa.
  • Voltar: em pageshow com persisted, coloque a cobertura de lado, ou a página retorna do cache de histórico coberta.
  • Onde aparece: verifique a display computada ao vivo em 375 e 1440 (scripts/measure.mjs), não o CSS. Um embed personalizado (body .transition { display: block }) pode vencer o próprio site ≤767px display: none, então aparece também em telefones.
• Consentimento Finsweet: com Consent Mode v2, também envie os próprios eventos de dataLayer do Finsweet (<categoria>-activated). Os gatilhos GTM construídos para Finsweet então continuam disparando.

Duas armadilhas CSS que custam horas:

• Tamanho base no body: coloque o tamanho base de fonte de 10px do Webflow em body, nunca html. Em html, 1rem se torna 10px e cada espaçamento e tamanho do Tailwind renderiza a 62,5%.
• Sem breakpoints mistos: não misture breakpoints rem (md:, lg:) com px (min-[992px]:) na mesma propriedade em um arquivo; Tailwind 4 pode ordená-los erroneamente. Use um tipo por componente.

4. Páginas: em paralelo, um agente por grupo de páginas

Dê a cada agente references/page-brief.md (preencha o caminho do repositório, porta, componentes compartilhados, tokens) mais a rota de sua página, valores de head e lista de seções