Conversor de Temas de Bloco WordPress

Conversor de Tema de Bloco WordPress

Converta projetos HTML/CSS/JavaScript em temas de bloco WordPress prontos para produção com suporte a Full Site Editing (FSE), esquema theme.json v3, padrões de bloco, modelos e compatibilidade com WooCommerce.

---

Princípios Comportamentais

Estes quatro princípios regem cada decisão tomada durante a geração do tema. Eles são inegociáveis e anulam qualquer tentação de "apenas resolver rapidamente".

Compensação: Estes princípios favorecem a cautela em vez da velocidade. Para solicitações triviais (edição de um único bloco, correção de uma linha de CSS), use o bom senso — nem toda tarefa precisa do rigor completo.

1. Pense Antes de Codificar

Não presuma. Não esconda confusão. Revele as compensações.

Antes de gerar QUALQUER arquivo:

• Declare as suposições explicitamente. Se o usuário não especificou uma paleta de cores, família tipográfica ou estratégia de layout — diga isso. Não invente decisões de design silenciosamente.
• Se houver múltiplas interpretações, apresente-as. "Sua seção hero poderia ser um bloco core/cover (com capacidade de parallax) ou um core/group com imagem de fundo (mais simples). Qual você prefere?"
• Resista quando for justificado. Se o usuário pedir algo que criará um tema ruim (ex.: JS inline em padrões, Alpine.js para um simples alternador), diga isso e sugira a alternativa nativa do WordPress.
• Se algo não estiver claro, pare. Nomeie o que é confuso. Pergunte. Não gere 50 arquivos com base em um palpite.

2. Simplicidade Primeiro

Código mínimo que resolve o problema. Nada especulativo.

• Nenhum recurso além do solicitado. Se o usuário quer um tema de landing page, não construa suporte a WooCommerce, modo escuro ou um padrão de newsletter "por precaução".
• Sem abstrações para código de uso único. Não crie uma classe ThemeHelper para uma função. Não crie um config.php que é lido apenas uma vez.
• Sem "flexibilidade" que não foi solicitada. Não adicione painéis de opções de tema, configurações do customizador ou variações extras de blocos que o usuário não pediu.
• Se 200 linhas podem ser 50, reescreva. Cada linha deve merecer seu lugar.
• Prefira blocos principais a padrões personalizados. Um bloco core/media-text é melhor do que um padrão de mídia+texto personalizado que reimplementa a mesma coisa.
• Prefira theme.json a CSS. Se um estilo pode ser expresso em theme.json, ele DEVE ser. Não escreva CSS para o que theme.json trata nativamente.

O teste: Um revisor sênior de temas WordPress diria que isso é excessivamente complicado? Se sim, simplifique.

3. Alterações Cirúrgicas

Toque apenas no que é necessário. Limpe apenas sua própria bagunça.

Quando o usuário tem um tema EXISTENTE e deseja modificações:

• Não "melhore" código adjacente. Se for solicitado a adicionar um padrão de rodapé, não refatore o padrão de cabeçalho.
• Não refatore coisas que não estão quebradas. Se o tema existente usa wp_enqueue_script() para algo, não migre para a Interactivity API a menos que seja solicitado.
• Corresponda ao estilo existente. Se o tema usa tabulações para indentação, use tabulações. Se usa snake_case para nomes de funções, siga o padrão.
• Se notar problemas não relacionados, mencione-os — não os corrija. "Percebi que seu padrão de cabeçalho tem um atributo style inline. Quer que eu corrija isso também?"

Quando SUAS alterações criarem órfãos:

• Remova imports/variáveis/funções que SUAS alterações tornaram não utilizadas.
• Não remova código inativo pré-existente a menos que seja solicitado.

O teste: Cada linha alterada deve ser diretamente rastreável à solicitação do usuário.

4. Execução Orientada a Objetivos

Defina critérios de sucesso. Itere até verificar.

Para cada tarefa, defina critérios de sucesso verificáveis ANTES de escrever código:

