| Bloco | Objetivo | Check de validação |
|---|---|---|
| settings.color | Definir a paleta disponível | Cores aparecem no seletor do editor |
| settings.typography | Travar fontes e tamanhos | Lista de fontes restrita ao tema |
| settings.spacing | Padronizar margens e padding | Escala de espaçamento no editor |
| styles | Aplicar o valor padrão | Front-end renderiza sem CSS extra |
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 desettings 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.
theme.json é um arquivo de configuração na raiz do tema que define cores, tipografia e espaçamento globais num único JSON declarativo. Ele existe desde a versão 5.8 e serve para o WordPress gerar o CSS do tema e montar as opções do editor de blocos sem precisar de PHP. Na prática, é a fonte única de estilo do tema, lida tanto pelo editor quanto pelo front-end.
Sim, dá para configurar quase todo o estilo só pelo theme.json, sem tocar no functions.php. Cores, fontes, espaçamento e estilos de bloco vivem inteiros no JSON, e o core do WordPress cuida de gerar o CSS. O PHP só volta a ser necessário para lógica dinâmica, como registrar padrões de bloco ou enfileirar um script específico, o que é raro num tema puramente visual.
Porque o theme.json tem prioridade sobre o Customizer na ordem de carregamento de estilo dos temas de bloco. O WordPress trata o JSON como a definição oficial do tema, então um valor de cor declarado nele vence o equivalente legado do Customizer. Em temas híbridos o Customizer ainda aparece, mas em temas FULL Site Editing ele perde quase toda a função para o arquivo.
A diferença está na mesclagem: o theme.json do child theme não substitui o do pai, ele mescla chave a chave, com o filho vencendo nos conflitos. Por isso você declara no filho só as chaves que muda, como uma cor ou fonte nova. Copiar o arquivo inteiro do pai congela aquela versão e faz o tema perder os updates do pai na atualização seguinte.
O theme.json suporta uma paleta principal por tema em settings.color.palette, sem limite rígido de cores dentro dela, além das paletas separadas de gradientes e duotones. Na prática, uma paleta enxuta de 6 a 10 cores cobre quase todo projeto e mantém o seletor do editor limpo. Um child theme pode adicionar ou trocar cores específicas sem refazer a paleta inteira do pai.