brandvm/webflow-build

Construção Webflow: design aprovado → Webflow, seção por seção

A pessoa aprova cada decisão de design; Claude constrói, verifica e relata. Uma seção só é concluída quando corresponde ao design aprovado em todas as larguras, funciona depois de todas as formas de chegar até ela e suas etapas manuais estão listadas.

• checklists.md controla cada etapa: a entrega do design, a fundação Webflow, a página de mídia, cada componente, cada página finalizada e a entrega da construção. O progresso é registrado em docs/handoff/progress.json com pnpm progress (checklists.md › Como registrar o progresso), que o painel de Tarefas do Bench mostra.
• conventions.md define a estrutura de página e seção, a nomenclatura de classes e variáveis, e os padrões de componente, CMS e guia de estilo que toda construção segue.
• lessons/ contém o que custou tempo em construções anteriores, por área. Leia o arquivo da área em que você está prestes a trabalhar.
• O protótipo vem primeiro, sempre: ele é construído a partir do arquivo Figma, página por página, no Bench (ou pelo Claude no terminal com os mesmos passos), e o cliente o aprova antes que qualquer coisa seja construída no Webflow. As etapas estão abaixo (O protótipo, a partir do Figma); a skill webflow-prototype tem a configuração do projeto, as entradas, o snapshot e o guia de estilo, e seu figma.md explica como ler o arquivo.
• rules.md contém as regras que toda skill Webflow compartilha (não fazer commit ou push sem um OK, Designer primeiro, sem credenciais no chat, etapas manuais, lições), o encerramento da sessão e como contribuir de volta.
• starter-site.md descreve o site Webflow inicial que um projeto duplica, com o sistema base já incluído.
• A skill webflow-style-guide constrói a página de guia de estilo, a primeira página do protótipo e da construção Webflow, no layout único que todo site usa.
• media.md é a página de mídia: onde os vídeos de um site são carregados para que o Webflow os converta e hospede, construída antes da primeira página que reproduz um.
• Um site que já está ativo não é uma construção: use a skill webflow-audit (auditoria, depois pequenos lotes verificados; também para correções pontuais).
• Após a entrega da construção, a skill webflow-launch assume: QA pré-lançamento, dia do lançamento, entrega ao cliente e os primeiros 30 dias.

Cada item da checklist diz quem o faz:

• [Claude] Claude faz (através do MCP, do repositório ou de um script).
• [Claude verifica] Claude verifica e relata; uma pessoa corrige o que Claude não pode.
• [Pessoa] uma pessoa faz (cliente, gerente de projeto, designer, DNS, contas). Claude pode lembrar e rastrear, nunca assumir.

Início da sessão (toda sessão)

1. Leia o workspace CLAUDE.md, depois o AGENTS.md e GOTCHAS.md deste repositório, depois docs/handoff/ (HANDOFF.md, MANUAL-TODO.md, BUILD-NOTES.md e REVIEW.md uma vez que a fase de revisão tenha começado). Folheie lessons/README.md e leia o arquivo de lições para a área de hoje (trabalho com MCP: lessons/mcp.md). Nunca repita um erro já registrado.
2. Leia a memória do projeto: onde a última sessão parou, etapas manuais em aberto, perguntas em aberto. Execute pnpm progress show para o estágio, as checklists ainda abertas e as tarefas da própria pessoa. Diga em uma linha onde as coisas estão e o que vem a seguir; pergunte qual página ou seção se não estiver claro.
3. Execute Antes de construir em checklists.md antes do primeiro lote Webflow; o estágio Protótipo antes de ser concluído (as entradas são do webflow-prototype). Combine qualquer alteração em conventions.md com o designer. Se uma entrada estiver faltando, peça-a; não adivinhe conteúdo, estados ou campos de SEO.
4. MCP Webflow: chame webflow_guide_tool uma vez, depois reutilize um id de sessão e um id de agente para toda a sessão.
5. O servidor de desenvolvimento do protótipo está em execução e webflow-build.config.json existe (pnpm new-project o escreve; webflow-prototype › Configuração do projeto).
6. O escopo de hoje é uma página (veja Ritmo de trabalho). Diga qual.

Regras permanentes

As regras compartilhadas estão em rules.md. A construção adiciona:

• Pergunte antes de criar, editar ou remover classes e variáveis, um lote de cada vez, com nomes e valores. Uma solicitação que claramente os implica (por exemplo, "construa no Webflow" após aprovar um mock) é o OK.
• Publicar depende se o site está ativo.
  • Nova construção (nenhum domínio personalizado anexado): publicar no domínio de staging webflow.io é aceitável.
  • Site ativo: uma publicação é para todo o site. Ela envia tudo que está pendente, incluindo edições inacabadas de outras pessoas. Publique apenas no staging, verifique o que mais iria ao ar e espere a pessoa digitar "publicar" antes do domínio personalizado (webflow-audit tem os passos).
  • Nunca publique em um domínio personalizado, corte um release ou altere DNS sem perguntar.
