Centralizar o estilo de um tema no theme.json no WordPress reúne cores, tipografia e espaçamento em um único arquivo declarativo. Segundo a referência oficial de theme.json do WordPress, o arquivo usa o schema versão 2 e o core gera o CSS a partir dele. Um tema bem estruturado gera CSS mais enxuto. Use o arquivo antes de sair escrevendo CSS solto.

O arquivo de configuração de tema no WordPress define as opções globais de estilo, como paleta de cores, fontes e espaçamento, num formato único que o editor de blocos lê. Esse arquivo é o theme.json no WordPress, que chegou com o FULL Site Editing e virou a forma oficial de configurar temas modernos. A gente vê no suporte da FULL que muita gente ainda edita estilo no CSS solto e perde controle. Este guia integra o conteúdo da FULL sobre temas WordPress da FULL e mostra a estrutura do arquivo, os 6 passos de configuração e como ele apoia SEO e desempenho do tema.

Primeiros passos: Visão geral do theme.json no WordPress

O theme.json no WordPress organiza em 1 arquivo o que antes ficava espalhado entre functions.php, Customizer e folhas de estilo soltas. Ele nasceu na versão 5.8 e ganhou a versão 2 do schema na 5.9, em 2022, consolidando settings (o que o usuário pode mexer) e styles (o valor padrão aplicado). Quem domina esse arquivo configura o tema inteiro sem tocar em PHP.

A tabela abaixo resume os blocos principais do arquivo, o objetivo de cada um e como validar se a configuração funcionou, da paleta de cores ao espaçamento global do tema.

Legenda: a separação entre settings e styles é o que torna o arquivo previsível para editor e front-end.

O que é o theme.json no WordPress e por que ele existe

O theme.json no WordPress é a fonte única de verdade do estilo de um tema de blocos: um arquivo na raiz do tema que o core do WordPress lê para montar o editor e o front-end. Ele existe para acabar com a duplicação de estilo entre PHP, Customizer e CSS, que gerava temas inconsistentes e difíceis de manter ao longo dos anos.

Pense nele como a planta de uma casa em vez de instruções soltas para cada cômodo. Antes, cada área do tema dependia de add_theme_support() no functions.php, de opções do Customizer e de regras de CSS que brigavam entre si por especificidade. O arquivo unifica isso num JSON declarativo: você diz o que quer, e o WordPress gera o CSS necessário. Temas como o Twenty Twenty-Four nasceram inteiros assim, sem uma folha de estilo gigante. Quem vem do modelo antigo encontra aqui o guia da FULL sobre criar temas para WordPress.

Como o theme.json no WordPress se relaciona com CSS e customizer

O theme.json no WordPress fica acima do Customizer e do CSS adicional na ordem de quem manda no estilo, mas não elimina os dois. Em blocos cobertos pelo arquivo, o valor do JSON vira o padrão; o CSS solto só sobrescreve quando tem especificidade maior, o que costuma gerar conflito silencioso em boa parte dos temas migrados às pressas.

A regra prática é: o que é estrutural e reutilizável vai para o arquivo; a exceção pontual fica no CSS. Um theme.json com settings.color.palette definido e custom:false faz o editor bloquear cores fora da paleta, o que impede o cliente de quebrar a identidade visual sem querer. Já ajustes muito específicos continuam mais simples no CSS direto do painel. O Customizer perde força nos temas de bloco, mas ainda aparece em temas híbridos. Entender essa cascata evita horas de depuração por causa de uma cor que não muda.

Passo a passo: Configurar o theme.json no WordPress

Configurar o theme.json no WordPress segue seis movimentos em ordem lógica, do esqueleto do arquivo à validação no editor. Os passos abaixo assumem um tema de blocos já ativo; um child theme funciona igual, com a ressalva de mesclagem que veremos adiante. Para o detalhe oficial de cada chave, a documentação da referência de theme.json do WordPress traz a lista completa de propriedades suportadas pelo core.

Passo 1: Crie o arquivo na raiz do tema

Crie um arquivo chamado theme.json na pasta raiz do tema, ao lado do style.css. Comece com o esqueleto mínimo: a chave version igual a 2 e a chave $schema apontando para o schema oficial, que liga o autocomplete no editor de código. Sem a versão 2, o WordPress trata o arquivo como schema antigo e ignora boa parte das opções.

Passo 2: Defina a paleta de cores

Configure settings.color.palette como uma lista de objetos com slug, color e name. Cada cor vira uma variável CSS automática no formato --wp--preset--color--{slug}, reutilizável em todo o tema. Use slug em inglês e sem acento, porque ele entra no nome da variável e em classes; o name pode ser em português para o editor.