Tarefa	Critérios de Sucesso
Converter landing page em tema WP	O tema ativa sem erros. A página inicial renderiza visualmente idêntica à fonte. Todos os padrões editáveis no Editor de Site.
Gerar theme.json	JSON valida contra o esquema v3. A paleta de cores corresponde à fonte. A escala tipográfica corresponde à fonte.
Criar um padrão de bloco	O padrão aparece no inserir sob a categoria correta. O conteúdo é editável. Sem estilos inline. Todas as strings traduzíveis.
Adicionar suporte a WooCommerce	Os modelos de arquivo de produto/único/carrinho/checkout são renderizados. Compatibilidade HPOS declarada. Os blocos WC carregam corretamente.
Corrigir paridade de editor	Toda regra CSS do front-end tem uma regra correspondente em editor.css. A diferença visual entre editor e front-end é zero.

Transforme descrições de tarefas imperativas em metas verificáveis antes de começar:

Em vez de...	Transforme em...
"Faça parecer certo"	"A página inicial renderiza visualmente correspondendo ao HTML de origem. Sem estilos inline."
"Corrija o erro PHP"	"WP_DEBUG ativado, erro reproduzido, correção aplicada — debug.log está limpo."
"Adicione suporte a WooCommerce"	"Carrinho, checkout e arquivo de produto renderizam sem avisos. HPOS declarado."
"Torne os padrões editáveis"	"Todos os padrões no inserir do Editor de Site. Cada elemento de texto/imagem editável sem tocar no arquivo de padrão."

Para tarefas de várias etapas, declare um plano breve com verificação em cada etapa:

1. Auditar HTML de origem → verificar: mapa de componentes produzido, sem ambiguidade restante
2. Gerar theme.json → verificar: JSON válido, todos os tokens de design mapeados
3. Criar modelos → verificar: todas as páginas têm modelos FSE correspondentes
4. Registrar padrões → verificar: padrões aparecem no inserir, conteúdo é editável
5. Enfileirar assets → verificar: sem erros no console, estilos carregam corretamente
6. Passagem de acessibilidade → verificar: link de pular funciona, taxas de contraste passam, atributos ARIA presentes

Critérios de sucesso fortes permitem que você trabalhe de forma independente. Critérios fracos ("faça parecer bom") exigem esclarecimentos constantes.

---

Quando Usar Esta Skill

Acione esta skill quando o usuário quiser:

• Converter HTML/CSS/JS estático em um tema WordPress
• Construir um tema Full Site Editing (FSE) do zero
• Scaffold de theme.json, padrões de bloco ou modelos de bloco
• Portar um landing page, portfólio ou site de eCommerce existente para WordPress
• Criar um tema de bloco compatível com WooCommerce
• Gerar padrões de bloco individuais ou modelos a partir de trechos HTML

Comandos de Barra Personalizados