• Após cada lote de escrita do Webflow, diga duas coisas: "recarregue o Designer" (uma aba aberta do Designer não mostra alterações do MCP, e salvar de uma aba desatualizada pode sobrescrevê-las), e o que ainda não foi publicado.
• Marque etapas manuais na página. Uma linha em MANUAL-TODO.md que deixa algo visivelmente inacabado (um valor ainda faltando, uma ligação não feita) recebe um marcador ao lado do elemento, ou ao lado de seu espécime no guia de estilo: uma Legenda com data-manual-todo="<letra>" e o texto "Passo manual : <o quê>". Ele aparece na tela e no staging, para que ninguém revise o estado inacabado como o design. Remova-o no lote que marca a linha como concluída; nenhum pode permanecer na entrega da construção ou no lançamento (pesquise o HTML publicado por data-manual-todo).

O protótipo, a partir do Figma

Todo site começa a partir de um arquivo Figma. O protótipo é construído a partir dele, página por página, e aprovado antes que qualquer coisa seja construída no Webflow.

No Bench. Adicionar cliente › a partir de um design Figma configura a pasta do cliente, o repositório a partir deste template e um prototype/ vazio (uma cópia de prototype-starter/). Construir o protótipo a partir do Figma agrupa os quadros em páginas; a pessoa os escolhe e ordena, cada um com seu endereço. Um trabalho de IA então os constrói uma página de cada vez: cada página vem como sua própria mensagem com os IDs dos nós de seus quadros. Cada página construída mantém seu quadro Figma para Comparar › Com Figma. O Bench verifica o arquivo novamente quando o cliente abre e a cada hora, e oferece a atualização das páginas cujos quadros mudaram: mude apenas o que mudou nesses quadros e mantenha as edições feitas no protótipo desde então.

Não no Bench, Claude segue os mesmos passos no terminal: liste os quadros, concorde as páginas, sua ordem e endereços com a pessoa, depois construa uma página de cada vez.

Uma página:

1. Seus quadros. Quadros com o mesmo nome em Desktop, Tablet e Mobile são uma página. Leia cada um com o conector Figma (get_design_context, get_screenshot, get_variable_defs) ou o servidor MCP do aplicativo Figma (figma.md). Sem quadro Tablet: desenhe Tablet entre Desktop e Mobile. Sem quadro Mobile: faça funcionar em um telefone a partir dos quadros maiores e diga isso. Quadros que não são páginas (o guia de estilo) são lidos para tokens, tipo e componentes.
2. Tokens das variáveis do arquivo e estilos de texto, como propriedades personalizadas CSS: alterações nas variáveis do snapshot e novas em src/css/proposed.css (antigo → novo), nomeadas por conventions.md §4; nunca no tokens.css gerado.
3. Fontes que os estilos de texto usam, em public/fonts/ com sua licença, declaradas em src/css/prototype.css e pré-carregadas em partials/head.html.
4. Imagens exportadas do arquivo para prototype/images/: fotos como WebP no maior tamanho que o design usa, ícones como SVG.
5. Apenas o que está no arquivo. Um valor, estado, texto ou imagem que o arquivo não fornece é uma pergunta: pergunte antes de inventá-lo (no Bench, adicione com mcp__bench__todo_add e prossiga).
6. Onde vai: prototype/<pagina>/index.html em seu endereço Webflow (Home é prototype/index.html), adicionado a pages em prototype/vite.config.js. Nav e footer são parciais compartilhados. Altere apenas essa página, mais os parciais e tokens que ela precisa. Não faça commit, push ou publique.
7. Verifique ao lado de seus quadros em Desktop, Tablet e Mobile, e que os links do protótipo Figma funcionam (menus, abas, formulários).

Então a página executa Página de protótipo concluída (o checklists.md do webflow-prototype) e a pessoa a aprova (no Bench: clique com o botão direito em Páginas). O estágio Protótipo em checklists.md rastreia tudo, até a aprovação do cliente por escrito:

• cada página corresponde ao seu quadro Figma em Desktop, Tablet e Mobile (verificação "Corresponde ao quadro Figma" do Bench);
• o arquivo Figma está vinculado ao cliente;
• quadros escolhidos, em ordem, cada um com seu endereço de página;
• cada quadro escolhido construído como uma página de protótipo;
• tokens, fontes e imagens vêm do arquivo; nada inventado;
• os links do protótipo Figma funcionam;
• cada página aprovada no protótipo;
• o cliente aprovou o protótipo por escrito.

