theme.json version 3 dans WordPress 6.6 : migrer sans casser vos presets

WordPress 6.6, sorti fin juillet, généralise la version 3 du schéma theme.json. Sur le papier, la bascule ressemble à celle de la v1 vers la v2 : changer un nombre en tête de fichier. En pratique, sur un thème client que nous maintenons depuis 2022, la migration a fait apparaître dans l’éditeur des tailles de police que nous avions volontairement masquées deux ans plus tôt. La cause : un changement de comportement des presets par défaut du cœur, discret mais avec un effet visible immédiat.

Ce guide couvre la migration depuis la v2 vers la v3. Il ne revient pas sur les nouveautés déjà apportées par la v2 elle-même, que nous avions traitées lors de sa sortie.

Ce qui change concrètement en v3

La nouveauté centrale de la v3 concerne le contrôle plus fin des valeurs par défaut fournies par le cœur de WordPress. Deux nouvelles clés apparaissent : defaultFontSizes et defaultSpacingSizes, toutes deux booléennes, qui déterminent si les tailles de police et d’espacement natives du cœur doivent être ajoutées automatiquement aux presets définis dans le thème.

{
  "$schema": "https://schemas.wp.org/wp/6.6/theme.json",
  "version": 3,
  "settings": {
    "typography": {
      "defaultFontSizes": false,
      "fontSizes": [
        { "slug": "petit", "size": "0.875rem", "name": "Petit" },
        { "slug": "moyen", "size": "1.125rem", "name": "Moyen" }
      ]
    },
    "spacing": {
      "defaultSpacingSizes": false
    }
  }
}

C’est précisément ce paramètre qui manquait sur notre thème client : en v2, désactiver les tailles par défaut du cœur se faisait via la clé plus générale custom ou en filtrant côté PHP, une approche moins lisible. En v3, defaultFontSizes: false suffit à garantir que seules les tailles déclarées explicitement par le thème apparaissent dans le sélecteur de l’éditeur.

Un changement dans l’ordre de priorité des presets

Autre évolution notable : en v3, quand un thème déclare un preset avec le même slug qu’un preset par défaut du cœur, la valeur du thème prend systématiquement le dessus, y compris pour l’ordre d’affichage dans le sélecteur. En v2, cet ordre pouvait dans certains cas rester dicté par l’ordre d’enregistrement interne, ce qui produisait des sélecteurs de couleur ou de taille dans un ordre parfois inattendu.

Procédure de migration suivie sur nos projets

1. Sauvegarder le theme.json actuel et noter la liste complète des presets déclarés (couleurs, tailles de police, espacements).
2. Passer version à 3 et mettre à jour $schema.
3. Ajouter explicitement defaultFontSizes: false et defaultSpacingSizes: false si le thème a toujours voulu maîtriser strictement sa liste de presets — sinon, laisser le comportement par défaut, qui reste à true.
4. Recharger l’éditeur de blocs et comparer le sélecteur de tailles de police avec la liste notée à l’étape 1 : toute valeur en trop signale un preset natif du cœur réapparu.
5. Vérifier les styles utilisateur déjà enregistrés en base : une valeur choisie avant la migration reste valide même si son slug n’est plus proposé dans le sélecteur après coup.

Cas rencontré : des tailles fantômes après migration

Sur le thème client mentionné en introduction, la migration a fait réapparaître les tailles « Small », « Medium », « Large » et « Extra Large » du cœur, alors que le thème n’en avait jamais eu besoin depuis sa création — elles avaient simplement été masquées en v2 par un réglage désormais insuffisant en v3. L’ajout de defaultFontSizes: false a réglé le problème en une ligne, mais nous ne l’aurions pas trouvé sans comparer le sélecteur avant et après migration, d’où l’intérêt de l’étape de vérification manuelle dans la procédure ci-dessus.

Ne migrez jamais un theme.json de production un vendredi après-midi. Les presets fantômes ne sont pas visibles en ligne de commande ni dans les logs : seule une vérification visuelle du sélecteur de l’éditeur les révèle, et il faut du temps calme pour comparer méthodiquement avant et après.

Compatibilité avec les thèmes restés en v2

Un thème en v2 continue de fonctionner normalement sous WordPress 6.6 : rien n’oblige à migrer immédiatement. La bascule vers la v3 n’a d’intérêt réel que si le thème doit gérer finement l’apparition des presets natifs du cœur, ou si une extension future dépend spécifiquement des clés introduites en v3.

En résumé

La migration vers la v3 de theme.json tient en une ligne de version, mais son effet le plus sournois porte sur les presets par défaut du cœur qui peuvent réapparaître silencieusement dans l’éditeur. Une comparaison manuelle du sélecteur de tailles et de couleurs avant et après la bascule reste, à ce stade, la seule vérification fiable.