theme.json do WordPress explicado: settings, styles e a cascata

O theme.json é um único arquivo de configuração na raiz de um tema de blocos que faz dois trabalhos separados: settings decide o que o editor de blocos oferece aos usuários, e styles decide como o site fica por padrão. O WordPress interpreta o arquivo, mescla com os próprios padrões e com qualquer coisa salva no Editor do Site, e devolve o resultado como propriedades CSS personalizadas mais uma folha de estilo embutida em cada página.

Confundir esses dois trabalhos é o motivo pelo qual a maioria das edições no theme.json parece não fazer nada. Declarar uma cor em settings não aplica essa cor em lugar nenhum. Isso só cria uma variável e uma amostra na barra lateral do editor.

As chaves de primeiro nível

Um arquivo mínimo é assim:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {},
  "styles": {},
  "templateParts": [],
  "customTemplates": []
}

Chave	O que ela faz
$schema	Só autocompletar e validação no editor de código. O WordPress ignora.
version	Diz ao WordPress qual formato de esquema interpretar. Não é a versão do seu tema.
settings	Gera variáveis CSS e controla o que o editor oferece.
styles	Aplica o estilo padrão de verdade.
templateParts	Declara as partes em parts/ e a qual área cada uma pertence.
customTemplates	Registra modelos de página em templates/ para o editor de posts.

A chave version engana porque parece o número de versão do tema. Não é. Ela seleciona um modo de interpretação, e versões antigas do WordPress ignoram em silêncio chaves de um formato de esquema que não conhecem. Se você atende instalações antigas, mire na versão que elas entendem em vez de supor que chaves novas degradam sem problema. A versão 3 é a atual no momento em que este texto foi escrito; a versão 2 ainda está muito instalada e continua sendo interpretada.

O $schema aponta para uma URL de esquema hospedada pelo WordPress. Fixá-la em trunk dá as dicas mais novas no seu editor de código; uma URL de versão específica é mais segura se você está deliberadamente ficando em um esquema mais antigo.

settings: o que o editor oferece

Tudo dentro de settings produz uma propriedade CSS personalizada e, na maioria dos casos, um controle no editor. Nada dentro de settings estiliza coisa alguma.

{
  "settings": {
    "color": {
      "palette": [
        { "slug": "brand", "color": "#1f4ed8", "name": "Brand" },
        { "slug": "ink", "color": "#111827", "name": "Ink" }
      ],
      "custom": false
    },
    "typography": {
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" },
        { "slug": "large", "size": "1.5rem", "name": "Large" }
      ]
    },
    "layout": {
      "contentSize": "680px",
      "wideSize": "1200px"
    }
  }
}

Isso produz variáveis nomeadas a partir do caminho do preset e do slug:

--wp--preset--color--brand
--wp--preset--color--ink
--wp--preset--font-size--small
--wp--preset--font-size--large

Também produz classes utilitárias como .has-brand-color e .has-brand-background-color, que é como o editor aplica a amostra escolhida a um bloco.

A linha "custom": false é a outra metade de settings: desligar opções. Coloque isso e o seletor de cor livre desaparece, deixando para os usuários a sua paleta e nada mais. O mesmo padrão vale para tudo — settings.typography.customFontSize, settings.spacing.customSpacingSize, settings.border e assim por diante. Nada dentro de settings é decorativo; cada chave ou adiciona uma variável, ou adiciona um controle, ou remove um controle.

O settings.custom é um espaço livre para as suas próprias variáveis:

{
  "settings": {
    "custom": {
      "lineHeight": { "body": 1.6 },
      "shadow": { "card": "0 1px 3px rgba(0,0,0,0.12)" }
    }
  }
}

Essas viram --wp--custom--line-height--body e --wp--custom--shadow--card. Repare na transformação: chaves em camelCase são quebradas em kebab-case, e o aninhamento é unido com dois traços. Errar o nome de uma variável é um motivo comum de um valor cair no padrão silenciosamente.

Você pode aplicar settings por bloco, que é como se libera um seletor de cor nos botões mas não nos parágrafos:

{
  "settings": {
    "blocks": {
      "core/paragraph": {
        "color": { "custom": false, "customGradient": false }
      }
    }
  }
}

styles: o que realmente renderiza

styles é onde os valores são aplicados. Ele espelha a estrutura do editor: um nível raiz, depois elements, depois blocks.

{
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--base)",
      "text": "var(--wp--preset--color--ink)"
    },
    "typography": {
      "lineHeight": "var(--wp--custom--line-height--body)"
    },
    "elements": {
      "link": {
        "color": { "text": "var(--wp--preset--color--brand)" },
        ":hover": { "typography": { "textDecoration": "none" } }
      }
    },
    "blocks": {
      "core/quote": {
        "typography": { "fontStyle": "italic" },
        "spacing": { "padding": { "left": "var(--wp--preset--spacing--40)" } }
      }
    }
  }
}

