theme.json expliqué : settings, styles et la cascade WordPress

theme.json est un fichier de configuration unique, placé à la racine d’un thème bloc, qui remplit deux missions distinctes : settings décide de ce que l’éditeur de blocs propose aux utilisateurs, et styles décide de l’apparence réelle du site par défaut. WordPress l’analyse, le fusionne avec ses propres valeurs par défaut et avec tout ce qui a été enregistré dans l’éditeur de site, puis produit le résultat sous forme de propriétés personnalisées CSS et de feuille de styles en ligne sur chaque page.

Confondre ces deux missions, c’est la raison pour laquelle la plupart des modifications de theme.json semblent ne rien faire. Déclarer une couleur sous settings ne l’applique nulle part. Cela crée seulement une variable et une pastille dans la barre latérale de l’éditeur.

Les clés de premier niveau

Un fichier minimal ressemble à ceci :

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

Clé	À quoi elle sert
$schema	Uniquement l’autocomplétion et la validation dans l’éditeur de code. WordPress l’ignore.
version	Indique à WordPress quel schéma analyser. Ce n’est pas la version de votre thème.
settings	Génère les variables CSS et détermine ce que l’éditeur expose.
styles	Applique le style par défaut réel.
templateParts	Déclare les parties présentes dans parts/ et la zone à laquelle elles appartiennent.
customTemplates	Enregistre les modèles de page de templates/ pour l’éditeur de contenu.

version piège tout le monde parce qu’elle ressemble à un numéro de version de thème. Elle n’en est pas un. Elle sélectionne un mode d’analyse, et les anciennes versions de WordPress ignorent silencieusement les clés issues d’un schéma qu’elles ne connaissent pas. Si vous prenez en charge des installations anciennes, visez la version que ces installations comprennent plutôt que de supposer que les clés récentes se dégradent proprement. La version 3 est la version courante à l’heure où ces lignes sont écrites ; la version 2 reste très répandue et toujours analysée.

$schema pointe vers une URL de schéma hébergée par WordPress. La figer sur trunk vous donne les suggestions les plus récentes dans votre éditeur de code ; une URL liée à une version précise est plus prudente si vous restez délibérément sur un schéma plus ancien.

settings : ce que l’éditeur propose

Tout ce qui se trouve sous settings produit une propriété personnalisée CSS et, dans la plupart des cas, un contrôle dans l’éditeur. Rien sous settings ne stylise quoi que ce soit.

{
  "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"
    }
  }
}

Cela produit des variables nommées à partir du chemin du preset et du slug :

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

Cela produit aussi des classes utilitaires comme .has-brand-color et .has-brand-background-color : c’est ainsi que l’éditeur applique à un bloc la pastille choisie.

La ligne "custom": false illustre l’autre moitié de settings : désactiver des options. Mettez-la et le sélecteur de couleur libre disparaît, ne laissant aux utilisateurs que votre palette, et rien d’autre. Le même principe vaut partout — settings.typography.customFontSize, settings.spacing.customSpacingSize, settings.border, et ainsi de suite. Rien sous settings n’est décoratif : chaque clé ajoute une variable, ajoute un contrôle, ou retire un contrôle.

settings.custom est un espace libre pour vos propres variables :

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

Ces valeurs deviennent --wp--custom--line-height--body et --wp--custom--shadow--card. Notez la transformation : les clés en camelCase sont découpées en kebab-case, et l’imbrication est reliée par un double tiret. Se tromper dans un nom de variable est une cause fréquente de valeur qui retombe silencieusement sur sa valeur de repli.

Vous pouvez restreindre des réglages bloc par bloc, ce qui permet par exemple d’autoriser un sélecteur de couleur sur les boutons mais pas sur les paragraphes :

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

styles : ce qui s’affiche vraiment

styles, c’est là où les valeurs sont appliquées. La clé reprend la structure de l’éditeur : un niveau racine, puis elements, puis 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)" } }
      }
    }
  }
}

Les styles de niveau racine atterrissent sur le body. elements couvre les primitives HTML qui ne sont pas des blocs : lien, bouton, titres, légende. blocks cible un type de bloc précis par son nom.

