Construção de tema WordPress
O objetivo é um tema onde o design está fixo no código e o conteúdo é editável no editor. Texto codificado diretamente em templates é a razão mais comum pela qual clientes voltam para edições triviais.
Escolha a abordagem
| Abordagem | Quando escolher |
|---|---|
Tema de bloco (theme.json, templates HTML) | Nova construção, cliente edita no Editor do Site, conteúdo é principalmente blocos padrão |
Tema clássico híbrido (templates PHP mais theme.json e padrões de bloco) | Marcação personalizada complexa ou animação pesada que precisa de controle exato do HTML |
| Tema filho | Modificar um tema existente; nunca edite um tema pai diretamente, pois atualizações o sobrescrevem |
Para sites de marketing com design animado, a abordagem híbrida geralmente é a mais pragmática: marcação precisa em PHP, conteúdo editável através de padrões, campos e o editor de blocos.
Estrutura mínima
meu-tema/
├── style.css # comentário de cabeçalho do tema (obrigatório)
├── functions.php # configuração, enfileiramentos, registros
├── theme.json # paleta, escala de tipos, espaçamento, larguras de layout
├── index.php # template de fallback (clássico/híbrido)
├── front-page.php # página inicial
├── header.php # cabeçalho
├── footer.php # rodapé
├── template-parts/ # um arquivo por seção
├── patterns/ # padrões de bloco (registrados automaticamente)
├── assets/css # folhas de estilo
├── assets/js # scripts
├── assets/media # mídia
└── screenshot.png # 1200x900
Cabeçalho style.css:
/*
Theme Name: Meu Tema
Author: Seu Nome
Version: 1.0.0
Requires at least: 6.4
Requires PHP: 8.0
Text Domain: meu-tema
*/
Workflow de conversão
- Congele a construção estática. Termine o HTML, CSS e JS primeiro e valide. Converter um alvo em movimento dobra o trabalho.
- Divida em partes. Cabeçalho e rodapé vão para
header.phpefooter.phpcomwp_head()ewp_footer(). Cada seção da página inicial se torna um arquivo emtemplate-parts/, carregado comget_template_part(). - Mova tokens para
theme.json(paleta, tamanhos de fonte, espaçamento, largura de conteúdo) para que o editor mostre as mesmas opções que o front-end. Mantenha os mesmos valores das propriedades CSS personalizadas; o WordPress gera variáveis--wp--preset--*que você pode alias. Se o CLIwebcraftestiver disponível,webcraft tokens "#brand" --format theme-json -o theme.jsonescreve um arquivo versão 3 a partir dos mesmos valores detokens.css. - Enfileire, nunca codifique, ativos:
add_action('wp_enqueue_scripts', function () {
$v = wp_get_theme()->get('Version');
$uri = get_theme_file_uri('assets');
wp_enqueue_style('meu-tema', "$uri/css/main.css", [], $v);
wp_enqueue_script('gsap', "$uri/js/vendor/gsap.min.js", [], '3', ['strategy' => 'defer', 'in_footer' => true]);
wp_enqueue_script('meu-tema', "$uri/js/main.js", ['gsap'], $v, ['strategy' => 'defer', 'in_footer' => true]);
});
Agrupe bibliotecas localmente em vez de a partir de uma CDN sempre que possível; evita uma requisição de terceiros e uma questão de consentimento. 5. Torne o conteúdo editável. Escolha por seção:
- Itens repetitivos com suas próprias páginas (serviços, portfólio, depoimentos): um tipo de post personalizado consultado com
WP_Query. - Texto e imagens de seções únicas: padrões de bloco que o cliente insere e edita, ou campos personalizados.
- Itens globais (telefone, links de redes sociais, texto do rodapé): o Customizer ou uma pequena página de opções.
- Navegação:
register_nav_menus()ewp_nav_menu().
- Escape tudo na saída:
esc_html(),esc_attr(),esc_url(),wp_kses_post()para rich text. Envolva strings em__()ouesc_html__()com o text domain. - Imagens: use
wp_get_attachment_image()para quesrcset,sizes, dimensões e lazy loading sejam gerados. Registre os tamanhos necessários comadd_image_size(). - Suportes do tema:
title-tag,post-thumbnails,editor-styles,responsive-embeds,html5,wp-block-styles.
Animação dentro do WordPress
- Scripts que ocultam conteúdo não devem rodar no editor de blocos. Enfileire-os apenas no front-end (
wp_enqueue_scripts, nãoenqueue_block_assets). - A barra de administração desloca cabeçalhos fixos em 32px (46px no mobile); compense com
body.admin-bar .header { top: var(--wp-admin--admin-bar--height, 32px); }. - Plugins de cache e otimização que adiam ou combinam JS podem quebrar a ordem de carregamento. Declare dependências corretamente para que sejam respeitadas, e teste com o plugin ativado.
- Conteúdo adicionado no editor não terá seus atributos de animação. Aplique animações por classe de bloco em JS, ou forneça padrões que incluam os atributos.
Não faça
- Edite o núcleo do WordPress ou um tema pai.
- Coloque funcionalidade que deve sobreviver a uma troca de tema (tipos de post personalizados, shortcodes) no tema quando o cliente pode trocar de tema; um pequeno plugin é o lugar certo.
- Consulte dentro de loops sem resetar (
wp_reset_postdata()). - Envie com avisos
WP_DEBUG. Desenvolva comWP_DEBUGligado. - Agrupe plugins pagos ou ativos cuja licença não permita redistribuição.
Checklist de entrega
- O cliente pode alterar todo texto, imagem, item de menu e detalhe de contato visível sem tocar em código.
- Página inicial definida em Configurações, Leitura; permalinks definidos como nome do post.
- Favicon (ícone do site), template 404, template de busca, página de privacidade presentes.
- Um guia de edição de uma página com capturas de tela.
- Em seguida, execute a habilidade
launch-qa.