construção-de-páginas-webflow

Construindo Páginas Webflow

Visão Geral

As ferramentas de escrita do Webflow MCP reportam sucesso em operações que silenciosamente fizeram algo diferente do que você pediu. Nomes de classes são renomeados, imagens não se vinculam a nada, estilos caem no breakpoint errado. Cada escrita deve ser lida de volta.

Princípio central: uma resposta de sucesso não é evidência. A árvore de elementos é.

Para itens do CMS, posts de blog e SEO de página, use um skill focado em publicação do CMS. Este skill é a superfície do Designer: elementos, estilos, assets, código personalizado.

A Lei de Ferro

Nunca publique em produção sem aprovação explícita na conversa atual.

Uma publicação de site envia todas as alterações do Designer preparadas em cada página, incluindo trabalho que você não fez e páginas não listadas que ainda são acessíveis em produção. "Eu já disse para você publicar antes" não é válido entre tarefas. Pergunte novamente.

Staging é diferente, e é como o trabalho é revisado. Publicar no subdomínio de staging apenas (uma lista de domínios personalizados vazia) é o passo normal após uma correção, seguido por QA em staging. Publique apenas no domínio de produção primário, nunca em todos os domínios do site, e somente após aprovação.

As nove armadilhas

1. whtml_builder renomeia classes conflitantes

Peça hp2-proof quando um estilo com esse nome existe e você obtém hp2-proof-1. Peça hp2-proof-n e você obtém hp2-proof-n-1. Colisões em cadeia produzem hp2-proof-link-1-2. Divs wrapper frequentemente não recebem classe alguma.

Nada gera erro. Seu CSS head então tem como alvo uma classe que não existe, e qualquer querySelectorAll('.hp2-proof') em um script registrado corresponde a zero elementos, então animações de scroll nunca são executadas.

Sempre use query_elements por estilo após inserir, leia os styleNames reais e escreva seus seletores CSS e de script contra eles. Wrappers sem classe são acessíveis como .parent-class > div.

2. Uma classe em html só se aplica se já existir

Uma classe referenciada no parâmetro html só se vincula se esse estilo já existir no site OU for definido no mesmo css da chamada. Caso contrário, o elemento é inserido sem classe e ainda reporta sucesso. Defina toda classe que você usar em css.

O builder também não suporta seletores descendentes. Use classes únicas e classes combinadas (.a.b). @media e clamp() são aceitáveis.

3. whtml_builder precisa de um único elemento raiz

Múltiplos irmãos no nível superior falham ou são inseridos parcialmente. Envolva em um único contêiner.

4. Imagens inseridas como marcação não são vinculadas

Um <img> em html retorna partial_success com "não existe na biblioteca de assets". Insira o elemento e então vincule-o com set_image_asset e o id do asset.

5. update_style escopa por breakpoint_id, não por breakpoint

Uma chave breakpoint é silenciosamente ignorada e a escrita cai no breakpoint base, sobrescrevendo o desktop. A resposta mostra uma chave breakpoints apenas quando a escrita escopada funcionou. Passe breakpoint_id explicitamente e leia-o de volta.

6. set_style substitui, não adiciona

set_style remove todos os estilos existentes e aplica apenas o que você passa. Para adicionar uma classe, leia os styleNames atuais primeiro e passe a lista completa.

7. set_page_freeform_code substitui o bloco inteiro

Código personalizado head e footer da página residem em data_scripts_tool, não nas ferramentas de páginas ou estilos: get_page_freeform_code e set_page_freeform_code, com location: "head".

A escrita é tudo ou nada. Não há anexação. Sempre use get no bloco atual, modifique a string e use set com ela inteira de volta. Escrever um fragmento deleta silenciosamente tudo o mais que estava no head. Também rejeita tags <script> em alguns planos, e é por isso que scripts vão em embeds (abaixo).

8. Páginas criadas via API não herdam seu CSS base

Se o site define seu tamanho de fonte raiz em um componente CSS base (por exemplo html{font-size:.625rem} para que 1rem seja 10px), uma página criada via API não recebe esse componente. Tudo renderiza 1,6 vezes maior no Designer e na publicação. O primeiro elemento em cada nova página é o componente CSS base. Verifique-o antes de estilizar qualquer coisa.

