# Theme.json: Customize o tema WordPress em 5 passos Configurar cores e tipografia pelo theme.json centraliza o estilo do tema num arquivo só. Segundo a documentação oficial do WordPress (2024), ele define presets globais que o editor lê direto. Reduz o CSS solto e deixa o cache de estilo previsível. Comece pela paleta antes da tipografia. No WordPress moderno, o arquivo theme.json controla a aparência do tema por configuração, não por CSS espalhado. Ele fica na raiz do tema e descreve cores, fontes, espaçamentos e layout que o Site Editor e o editor de blocos leem na hora de renderizar. Em vez de editar o `style.css` ou empilhar regras no Customizer, você declara presets num formato estruturado e o WordPress gera o CSS final. Este guia mostra como customizar o tema com theme.json em cinco passos, da paleta de cores até a hierarquia entre tema-pai e child theme. Para o panorama completo do cluster, veja os conteúdos de temas WordPress da FULL. --- ## Primeiros passos: O que o theme.json controla O theme.json controla quatro camadas de estilo do tema: settings (presets disponíveis), styles (valores aplicados), customTemplates e templateParts. Na prática, é onde você define a paleta de cores, a escala tipográfica, os tamanhos de espaçamento e o layout de largura. A tabela abaixo resume cada chave principal e o efeito direto na interface, com base no comportamento padrão do Theme Handbook oficial.

theme.json: chaves principais e efeito na interface do editor
Chave	Função	Efeito na interface
settings.color.palette	Define cores nomeadas	Limita o seletor de cor aos valores do tema
settings.typography	Fontes e tamanhos	Popula o menu de tipografia do bloco
settings.spacing	Escala de espaçamento	Cria os presets de padding e margin
styles	Aplica os valores	Gera o CSS global inline do site

Um theme.json bem montado transforma decisões de design em contrato técnico: o editor só oferece o que o tema autoriza, o que reduz erro de cliente. ## Por que o theme.json substitui o CSS do customizer O theme.json tem precedência sobre o CSS adicional do Customizer em 2 frentes: o WordPress gera os estilos globais inline com peso de especificidade próprio e os serve no `` antes do Customizer. Quando você declara `styles.color.background`, essa regra costuma vencer o CSS solto na maioria dos cenários. O problema clássico aparece quando há os dois ao mesmo tempo: o CSS do Customizer concorrendo com o theme.json gera especificidade imprevisível e invalida o cache de estilo a cada deploy. No suporte da FULL, boa parte dos tickets de "minha cor não muda" vem exatamente daí, um tema com theme.json novo e um Customizer cheio de regras antigas brigando. A regra prática é migrar o CSS do Customizer para o theme.json e manter o `style.css` só para ajustes que o arquivo não cobre. Se o seu fluxo ainda depende de página com builder, vale comparar os arquivos JSON do WordPress com os métodos de CSS personalizado no Elementor. ## Passo a passo: Customizar o tema com theme.json Customizar o tema com theme.json segue uma ordem estável de 5 passos, do arquivo base até a publicação no Site Editor, e leva poucos minutos por ajuste depois que a estrutura existe. Os passos abaixo assumem um tema de blocos como o Twenty Twenty-Four ou um child theme do Astra, e cada etapa é independente. ### Passo 1: Crie o arquivo theme.json na raiz do tema Crie um arquivo chamado `theme.json` na pasta raiz do tema, no mesmo nível do `style.css`. A primeira linha obrigatória é `"version": 2`, o schema atual desde o WordPress 5.9. Sem essa chave, o WordPress ignora o resto do arquivo. Use um editor com validação JSON para evitar vírgula sobrando, o erro de sintaxe número um nos tickets que a gente vê no suporte. Salve o arquivo vazio com apenas a versão e recarregue o editor para confirmar que o tema não quebrou. ### Passo 2: Defina a paleta de cores em settings.color.palette Declare as cores dentro de `settings.color.palette`, cada uma com slug, color e name. O slug vira a classe CSS (`has-primary-color`) e o name aparece no seletor do editor. Defina de 4 a 8 cores nomeadas: limitar a paleta força consistência visual e remove o seletor de hex livre da interface. Esse é o ponto-chave de governança, com a paleta travada, o cliente não insere um roxo aleatório no meio do site corporativo. ### Passo 3: Configure a tipografia em settings.typography Configure as fontes em `settings.typography.fontFamilies` e os tamanhos em `settings.typography.fontSizes`. Cada fonte recebe fontFamily, slug e name; cada tamanho recebe size, slug e name. Ative `fluid: true` para tipografia responsiva que escala entre breakpoints sem media query manual. Para subir fontes próprias, registre o caminho do arquivo no `fontFace` e confirme o carregamento, processo detalhado no guia de fontes personalizadas no WordPress. ### Passo 4: Aplique os estilos globais no bloco styles Aplique os valores no bloco `styles`, que é onde os presets viram aparência real. Em `styles.color` você define fundo e texto padrão; em `styles.typography` aplica a fonte base e a altura de linha; em `styles.blocks` você estiliza blocos específicos como `core/button` ou `core/heading`. O WordPress transforma esse bloco no CSS global inline servido no ``, o que mantém o estilo previsível e o cache estável entre deploys. ### Passo 5: Publique e ajuste pelo site editor Abra o Site Editor em Aparência e use o painel de Estilos para revisar o que o theme.json definiu. Tudo que você declarou no arquivo aparece como ponto de partida, e ajustes feitos na interface são salvos como override de usuário, sem reescrever o arquivo do tema. Para herdar uma referência sólida de estrutura, vale estudar como o editor de blocos Gutenberg consome esses presets na renderização. ## Hierarquia: Tema-pai, child theme e site editor A precedência do theme.json sobe em 3 níveis, do tema-pai para o child theme e deste para os ajustes do Site Editor, sempre com o nível mais alto vencendo. O tema-pai define a base; um child theme sobrescreve chaves específicas; e o usuário aplica a camada final salva no banco. O detalhe que derruba sites: quando o child theme declara apenas `"version": 2` sem repetir os settings, o WordPress não herda os presets automaticamente em todos os casos, e a paleta some da interface. Em sites que herdam um tema WordPress antigo via filho, esse merge silencioso é a causa de "minhas cores sumiram após atualizar". A correção é declarar os settings que você quer preservar dentro do próprio theme.json do filho, não confiar na herança total. Esse comportamento de block template e estilos é específico de temas de bloco; temas clássicos só leem um subconjunto do arquivo. ## Customize o tema com governança no bundle FULL Centralizar o estilo no theme.json é metade do trabalho; manter os plugins de tema atualizados em escala é a outra. No plano PRO da FULL, por R$849 por ano com até 10 sites, o custo cai para R$85 por site e inclui licenças como o Astra PRO e o Elementor PRO já ativadas, sem gerenciar chave em cada instalação. Veja os planos da FULL para comparar os níveis. A gente vê no suporte que time que padroniza o tema base e ativa os plugins por bundle erra menos em deploy do que quem licencia avulso site a site, porque o ponto de falha de licença expirada some da operação.

