Como Criar um Tema de Bloco Personalizado no WordPress com theme.json: Um Guia Passo a Passo

Resumo

Criar um tema de bloco personalizado no WordPress com Full Site Editing (FSE) pode ser assustador, mas o theme.json simplifica o processo. Este guia orienta você na configuração de um tema de bloco mínimo, definindo estilos globais como cores e tipografia no theme.json, e criando modelos personalizados usando marcação de blocos. Você aprenderá a adicionar padrões de blocos e variações de estilo, permitindo um site totalmente projetável sem arquivos de modelo PHP. Abordaremos erros comuns, como misturar recursos de temas clássicos e de blocos, e mostraremos como testar seu tema. Ao final, você terá um tema de bloco moderno e extensível pronto para produção. Essa abordagem aproveita os recursos mais recentes do WordPress para um desenvolvimento mais rápido e visual.

Introdução

O Full Site Editing (FSE) revolucionou o desenvolvimento de temas no WordPress, permitindo projetar visualmente cada parte do seu site. Mas muitos desenvolvedores ainda dependem de temas clássicos ou têm dificuldade em criar temas de bloco do zero. A chave para desbloquear o poder do FSE é o theme.json — um arquivo de configuração que controla estilos, configurações e modelos globais. Este artigo fornece um guia prático, passo a passo, para criar um tema de bloco personalizado usando theme.json. Você aprenderá a configurar a estrutura de pastas, definir paletas de cores e predefinições de tipografia, criar modelos personalizados com marcação de blocos e adicionar variações de estilo. Ao final, você terá um tema de bloco pronto para produção, fácil de manter e estender. Vamos mergulhar e desmistificar o desenvolvimento com FSE.

Para uma visão mais ampla de como o FSE está moldando o futuro do design no WordPress, confira Gutenberg FSE: O Futuro do Design WordPress em 2026.

1. Configurando um Tema de Bloco Mínimo

Um tema de bloco requer no mínimo dois arquivos: style.css e index.html. Vamos criá-los.

Estrutura de Pastas

Crie uma pasta chamada my-block-theme no diretório wp-content/themes/. Dentro, coloque:

• style.css
• index.html
• (opcional) theme.json

style.css

Embora os temas de bloco dependam menos de CSS, o style.css ainda é necessário para identificação do tema:

/*
Theme Name: My Block Theme
Theme URI: https://example.com
Author: Your Name
Description: A custom block theme built with theme.json.
Version: 1.0
Requires at least: 5.9
Tested up to: 6.5
Requires PHP: 7.4
License: GPL v2 or later
Text Domain: my-block-theme
*/

A linha Requires at least: 5.9 garante que o tema funcione com o recurso FSE.

index.html

Este é seu modelo de fallback. Ele deve começar com marcação de blocos. Crie um layout simples:

<!-- wp:template-part {\"slug\":\"header\",\"tagName\":\"header\"} /-->

<!-- wp:group {\"layout\":{\"type\":\"constrained\"}} -->
<div class=\"wp-block-group\">
    <!-- wp:post-title /-->
    <!-- wp:post-content /-->
</div>
<!-- /wp:group -->

<!-- wp:template-part {\"slug\":\"footer\",\"tagName\":\"footer\"} /-->

Isso usa sintaxe de blocos para incluir partes de modelo de cabeçalho e rodapé, e exibe o título do post e o conteúdo.

Atenção: Temas de bloco não devem conter arquivos de modelo PHP como header.php ou footer.php. Misturar modelos clássicos e de blocos quebrará o FSE.

Ativando o Tema

Faça upload da pasta via FTP ou instalação zip, e ative-a. Você verá um site em branco com sua estrutura mínima. Em seguida, vamos estilizá-lo com theme.json.

2. Dominando o theme.json: Estilos e Configurações Globais

theme.json centraliza todos os controles de design. Ele fica na raiz da sua pasta de tema. Vamos criar um com configurações de cor e tipografia.

Estrutura Básica

{
    \"version\": 2,
    \"settings\": {
        \"color\": {
            \"palette\": [
                {
                    \"slug\": \"primary\",
                    \"color\": \"#007cba\",
                    \"name\": \"Primary\"
                },
                {
                    \"slug\": \"secondary\",
                    \"color\": \"#005a87\",
                    \"name\": \"Secondary\"
                },
                {
                    \"slug\": \"background\",
                    \"color\": \"#ffffff\",
                    \"name\": \"Background\"
                }
            ],
            \"gradients\": []
        },
        \"typography\": {
            \"fontFamilies\": [
                {
                    \"fontFamily\": \"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif\",
                    \"slug\": \"system\",
                    \"name\": \"System\"
                },
                {
                    \"fontFamily\": \"'Georgia', serif\",
                    \"slug\": \"serif\",
                    \"name\": \"Serif\"
                }
            ],
            \"fontSizes\": [
                {
                    \"slug\": \"small\",
                    \"size\": \"14px\",
                    \"name\": \"Small\"
                },
                {
                    \"slug\": \"medium\",
                    \"size\": \"18px\",
                    \"name\": \"Medium\"
                },
                {
                    \"slug\": \"large\",
                    \"size\": \"24px\",
                    \"name\": \"Large\"
                }
            ]
        },
        \"spacing\": {
            \"padding\": true,
            \"margin\": true,
            \"units\": [\"px\", \"em\", \"rem\"]
        }
    },
    \"styles\": {
        \"color\": {
            \"background\": \"var(--wp--preset--color--background)\",
            \"text\": \"var(--wp--preset--color--primary)\"
        },
        \"typography\": {
            \"fontFamily\": \"var(--wp--preset--font-family--system)\",
            \"fontSize\": \"var(--wp--preset--font-size--medium)\"
        }
    }
}

