Construindo um site WordPress, do início ao fim
Por que este método existe
Um agente projeta mal quando seu ciclo de feedback é lento. Organizar uma página dentro do WordPress custa de três a cinco minutos por iteração — compor, salvar, serializar, limpar cache, recarregar, olhar. Em HTML local com um servidor de desenvolvimento, o mesmo ciclo leva cinco segundos, e a qualidade do design acompanha o número de iterações de forma muito mais confiável do que qualquer instrução estética.
A segunda metade é uma restrição de entrega: o cliente edita o site sem escrever código. Isso é o que proíbe blocos HTML puros e conteúdo de propriedade do template — e isso restringe a conversão, nunca o desenho.
Em uma frase: o design vive em arquivos, não no conteúdo da página. O WordPress recebe um tema pronto, não instruções de layout.
As duas regras que vêm primeiro
Regra 0 — desenhe a fase 2 como se a fase 4 não existisse. Nenhuma restrição de conversão entra na maquete. Antecipar "sem core/html" enquanto desenha remove silenciosamente profundidade, sobreposições e o objeto central; o resultado converte perfeitamente e não agrada ninguém.
Regra 0′ — nenhuma liberdade estética sai da referência. Com uma referência, um modelo deriva em direção ao seu próprio estilo pessoal: bege quente onde a referência é branco frio, uma serifa expressiva onde ela tem uma sem serifa, um acento que nunca teve. Sete invariantes de registro são lidos da referência e reproduzidos; mudar um é uma pergunta para o cliente, feita antes da codificação. Os invariantes, o portão de registro e o script de medição estão em references/register.md.
As dez regras
Cada uma vem de um erro que foi realmente cometido.
- Exija uma referência visual. Sem ela, a saída regride ao centro estatístico: fonte neutra, gradiente roxo, página branca.
- Nenhuma maquete sem fotos reais. Uma caixa cinza parece uma imagem quebrada.
- Nada chega à produção do WordPress antes de duas aprovações do cliente: a maquete e o plano de implantação.
- A página inicial é uma página, nunca um template —
front-page.htmlcontém cabeçalho,post-content, rodapé. - Zero blocos
core/html. Componha com grupos, títulos, parágrafos, imagens. - As imagens ficam na biblioteca de mídia, com um
idem cadacore/image. - Todas as variantes interativas vivem na página; o script alterna uma classe.
- Nenhum tema de terceiros sob o design.
- Aceite no editor, não no front-end — uma página pode renderizar perfeitamente e ser inutilizável no Gutenberg.
- A fidelidade de pixels é medida, não estimada visualmente: estilos computados e geometria, seletor por seletor.
Fases e seus portões
Não inicie uma fase até que o portão anterior seja aprovado.
| Fase | Quem | Portão de saída |
|---|---|---|
| 0 · Workspace | Agente | Projeto na pasta de trabalho do usuário, acesso de gravação testado |
| 1 · Briefing | Cliente | Levantamento da referência, paleta e tipo extraídos da referência, lista de "o que eu adiciono" |
| 2 · Maquete | Iterativo | Página inicial em HTML, portão de registro aprovado, aprovação do cliente |
| 3 · Conjunto de páginas | Agente | Cada página montada a partir de uma única fonte de cabeçalho/rodapé |
| 4 · Tema de blocos + preparação | Agente | Tema construído; WordPress local configurado por ferramentas repetíveis; portões 1–5 aprovados na preparação |
| 5 · Implantação | Agente, após aprovação do plano pelo cliente | Backup fora da raiz web, então as mesmas ferramentas executadas em produção |
| 6 · Aceitação | Agente | Portões 1–5 aprovados em produção, ou volta para a fase 4 |
Fases 0–3 e o plano de implantação: references/phases.md. Conversão de HTML para blocos: references/block-conversion.md. Os cinco portões com seu código: references/acceptance.md.
A preparação é local, e cada mudança é uma ferramenta. Conteúdo e configuração são escritos por scripts PHP idempotentes (tools/install-site.php, tools/configure-*.php) executados com o PHP CLI em uma cópia local, nunca digitados no wp-admin. Os mesmos scripts são reproduzidos em produção na implantação, e reproduzir um duas vezes não muda nada — isso é verificado, não assumido.
Escolha o ramo
O método é o mesmo para cada site; o que difere é a fase 4 em diante.
| Site | O que muda | Leia |
|---|---|---|
| Portfólio | Páginas, formulários (Contact Form 7 + Flamingo), páginas legais | este arquivo e as fases |
| Loja | Templates de blocos WooCommerce, importação de catálogo, filtros de produto, blocos de carrinho/checkout, consentimento, pagamentos, newsletter, confirmação de pedido | references/store.md |
| Aplicação web | Tipos de post personalizados, funções, REST, blocos dinâmicos, fluxos de conta — a maquete ainda orienta cada tela pública | references/web-app.md |
references/store.md é medido em uma construção real (WooCommerce 11.2.2, checkout em blocos, tema de blocos). references/web-app.md não é: ele mesmo diz isso, e direciona para as skills que são.
Fatos pertencem ao cliente
A maquete inventa texto do briefing; ela nunca inventa fatos. Avaliações, classificações, contagens de clientes, logotipos de imprensa, prazos de entrega, preços de serviços, cláusulas legais e identidade da empresa permanecem como espaços reservados visíveis — à compléter para o que apenas o cliente pode fornecer, à vérifier para o que foi lido no site antigo e pode estar desatualizado. Uma avaliação inventada passa em todos os portões e é o único defeito que pode custar caro ao cliente legalmente.
Em comentários, mensagens de commit e relatórios, diga quais alegações foram medidas (com a data) e quais foram lidas (com a fonte).
Ferramentas
| Arquivo | Quando |
|---|---|
scripts/serve.mjs | Fase 2 — servidor estático sem dependências, tenta a próxima porta quando uma está ocupada |
scripts/assemble.mjs | Fase 3 — constrói cada página a partir de uma única fonte <head>, cabeçalho e rodapé |
scripts/fetch-fonts.mjs | Fase 4 — auto-hospeda Google Fonts: nenhuma requisição ao Google vinda dos visitantes, nada a declarar sob o GDPR |
scripts/novamira.mjs | Fase 5 — chama uma habilidade Novamira via HTTP sem registrar um servidor MCP |
assets/theme-skeleton/ | Fase 4 — tema de blocos mínimo: theme.json com blockGap: 0px, editor.css, fontes no editor |
Referências
| Arquivo | Leia-o |
|---|---|
references/register.md | Antes da fase 1, e antes de mostrar qualquer maquete |
references/phases.md | Fases 0–3, depois a sequência de implantação da fase 5 |
references/block-conversion.md | Durante a fase 4, todas as vezes |
references/acceptance.md | Fases 4 e 6 — os cinco portões e a higiene de medição |
references/store.md | Qualquer site WooCommerce |
references/web-app.md | Assinatura, reserva, painéis, qualquer coisa com usuários logados realizando trabalho |
references/pitfalls.md | Assim que um sintoma te surpreender |
Skills relacionadas: wp-theme-block-fse para theme.json e templates, wp-design-system para tokens, wp-woocommerce para hooks e HPOS, wp-deploy para migrações, wp-plugin-architecture e wp-blocks-gutenberg para código de aplicação, wp-accessibility e wp-performance antes da aceitação.