Legenda: o arquivo theme.json na raiz do tema concentra paleta, tipografia e espaçamento que o editor lê na renderização.

Perguntas frequentes sobre theme.json

Por que o theme.json sobrescreve o CSS do Customizer?

O theme.json vence porque o WordPress gera estilos globais inline no <head> com especificidade própria, que costuma superar o CSS adicional do Customizer. Quando os dois coexistem, a regra do arquivo prevalece na maioria dos casos e o ajuste do Customizer parece "não funcionar". A correção é migrar essas regras para o bloco styles do theme.json.

É possível customizar o tema com theme.json sem saber CSS?

Sim, é possível na maior parte dos ajustes: cor, fonte, tamanho e espaçamento são declarados por presets nomeados, sem escrever uma linha de CSS bruto. Você edita pares de chave e valor no formato JSON, como slug e color. Só ajustes muito específicos de seletor ainda pedem CSS direto, e mesmo esses cabem no bloco styles.blocks.

Qual a diferença entre o theme.json do tema-pai e do child theme?

O theme.json do tema-pai define a base de estilos; o do child theme sobrescreve apenas as chaves que ele repete. A diferença crítica é que a herança não é total: se o filho declara só a version sem settings, o WordPress pode zerar os presets herdados e a paleta some da interface. Declare no filho os settings que precisa preservar.

Quanto tempo leva para aplicar uma paleta de cores via theme.json?

Aplicar uma paleta leva poucos minutos depois que o arquivo existe: você adiciona de 4 a 8 entradas em settings.color.palette, salva e recarrega o Site Editor. O efeito é imediato no seletor de cor do editor. O tempo maior, quando há, é migrar cores antigas do Customizer, não declarar as novas no arquivo.

O que acontece com o theme.json em temas clássicos sem suporte a blocos?

Em temas clássicos, o WordPress lê apenas um subconjunto do theme.json, sobretudo as configurações de editor de blocos, e ignora os styles globais que dependem do Site Editor. A paleta pode aparecer no editor, mas o front-end clássico continua governado pelo style.css. Para usar o arquivo por completo, o tema precisa declarar suporte a FULL Site Editing.

## Próximos passos para dominar o tema por configuração Migrar o estilo do tema para o theme.json troca improviso de CSS por um contrato técnico que o editor respeita e o cache entende. Comece pela paleta, avance para a tipografia e só então toque na hierarquia entre tema-pai e child theme, validando cada chave no Site Editor antes do deploy. Times que padronizam o tema base reduzem retrabalho, e o ganho fica visível também em Core Web Vitals, já que menos CSS solto significa menos render-blocking. Para aprofundar a criação de temas do zero, o guia de recursos para criar temas WordPress e o review do tema Astra mostram bases sólidas que já trazem theme.json maduro. Para continuar aprendendo, o FULL Academy reúne tutoriais, guias e reviews de WordPress num só lugar.