9. Saídas de criação de assets desaparecem e vinculações têm limite de taxa

A saída de create_asset abaixo de um certo tamanho não é persistida, então um lote de 22 assets é impresso inline e deve ser transcrito imediatamente. set_image_asset faz uma leitura e uma escrita cada: cerca de dez vinculações por minuto antes de um 429. Vincule em lotes de dez com um minuto de intervalo e mantenha uma tabela de linhas de nome, id do asset, data e assinatura.

Código personalizado e scripts

A API de scripts de página está bloqueada em algumas contas. Para executar JavaScript em uma página:

1. register_inline_script (máximo 2000 caracteres) ou register_hosted_script
2. Referencie a URL hospedada retornada de um <script src> dentro de um elemento HtmlEmbed na página, editado via data_element_settings_tool com chave code

Estruture a página como um embed por seção mais um embed loader que traz a biblioteca de animação e então seus scripts. Version o nome de exibição (sections.v17) em vez de mutar um script registrado: update_registered_script falha em scripts inline, e um nome versionado reverte editando uma URL no embed. Hospede o CSS da página da mesma forma, versionado.

Visualizando um rascunho

Uma página de rascunho não pode ser alternada para publicada via API, e ramificação de página é um recurso Enterprise. Então faça QA de um rascunho contra uma réplica local: a marcação de navegação e rodapé ao vivo, o CSS do site, a regra CSS base e a biblioteca de animação de um CDN.

Em uma guia oculta ou painel headless, o ticker de animação pausa. Force-o:

gsap.ticker.lagSmoothing(0); gsap.ticker.tick();

Screenshots de um painel oculto pintam em branco abaixo da dobra. Traduza o corpo para trazer uma seção à vista para um screenshot e chame ScrollTrigger.update() após um scrollTo real.

Assets

Três etapas, e a terceira é a que as pessoas esquecem:

1. create_asset com o nome do arquivo e o MD5 dos bytes brutos (32 hex minúsculos)
2. POST os bytes para o uploadUrl retornado como multipart/form-data, anexando cada campo uploadDetails mais o arquivo sob file. Espere 201.
3. create_asset novamente com o mesmo nome e hash para finalizar.

A URL do CDN é https://cdn.prod.website-files.com/<siteId>/<assetId>_<filename>. Veja asset-upload.md para uma receita curl funcional.

Vídeos são enviados através do mesmo formulário (video/mp4, video/webm) e são referenciados de um embed com autoplay muted loop playsinline e um poster. Vídeo de homepage é onde a largura de banda vai, então sirva loops pequenos e arquivos leves para telefones.

Limites de taxa

Leituras (query_elements, get_all_elements, get_settings) hidratam os endpoints de assets e coleções e começam a retornar 429 após trabalho pesado com assets. Escritas continuam funcionando. Quando query_elements dá 429, get_all_elements com profundidade 2 geralmente ainda funciona.

Leituras em lote: uma chamada query_elements pode fazer múltiplas consultas.

Checklist de verificação

Execute isso após cada sessão de construção e relate os resultados, não suas intenções.

• query_elements por nome de estilo para cada classe que você introduziu; os nomes reais correspondem ao que seu CSS e scripts têm como alvo
• Cada imagem inserida tem um assetId em suas configurações
• Estilos de breakpoint são lidos de volta no breakpoint que você pretendia
• O bloco head/footer ainda contém tudo o que tinha antes de sua edição
• A URL do script registrado no embed corresponde à versão que você acabou de registrar
• URLs de CDN de assets retornam 200 com o tipo de conteúdo e tamanho esperados
• O componente CSS base é o primeiro elemento na página
• A página preparada corresponde ao que você construiu: busque o HTML de staging e verifique, não assuma

Bandeiras vermelhas

• "A ferramenta retornou sucesso, então a classe está aplicada"
• "Vou escrever o CSS agora e verificar os nomes das classes depois"
• "É uma mudança pequena, vou escrever o bloco head diretamente"
• "O usuário aprovou a publicação mais cedo neste projeto"
• "Vou publicar em todos os domínios para ficar consistente"

Todas essas significam: leia a árvore de volta antes de continuar.