theme.json v3 em 2026: guia prático para temas WordPress

O theme.json deixou de ser apenas um arquivo de configuração do editor. Em temas modernos, ele funciona como a camada de tokens, permissões de design e estilos que conecta editor, frontend e personalização do usuário.

A versão atual do formato é a 3, disponível a partir do WordPress 6.6. Versões antigas continuam compatíveis, mas novos recursos são desenvolvidos sobre o schema mais recente.

Estrutura mínima recomendada

Comece declarando o schema. Além de documentar a intenção do arquivo, isso ativa validação e autocomplete em editores compatíveis.

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

Durante desenvolvimento, o schema trunk expõe recursos mais recentes, mas pode incluir propriedades ainda não presentes na versão de produção. Para projetos entregues a clientes, prefira o schema da menor versão do WordPress suportada.

settings: o que o editor pode oferecer

A seção settings controla ferramentas e presets. Ela não é apenas uma lista de cores: define o vocabulário de design disponível para quem edita o site.

{
  "version": 3,
  "settings": {
    "appearanceTools": true,
    "color": {
      "defaultPalette": false,
      "palette": [
        { "slug": "night", "name": "Night", "color": "#020a13" },
        { "slug": "lime", "name": "Lime", "color": "#b5ea10" },
        { "slug": "aqua", "name": "Aqua", "color": "#0ed0bd" }
      ]
    },
    "spacing": {
      "units": ["px", "rem", "vw"],
      "spacingSizes": [
        { "slug": "20", "size": "0.75rem", "name": "S" },
        { "slug": "40", "size": "1.5rem", "name": "M" },
        { "slug": "60", "size": "3rem", "name": "L" }
      ]
    }
  }
}

Desative defaults quando o projeto exige consistência. Se o usuário puder escolher qualquer cor, tamanho e espaçamento, o design system existe apenas no documento — não no produto.

styles: como os tokens chegam ao site

Em styles, você aplica valores globais, elementos e blocos específicos:

{
  "version": 3,
  "styles": {
    "color": {
      "background": "var:preset|color|night",
      "text": "#f4f7f5"
    },
    "typography": {
      "fontFamily": "var:preset|font-family|sans",
      "lineHeight": "1.6"
    },
    "elements": {
      "link": {
        "color": { "text": "var:preset|color|lime" }
      }
    },
    "blocks": {
      "core/button": {
        "border": { "radius": "0.7rem" },
        "typography": { "fontWeight": "800" }
      }
    }
  }
}

A sintaxe var:preset|... vira uma custom property do WordPress. Isso mantém editor e frontend alinhados e evita repetir valores mágicos.

Quando usar CSS fora do JSON

O theme.json cobre uma parte padronizada do CSS e ainda aceita CSS personalizado em alguns pontos. Mas não tente transformar JSON em uma folha de estilos ilegível.

Use theme.json para:

• tokens e presets;
• habilitar ou remover ferramentas;
• estilos globais e estados suportados;
• decisões que precisam aparecer no editor.

Use CSS para:

• seletores complexos;
• animações extensas;
• regras condicionais;
• componentes com muitas linhas de estilo;
• comportamento que não pertence ao design system.

Variações de estilo

Arquivos dentro de /styles podem oferecer variações de tema, cor, tipografia e bloco. Uma organização clara ajuda equipes grandes:

styles/
  theme/
  color/
  typography/
  block/

Uma variação de bloco pode declarar blockTypes, slug, title e seus próprios estilos. Isso cria opções editoriais reutilizáveis sem duplicar blocos.

Erros comuns

Usar o schema errado

O arquivo pode validar no trunk e falhar na versão mínima suportada. Valide contra a versão de produção.

Liberar controles demais

appearanceTools: true é conveniente, mas deve ser combinado com presets e restrições coerentes.

Misturar token e decisão local

Se um valor aparece em vários componentes, ele provavelmente é um token. Se serve a um único detalhe, talvez pertença ao bloco ou ao CSS.

Ignorar estilos do usuário

O WordPress combina valores do core, tema e usuário. Teste o que acontece depois que alguém altera Estilos Globais no Site Editor.

Checklist de produção

1. declare version: 3;
2. use um schema compatível com sua versão mínima;
3. valide JSON no build;
4. teste editor e frontend;
5. confira templates e template parts;
6. teste variações de estilo;
7. verifique contraste e foco;
8. remova presets que não devem ser usados;
9. evite CSS longo dentro do JSON;
10. documente os tokens do projeto.

O melhor theme.json não é o maior. É o arquivo que oferece liberdade suficiente para editar sem destruir a coerência do site.