La limite, en toute honnêteté : styles ne sait pas exprimer tout ce que le CSS permet. Impossible d’écrire vos propres media queries, pas de sélecteurs complexes, pas d’animations, et seulement un petit jeu d’états de pseudo-classes pris en charge. La typographie fluide et le dimensionnement basé sur la mise en page couvrent une bonne partie de ce pour quoi on utilisait des points de rupture, mais pas tout. La plupart des thèmes bloc livrés embarquent un theme.json plus une feuille de styles modeste, et c’est un résultat normal, pas un échec.

Le piège settings contre styles

La question de support la plus fréquente est une variante de « j’ai ajouté la couleur de ma marque et rien n’a changé ».

C’est normal. L’ajouter à settings.color.palette a créé --wp--preset--color--brand et une pastille. Cela n’a rien appliqué. Pour en faire la couleur de lien par défaut, vous devez aussi l’écrire sous styles :

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

À lire ainsi : settings, c’est la boîte de peinture que vous tendez à l’utilisateur ; styles, c’est la couche que vous passez avant son arrivée.

La cascade, du niveau le plus bas au plus haut

C’est la partie qui explique un site qui « ignore » le fichier du thème. WordPress fusionne plusieurs couches avant d’émettre le CSS :

1. Les valeurs par défaut du cœur de WordPress — le cœur livre son propre theme.json avec une palette, des tailles de police et une échelle d’espacement de base.
2. Le theme.json du thème parent
3. Le theme.json du thème enfant — fusionné par-dessus le parent clé par clé, sans remplacer le fichier entier.
4. Les styles globaux enregistrés en base de données — ce qu’écrit le panneau Styles de l’éditeur de site.
5. Les styles posés sur des blocs individuels — des attributs stockés dans le contenu de l’article, rendus en styles en ligne ou en classes.

C’est la couche 4 qui casse les sites. Dès l’instant où quelqu’un ouvre le panneau Styles et enregistre, WordPress stocke un enregistrement de styles globaux, et cet enregistrement l’emporte sur votre fichier pour chaque propriété qu’il contient. Modifier theme.json ensuite ne change rien de visible pour ces propriétés : le site reste identique après un déploiement alors que le fichier sur le disque est visiblement différent.

La solution consiste à effacer l’enregistrement, pas à monter d’un cran avec !important. Ouvrez l’éditeur de site, allez dans Styles, ouvrez le panneau des révisions et revenez aux valeurs par défaut du thème. Validez d’abord avec le client ou le propriétaire du site : cette réinitialisation supprime ses personnalisations, ce qui a un vrai coût, ce n’est pas un geste gratuit.

Le deuxième suspect, c’est le cache. WordPress met en cache les données analysées de theme.json au lieu de relire le fichier à chaque requête, ce qui est exactement ce que vous voulez en production et exactement ce que vous ne voulez pas pendant le développement. Activer WP_DEBUG, ou le réglage de mode développement de thème sur les versions récentes, force WordPress à relire le fichier à chaque fois. Si vos modifications n’apparaissent qu’après un déploiement ou un vidage de cache, c’est ce phénomène que vous observez.

templateParts et customTemplates

Les deux sont des tableaux qui décrivent des fichiers déjà présents dans votre thème.

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

name correspond au nom de fichier sans son extension — parts/header.html, templates/page-wide.html. La valeur de area compte : elle décide si la partie est encapsulée dans un élément de repère d’en-tête ou de pied de page, et comment l’éditeur la classe. Omettez-la et la partie est traitée comme non classée.

customTemplates est ce qui fait apparaître un modèle dans la liste déroulante des modèles de l’éditeur de contenu. Sans cette entrée, le fichier existe mais personne ne peut le sélectionner.

Un ordre de diagnostic rapide

Quand un thème bloc ne se stylise pas comme le fichier l’indique, déroulez ceci avant de toucher à quoi que ce soit :

1. Affichez le code source et cherchez le bloc de styles globaux généré. Si votre variable n’y est pas, le problème est dans settings ou dans une faute de frappe sur un slug.
2. Si la variable existe mais n’est utilisée nulle part, le problème est une entrée styles manquante.
3. Si les deux existent mais que quelque chose les écrase, cherchez un enregistrement de styles globaux sauvegardé.
4. Seulement ensuite, regardez votre propre feuille de styles, les extensions, ou un constructeur de pages qui injecte du CSS plus loin dans la cascade.