Isso define uma paleta de cores, famílias de fontes, tamanhos de fonte e estilos globais. As funções var() referenciam propriedades personalizadas CSS geradas automaticamente pelo WordPress. Os usuários podem então alterá-las no Editor de Site.

Dica: Use propriedades personalizadas CSS para consistência. Evite codificar valores em arquivos CSS; deixe o theme.json ser a única fonte da verdade.

3. Criando Modelos Personalizados

Os modelos de bloco são arquivos HTML com marcação de blocos. Eles seguem uma hierarquia semelhante aos arquivos de modelo clássicos. Por exemplo, crie single.html para posts individuais:

<!-- wp:template-part {\"slug\":\"header\",\"tagName\":\"header\"} /-->

<!-- wp:group {\"tagName\":\"main\",\"layout\":{\"type\":\"constrained\"}} -->
<main class=\"wp-block-group\">
    <!-- wp:post-title {\"level\":1} /-->
    <!-- wp:post-featured-image /-->
    <!-- wp:post-content /-->
    <!-- wp:post-navigation-link {\"type\":\"previous\"} /-->
    <!-- wp:post-navigation-link {\"type\":\"next\"} /-->
</main>
<!-- /wp:group -->

<!-- wp:template-part {\"slug\":\"footer\",\"tagName\":\"footer\"} /-->

Da mesma forma, crie page.html, archive.html, etc. Você também pode criar modelos personalizados adicionando um bloco wp:post-template dentro de um loop de consulta.

Para personalização avançada, considere construir blocos personalizados. Saiba mais em Além dos Blocos Básicos: Criando Blocos Gutenberg Personalizados para Funcionalidades Avançadas no WordPress.

Partes de Modelo

Crie uma pasta parts/ para partes reutilizáveis. Por exemplo, header.html:

<!-- wp:group {\"tagName\":\"header\",\"layout\":{\"type\":\"flex\",\"flexWrap\":\"nowrap\"}} -->
<header class=\"wp-block-group\">
    <!-- wp:site-logo /-->
    <!-- wp:navigation {\"themeLocation\":\"primary\"} /-->
</header>
<!-- /wp:group -->

E footer.html:

<!-- wp:paragraph {\"align\":\"center\"} -->
<p class=\"has-text-align-center\">&copy; 2025 My Site</p>
<!-- /wp:paragraph -->

4. Adicionando Padrões de Blocos e Variações de Estilo

Padrões de blocos são layouts pré-projetados. Defina-os em uma pasta patterns/. Crie patterns/hero.php:

<?php
/**
 * Title: Hero
 * Slug: my-block-theme/hero
 * Categories: hero
 */
?>
<!-- wp:cover {\"overlayColor\":\"primary\",\"minHeight\":50,\"align\":\"full\"} -->
<div class=\"wp-block-cover alignfull\" style=\"min-height:50vh\">
    <span aria-hidden=\"true\" class=\"wp-block-cover__background has-primary-background-color\"></span>
    <div class=\"wp-block-cover__inner-container\">
        <!-- wp:heading {\"textAlign\":\"center\",\"level\":1,\"style\":{\"color\":{\"text\":\"#ffffff\"}}} -->
        <h1 class=\"has-text-align-center has-text-color\" style=\"color:#ffffff\">Welcome</h1>
        <!-- /wp:heading -->
        <!-- wp:paragraph {\"align\":\"center\",\"textColor\":\"white\"} -->
        <p class=\"has-text-align-center has-white-color\">This is a custom hero section</p>
        <!-- /wp:paragraph -->
    </div>
</div>
<!-- /wp:cover -->

Variações de estilo permitem que os usuários mudem toda a aparência. Crie styles/default.json e styles/dark.json que substituem as configurações do tema.

5. Advertências e Melhores Práticas

• Performance: theme.json é armazenado em cache. Limpe o cache após alterações. Use o hook wp_register_theme_json se necessário.
• Compatibilidade Retroativa: Temas de bloco funcionam apenas a partir do WordPress 5.9. Se seu site precisar suportar versões mais antigas, considere uma abordagem híbrida, mas evite misturar arquivos de modelo.
• Temas Filhos: Temas de bloco podem ser usados como temas pai para temas filhos clássicos, mas não vice-versa. Use template em style.css para declarar um tema de bloco pai.
• Internacionalização: Use a função __() dentro de partes de modelo PHP para strings traduzíveis. Na marcação de blocos, especifique o domínio de texto através do atributo textDomain.

Para mais sobre melhores práticas de desenvolvimento de plugins, veja Construindo Plugins WordPress Robusto: Um Guia Prático para Melhores Práticas.

Conclusão

Construir um tema de bloco personalizado com theme.json permite que você crie um site totalmente projetável sem tocar em PHP. Seguindo este guia, você configurou um tema mínimo, definiu estilos globais, criou modelos personalizados e adicionou padrões. Lembre-se de testar minuciosamente, especialmente para casos extremos como páginas de arquivo ou tipos de post personalizados. Conforme o WordPress evolui, os temas de bloco se tornarão o padrão. Comece a usar o FSE hoje para otimizar seu fluxo de trabalho e oferecer aos clientes flexibilidade incomparável.

Se você quiser acelerar ainda mais a criação de temas, considere usar uma ferramenta que gera um site completo a partir de uma descrição. Por exemplo, você pode descrever o layout desejado e ter um tema de bloco pronto para uso em minutos.

Pronto para colocar seu tema de bloco no ar? Com uma descrição em texto simples, você pode gerar uma landing page ou site totalmente funcional — sem necessidade de código.