A ordem de uma construção

Começa assim que o estágio Protótipo é concluído. A estrutura e os nomes seguem conventions.md. Cada etapa é controlada em checklists.md:

1. variáveis;
2. estilos de tag (definidos uma vez no Designer para que o MCP possa alcançá-los);
3. classes;
4. coleções CMS;
5. a porta do repositório (módulos e CSS do repositório a partir do protótipo) e o loader, para que o staging execute o código real → Fundação concluída;
6. a página de guia de estilo, a primeira página construída (skill webflow-style-guide) → Base do guia de estilo concluída;
7. a página de mídia, quando qualquer página reproduz um vídeo (media.md) → Mídia concluída;
8. componentes, construídos a partir da marcação real da página (nunca de pré-visualizações do guia de estilo), cada um adicionando sua linha no guia de estilo → Componente concluído;
9. páginas, seção por seção → Página concluída;
10. a verificação final do guia de estilo, depois Entrega da construção;
11. a fase de revisão: docs/handoff/REVIEW.md lista o que foi construído por página, cada rodada de feedback e o que resta antes do lançamento, até que a skill webflow-launch assuma.

Um site duplicado a partir do inicial já tem a base dos passos 1 a 3 e o shell da página; o projeto adiciona a ela. Antes de cada importação, execute pnpm wf:preflight; planeje lotes de classes com pnpm wf:styles (veja Verificações).

O loop de seção

Para cada seção, na ordem da página:

1. Leia o protótipo: sua marcação, CSS e o módulo que o anima, com o quadro Figma da página para estados e a especificação de interação. Anote cada hook data-*, id e atributo aria.
2. Verifique o que o Webflow tem: classes (query_styles), componentes e suas props, campos CMS, assets. Reutilize antes de criar; nomeie qualquer coisa nova de acordo com conventions.md (seções 2–4).
3. Construa, preferindo, em ordem:
   • instâncias de componentes;
   • o construtor de elementos para elementos DOM (button, ul/li quando as funções ARIA devem sobreviver, svg, span com tag), com filhos aninhados;
   • importação WHTML para marcação simples, depois corrija o que ele deixa cair (veja a checklist do importador abaixo). O conteúdo da página vive no slot G | Main do componente G | Page W. Em uma página cujo slot ainda está vazio: construa as seções em um wrapper To Slot após G | Page W, peça à pessoa para arrastar o wrapper para o slot, depois desagrupe-o (mova cada filho para antes do wrapper, remova o wrapper). Uma vez que uma seção esteja no slot, construa ao lado dela diretamente (conventions.md §1). Verifique o conteúdo do slot com query_elements; a árvore da página mostra slots como vazios.
4. Conecte atributos, ligações CMS, valores de props, links, configurações de formulário.
5. Publique, depois execute as verificações. Corrija, publique novamente, verifique novamente.
6. Relate: o que foi construído, o que correspondeu, o que difere e por que, etapas manuais e os arquivos aguardando um OK para commit.

Quando uma página estiver completa, execute Página concluída em checklists.md.

Checklist do importador (após cada importação WHTML)

• <button> tornou-se um Link → reconstrua como DOM button, mova os filhos para dentro.
• <img> perdeu todos os atributos e seu link de asset → set_image_asset, re-adicione data-*, loading, tamanho (ou uma classe com aspect-ratio).
• <span> tornou-se um Span de texto → formas como <div>; peças de texto divididas como DOM span (caso contrário, editar o texto do pai as achata).
• Uma lista de classes com uma classe faltando perdeu todas as suas classes → crie classes primeiro, re-verifique styleNames.
• Elementos DOM mantêm um atributo class literal → remove_attribute class.
• Um espaço normal antes de <br> é cortado → Line.&nbsp;<br>Next.
• Atributos booleanos precisam de um valor (muted="true") ou a publicação os descarta.
• Listas são publicadas como role="list" → mantenha funções ARIA em DOM ul/li.

Higiene da tela

• Toda classe em um elemento vazio: padding 0 em todos os lados e font-size: inherit (o .wf-empty da tela adiciona 75px de padding e font-size 0).
• Toda grade define pelo menos um modelo de linha e um modelo de coluna; centralize filhos únicos com flex, não grade.
• Um elemento desenhado apenas por um pseudo-elemento (um glifo de fonte de ícone) recebe um espaço como seu texto (set_settings, chave text), para que não seja em