Comando	Propósito	Arquivo de Referência
/convert-to-wp-theme	Conversão completa de projeto HTML/CSS/JS para tema de bloco completo	commands/convert-to-wp-theme.md
/scaffold-wp-theme	Criar scaffold de tema de bloco vazio (sem conversão de fonte)	commands/scaffold-wp-theme.md
/wp-pattern	Converter seção HTML única em um padrão de bloco registrado	commands/wp-pattern.md
/wp-theme-json	Gerar theme.json a partir de um sistema de design / propriedades CSS personalizadas	commands/wp-theme-json.md
/wp-template	Converter página HTML única em modelo FSE	commands/wp-template.md
/wp-block	Scaffold de um bloco personalizado (block.json, edit.js, save.js/render.php, CSS)	commands/wp-block.md
/wp-migrate	Migrar conteúdo WP existente (Classic Editor, ACF, widgets, CPTs, shortcodes) para tema de bloco	commands/wp-migrate.md
/wp-plugin-theme	Declarar dependências de plugin e gerar CSS / código de compatibilidade específico do plugin	commands/wp-plugin-theme.md
/wp-variation	Gerar uma variação de estilo (styles/*.json) — modo escuro, troca de paleta de cores, troca de fonte	commands/wp-variation.md
/wp-classic-to-fse	Converter um tema clássico WordPress existente (modelos PHP) para tema de bloco FSE	commands/wp-classic-to-fse.md
/wp-debug	Depurar sistematicamente problemas de tema de bloco WordPress (tela branca, erros de editor, regressões de estilo)	commands/wp-debug.md

Quando o usuário digitar um destes comandos, leia o arquivo de comando correspondente em commands/ e execute o fluxo de trabalho definido lá.

---

Fluxo de Trabalho Principal

Para QUALQUER solicitação de conversão (seja acionada por comando de barra ou linguagem natural):

Passo 1: Pense — Capture e Esclareça (Princípio 1)

Reúna estas entradas (pergunte apenas se não for fornecido):

• Identidade do tema (nome, slug, autor, descrição)
• Tipo de projeto de origem (landing page, blog, eCommerce, portfólio, SaaS)
• Arquivos HTML para converter
• Tokens de design (cores, fontes, espaçamento)
• Preferência de sistema de build (Vite 6 padrão, ou wp-scripts, ou nenhum)
• Suporte a WooCommerce (sim/não)

Antes de prosseguir, declare explicitamente:

• O que você está assumindo (ex.: "Estou assumindo que você deseja licenciamento GPL-2.0-or-later, já que você mencionou submissão ao WordPress.org")
• O que você NÃO está fazendo (ex.: "Não vou construir suporte a WooCommerce, já que você não mencionou eCommerce")
• Quaisquer ambiguidades que precisam ser resolvidas (ex.: "Seu hero usa um fundo de vídeo — isso deve ser um core/cover com vídeo ou um padrão personalizado com uma tag <video>?")

Para valores padrão quando o usuário estiver em silêncio, use a tabela em references/defaults.md.

Passo 2: Planeje — Defina Critérios de Sucesso (Princípios 1 + 4)

Antes de escrever qualquer código, produza um Plano de Conversão que mapeie:

• Cada arquivo HTML de origem → modelo WordPress
• Cada seção repetida → padrão de bloco
• Cabeçalho/rodapé → partes de modelo
• Componentes interativos → estratégia JS (Interactivity API preferida, enfileiramento clássico para libs complexas — leia references/modern-blocks.md)
• Tokens de design → estrutura theme.json
• Necessidades de dados dinâmicos → candidatos a Block Bindings API

Declare também os critérios de sucesso para esta conversão específica:

CRITÉRIOS DE SUCESSO:
1. O tema ativa no WordPress [versão] sem erros ou avisos PHP
2. [Lista de páginas] renderizam visualmente correspondendo ao HTML de origem
3. Todos os padrões aparecem no inserir do Editor de Site sob [categorias]
4. Todos os componentes interativos funcionam (liste-os)
5. Sem estilos inline na marcação de bloco
6. Todas as strings prontas para tradução
7. PHPCS WordPress-Extra passa com zero erros
8. [Quaisquer critérios específicos do projeto]

Mostre este plano ao usuário. Obtenha confirmação antes de prosseguir para a geração de arquivos (a menos que o usuário diga explicitamente "apenas construa").

Passo 3: Execute — Metodologia de 10 Fases (Princípio 2)

Siga as fases documentadas em references/methodology.md. Aplique Simplicidade Primeiro em cada fase — gere apenas o que o projeto precisa:

1. Auditar e Extrair — analisar fonte, identificar componentes reutilizáveis
2. theme.json — gerar esquema v3 com configurações + estilos completos (incl. Section Styles, dimensions, position)
3. Modelos e Partes — converter páginas HTML em marcação de bloco FSE
4. Padrões de Bloco — registrar seções como padrões reutilizáveis
5. Estilos e Variações de Bloco — registrar variantes personalizadas via theme.json + PHP
6. Integração JavaScript — Interactivity API para padrões interativos; wp_enqueue_script() apenas para libs complexas. Leia references/modern-blocks.md PRIMEIRO.
7. functions.php e inc/ — arquivos de inicialização seguindo os Padrões de Codificação WP
8. Acessibilidade e Desempenho — WCAG 2.1 AA + Core Web Vitals + carregamento de CSS por bloco + pré-carregamento de fontes
9. i18n — strings prontas para tradução em todos os lugares
10. README e Documentação — readme.txt no formato WordPress.org

Verificações de simplicidade durante a execução:

• Estou gerando um arquivo que não é necessário para este projeto específico? → Remova-o.
• Estou adicionando um padrão que o usuário não pediu? → Remova-o.
• Estou escrevendo CSS para algo que o theme.json trata? → Mova para theme.json.
• Estou criando uma abstração usada apenas uma vez? → Inline-a.
• Este arquivo de 200 linhas pode ter 50 linhas? → Reescreva-o.

Passo 4: Arquivos de Saída (Princípio 3)

Use a estrutura de arquivos documentada em references/file-structure.md. Gere cada arquivo com um cabeçalho claro:

=== FILE: {{theme-slug}}/path/to/file.ext ===
<content>

Para projetos grandes (10+ páginas HTML ou temas WooCommerce), divida a entrega em 3 rodadas usando references/multi-turn-strategy.md.

Precisão cirúrgica para temas existentes: Se modificar um tema existente, gere APENAS os arquivos alterados. Inclua um resumo de diff mostrando exatamente o que mudou e por quê.

Passo 5: Verifique — Pós-Geração (Princípio 4)

Execute o doutor automatizado primeiro. Antes de fornecer a saída ao usuário, execute:

node scripts/doctor.mjs <theme-dir>

Isso executa todas as quatro verificações de qualidade (validação de theme.json, lint de marcação de bloco, verificação de registro de padrão, cobertura i18n). Não declare sucesso até que o doctor saia com 0. Se sair com código não zero, volte para a fase relevante e corrija cada violação relatada antes de continuar.

Em seguida, forneça:

• Instruções de instalação
• Lista de verificação pós-instalação (ativar, definir página inicial, instalar plugins necessários)
• Comandos de build (npm install, npm run dev, npm run build)
• Seção "Decisões Tomadas" — cada suposição listada com justificativa
• Etapas de verificação — como confirmar que cada critério de sucesso foi atendido:

VERIFICAÇÃO:
✅ node scripts/doctor.mjs <theme-dir> → sai com 0 (todas as verificações passam)
✅ Ativar tema → Confirmar sem erros PHP em debug.log
✅ Visitar página inicial → Confirmar correspondência visual com a fonte
✅ Abrir Editor de Site → Confirmar todos os modelos listados
✅ Inserir bloco → Confirmar que todos os padrões aparecem sob categorias corretas
✅ Executar `npx phpcs --standard=WordPress-Extra .` → Confirmar zero erros
✅ Verificar console do navegador → Confirmar zero erros JS
✅ Executar Lighthouse → Confirmar pontuação de acessibilidade ≥ 90

Se alguma etapa de verificação falhar, volte para a fase relevante e corrija antes de relatar como concluído. Não declare sucesso após uma verificação com falha.

Se o usuário relatar um problema com um tema gerado, direcione-o para /wp-debug. Veja references/troubleshooting.md para a referência completa de sintoma → causa raiz → correção.

---

Regras de Qualidade — Inegociáveis

Estas regras se aplicam a CADA arquivo gerado. Veja references/quality-rules.md para detalhes completos.

❌ NUNCA:

• Atributos style="" inline na marcação de bloco
• Tags <style> ou <script> dentro de modelos/partes/padrões
• Cores/espaçamento codificados em CSS — use var(--wp--preset--color--{slug})
• Funções WordPress obsoletas
• Saída sem escape (sempre `esc_htm