O styles no nível raiz cai no body. elements cobre primitivos HTML que não são blocos — link, botão, títulos, legenda. blocks mira um tipo de bloco específico pelo nome.

A limitação honesta: styles não consegue expressar tudo o que o CSS expressa. Não há como escrever suas próprias media queries, não há seletores complexos, não há animações, e só existe um conjunto pequeno de estados de pseudoclasse suportados. Tipografia fluida e dimensionamento por layout cobrem boa parte do que as pessoas resolviam com breakpoints, mas não tudo. A maioria dos temas de blocos em produção leva theme.json mais uma folha de estilo enxuta, e isso é um resultado normal, não um fracasso.

A armadilha do settings contra o styles

A dúvida de suporte mais comum é alguma versão de “adicionei a cor da minha marca e nada mudou”.

Correto. Adicionar em settings.color.palette criou a variável --wp--preset--color--brand e uma amostra. Não aplicou nada. Para tornar essa cor a cor padrão dos links, você também precisa escrever em styles:

{
  "settings": {
    "color": {
      "palette": [{ "slug": "brand", "color": "#1f4ed8", "name": "Brand" }]
    }
  },
  "styles": {
    "elements": {
      "link": { "color": { "text": "var(--wp--preset--color--brand)" } }
    }
  }
}

Leia assim: settings é a caixa de tintas que você entrega ao usuário, styles é a demão que você passa antes de ele chegar.

A cascata, da menor para a maior prioridade

Essa é a parte que explica um site que “ignora” o arquivo do tema. O WordPress mescla várias camadas antes de emitir o CSS:

1. Padrões do núcleo do WordPress — o núcleo traz o próprio theme.json com paleta, tamanhos de fonte e escala de espaçamento de base.
2. theme.json do tema pai
3. theme.json do tema filho — mesclado sobre o pai chave por chave, não substituindo o arquivo inteiro.
4. Estilos Globais salvos no banco de dados — o que o painel de Estilos do Editor do Site grava.
5. Estilos por bloco em blocos individuais — atributos guardados no conteúdo do post, renderizados como estilos inline ou classes.

A camada 4 é a que quebra sites. No momento em que alguém abre o painel de Estilos e salva, o WordPress guarda um registro de Estilos Globais, e esse registro vence sobre o seu arquivo para toda propriedade que ele contiver. Editar o theme.json depois disso não muda nada visível nessas propriedades, num site que fica idêntico depois de um deploy enquanto o arquivo em disco está claramente diferente.

A correção é limpar o registro salvo, não escalar com !important. Abra o Editor do Site, vá em Estilos, abra o painel de revisões e volte aos padrões do tema. Confirme antes com o cliente ou o dono do site — resetar descarta as personalizações dele, o que é um custo real, não uma ação gratuita.

O segundo suspeito é o cache. O WordPress guarda em cache os dados já interpretados do theme.json em vez de reler o arquivo a cada requisição, que é exatamente o que você quer em produção e exatamente o que você não quer durante o desenvolvimento. Ativar o WP_DEBUG, ou a configuração de modo de desenvolvimento de tema nas versões mais novas, faz o WordPress reler o arquivo toda vez. Se suas edições só aparecem depois de um deploy ou de uma limpeza de cache, é isso que está acontecendo.

templateParts e customTemplates

Os dois são arrays que descrevem arquivos que já estão no seu tema.

{
  "templateParts": [
    { "name": "header", "title": "Header", "area": "header" },
    { "name": "footer", "title": "Footer", "area": "footer" }
  ],
  "customTemplates": [
    { "name": "page-wide", "title": "Wide Page", "postTypes": ["page"] }
  ]
}

O name corresponde ao nome do arquivo sem a extensão — parts/header.html, templates/page-wide.html. O valor de area importa: ele decide se a parte é envolvida por um elemento de marco de cabeçalho ou rodapé e como o editor a categoriza. Deixe de fora e a parte é tratada como sem categoria.

O customTemplates é o que faz um modelo aparecer na lista de modelos do editor de posts. Sem essa entrada, o arquivo existe mas ninguém consegue selecioná-lo.

Uma ordem rápida de diagnóstico

Quando um tema de blocos não está estilizando do jeito que o arquivo diz que deveria, percorra isto antes de mexer em qualquer coisa:

1. Veja o código-fonte e procure o bloco de estilos globais gerado. Se sua variável não estiver lá, o problema está em settings ou em um slug digitado errado.
2. Se a variável existe mas não é usada, o problema é uma entrada faltando em styles.
3. Se as duas existem mas algo as sobrescreve, procure um registro salvo de Estilos Globais.
4. Só então olhe a sua própria folha de estilo, plugins ou algum construtor de páginas injetando CSS mais adiante na cascata.