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.

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

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.