theme.json : premiers pas avec les réglages globaux de WordPress 5.8

WordPress 5.8 vient de sortir ce mois-ci, et son ajout le plus structurant pour les auteurs de thèmes s’appelle theme.json. Ce fichier, placé à la racine du thème, permet de déclarer de façon déclarative les couleurs, la typographie, les espacements et le comportement de l’éditeur de blocs, là où il fallait auparavant multiplier les appels à add_theme_support() dans functions.php.

J’ai commencé à migrer plusieurs thèmes maison vers cette nouvelle approche, et le gain de lisibilité est net. Ce tutoriel présente la structure de base du fichier, la clé settings qui en est le cœur, et quelques pièges rencontrés lors des premiers essais.

Pourquoi theme.json change la donne

Avant WordPress 5.8, activer le support des couleurs personnalisées, définir une palette ou limiter les tailles de police disponibles nécessitait d’écrire du PHP procédural, souvent dispersé entre plusieurs fichiers. Avec theme.json, toute cette configuration devient déclarative, dans un unique fichier JSON lu directement par l’éditeur de blocs et le rendu front.

Concrètement, cela signifie que l’éditeur et le site public partagent désormais la même source de vérité pour le style : plus besoin de dupliquer les couleurs entre le CSS du thème et les réglages du Customizer.

La structure de base du fichier

Le fichier se place à la racine du thème, au même niveau que style.css. Voici un squelette minimal et réaliste, tel que je le pose en début de projet :

{
  "$schema": "https://schemas.wp.org/wp/5.8/theme.json",
  "version": 2,
  "settings": {
    "color": {
      "custom": true,
      "customGradient": true,
      "palette": [
        {
          "slug": "primary",
          "color": "#1a3c6e",
          "name": "Bleu principal"
        },
        {
          "slug": "secondary",
          "color": "#f2b134",
          "name": "Jaune accent"
        },
        {
          "slug": "dark-gray",
          "color": "#1e1e1e",
          "name": "Gris foncé"
        }
      ]
    },
    "typography": {
      "customFontSize": false,
      "fontSizes": [
        { "slug": "small", "size": "14px", "name": "Petit" },
        { "slug": "normal", "size": "18px", "name": "Normal" },
        { "slug": "large", "size": "28px", "name": "Grand" }
      ]
    },
    "spacing": {
      "units": [ "px", "em", "rem", "%" ],
      "customPadding": true
    }
  }
}

Notez l’attribut "version": 2, obligatoire pour bénéficier du schéma le plus récent introduit avec WordPress 5.8. Sans cette clé, l’éditeur retombe sur un comportement plus limité, hérité des premières expérimentations du projet Gutenberg.

La clé settings, cœur du fichier

La section settings détermine ce que l’utilisateur peut ou ne peut pas modifier dans l’éditeur de blocs. Chaque réglage désactivé retire purement et simplement l’option correspondante de l’interface, plutôt que de la griser :

• color.custom à false retire le sélecteur de couleur personnalisée et n’affiche plus que la palette définie
• typography.customFontSize à false impose les tailles de police prédéfinies dans fontSizes
• spacing.customPadding à true ouvre le contrôle de marge interne bloc par bloc
• settings.blocks permet de surcharger ces réglages pour un type de bloc précis uniquement

Cette granularité est précieuse : on peut par exemple autoriser une palette de couleurs libre pour le bloc Paragraphe tout en la verrouillant strictement pour le bloc Titre, afin de préserver la cohérence visuelle du site.

Activer les réglages par bloc

Pour cibler un bloc spécifique, on utilise la clé blocks à l’intérieur de settings, avec le nom complet du bloc comme core/heading ou core/paragraph :

"settings": {
  "blocks": {
    "core/heading": {
      "color": {
        "custom": false
      }
    }
  }
}

Ce que theme.json remplace dans functions.php

Plusieurs appels classiques à add_theme_support() deviennent redondants une fois theme.json en place, notamment ceux liés à editor-color-palette, editor-font-sizes ou custom-spacing. WordPress lit en priorité les réglages du fichier JSON s’il est présent, et il vaut mieux éviter de dupliquer la configuration aux deux endroits pour ne pas se retrouver avec des comportements contradictoires.

Sur mes premiers essais, j’ai perdu du temps à chercher pourquoi mes couleurs personnalisées en functions.php n’apparaissaient plus. La règle est simple : dès que theme.json déclare une clé, elle prend le pas sur l’équivalent PHP. Autant nettoyer functions.php dès le départ plutôt que de laisser cohabiter les deux systèmes.

Pour aller plus loin

Ce tutoriel ne couvre que les fondations : couleurs, typographie et espacements. La clé settings permet aussi de contrôler les bordures, les thèmes de couleur par défaut ou encore l’activation du mode pleine largeur pour certains blocs. Je recommande de migrer un thème existant progressivement, réglage par réglage, en vérifiant à chaque étape le rendu dans l’éditeur avant de supprimer le code PHP équivalent. C’est un chantier qui prend quelques heures, mais qui simplifie considérablement la maintenance future du thème.