Passo 3: Trave a tipografia

Em settings.typography.fontFamilies, declare as fontes do tema e desative customFontSize se quiser uma escala fixa. Defina fontSizes com slugs como small, medium e large, que o WordPress expõe no seletor de tamanho. Isso evita que um editor escolha 47px no meio de um texto e quebre o ritmo visual da página.

Passo 4: Padronize o espaçamento

Use settings.spacing.spacingScale ou spacingSizes para criar uma escala de margens e padding consistente. Ativar units permite controlar quais unidades (px, rem, vh) ficam disponíveis no editor. Uma escala enxuta, com 5 a 7 degraus, cobre quase todo layout e mantém o espaçamento previsível entre seções.

Passo 5: Aplique os styles padrão

Na chave styles, defina os valores aplicados por padrão: cor de fundo, cor do texto, fonte base e espaçamento do conteúdo. Você também estiliza blocos específicos em styles.blocks, como dar uma cor só aos botões. Esses valores viram CSS gerado pelo core, sem você enfileirar nada manualmente.

Passo 6: Valide no editor e no front-end

Abra o editor de blocos e confira se a paleta, as fontes e a escala de espaçamento aparecem como esperado. No front-end, inspecione o HTML e confirme que o CSS das variáveis --wp--preset-- foi gerado. Se uma opção não aparecer, quase sempre é erro de vírgula ou chave fora de settings, e o JSON inteiro deixa de carregar.

Theme.json no WordPress, child theme e a ordem de mesclagem

O theme.json no WordPress de um child theme não substitui o do tema pai: o WordPress mescla os dois chave a chave, com o filho vencendo onde houver conflito. Esse comportamento muda tudo na hora de personalizar, porque copiar o arquivo inteiro do pai para o filho é justamente o erro que mais aparece nos tickets de tema da FULL.

Quem copia o theme.json inteiro do pai para o filho congela aquela versão e perde os updates do tema base na próxima atualização. O certo é declarar no filho apenas as chaves que você muda: uma cor nova, uma fonte diferente, um ajuste de espaçamento. O restante continua herdado do pai e segue recebendo melhorias. Esse cuidado é o mesmo de quando você decide alterar corretamente um tema do WordPress sem perder customizações. Em temas solidos como os da review do tema Astra, a mesclagem por child theme é o caminho recomendado pelo próprio autor.

Como o theme.json no WordPress ajuda SEO e desempenho

O theme.json no WordPress influencia SEO de forma indireta mas concreta: ao gerar CSS só do que a página usa, ele reduz requisições e ajuda métricas de carregamento como o LCP, um dos Core Web Vitals que o Google avalia. Um tema declarativo bem feito entrega menos CSS bloqueante que um tema antigo cheio de folhas de estilo enfileiradas à mão.

O ganho de desempenho vem da forma como o core monta a folha de estilo. Como o WordPress gera o CSS a partir das chaves de settings e styles, ele carrega apenas as variáveis --wp--preset-- que o tema realmente declara, em vez de uma folha gigante feita à mão. Isso reduz CSS não usado, evita conflito de especificidade e mantém o HTML mais limpo, o que ajuda o crawler do Google a entender a página e melhora a base técnica que sustenta o SEO. A gente vê no suporte da FULL que temas migrados para esse modelo ficam mais leves e mais fáceis de manter ao longo das atualizações.

Garanta um tema rápido e citável com o plano certo

Configurar o theme.json no WordPress resolve a base do estilo, mas um tema bem ranqueado precisa de schema JSON-LD e meta tags bem feitos, e é aí que o plano PRO da FULL entra. O plano PRO sai por R$849,90 e dá acesso ao bundle com Rank Math PRO, que gera o schema e os sinais de SEO on-page por cima do tema que você montou no Gutenberg. Diluído nos sites que você gerencia, isso fica em torno de R$85 por site, valor que a gente vê no suporte compensar rápido para quem cuida de vários projetos. Conheça o plano PRO no FULL.services/planos e padronize tema e SEO de uma vez.

Perguntas frequentes sobre theme.json no WordPress

Próximos passos para dominar temas de bloco

O theme.json no WordPress deixou de ser detalhe avançado e virou a base de qualquer tema de bloco bem feito: quem configura o arquivo direito ganha controle total sobre cor, fonte e espaçamento sem CSS solto. Comece pelo esqueleto, defina a paleta, trave a tipografia e valide no editor, sempre declarando no child theme apenas o que muda. A partir daí, o tema fica previsível, mais rápido e mais fácil de manter ao longo das atualizações. Para continuar aprendendo, vale aprofundar no editor de blocos Gutenberg e seguir os tutoriais e guias reunidos no FULL Academy.