# theme.json version 2 et WordPress 6.0 : ce qui change pour les auteurs de thèmes

> WordPress 6.0 généralise le schéma v2 de theme.json. Tour d'horizon des nouveautés et de la marche à suivre pour migrer un thème depuis la v1.

- Auteur : Clément Hadrot
- Publié le : 2022-12-29
- Mis à jour le : 2022-12-29
- Catégorie : Thèmes
- URL : https://wpmoderne.dev.wordpress-developpement.fr/themes/theme-json-v2-wordpress-6-0/

## L’essentiel

- appearanceTools active un lot d'options en une clé
- templates et styles d'éléments arrivent en v2
- La v1 reste lue mais perd les nouveautés

Depuis quelques semaines, presque tous les thèmes que nous livrons embarquent un `theme.json` en version 2. WordPress 5.9 avait introduit ce schéma en parallèle de la v1, mais c'est WordPress 6.0, sorti en mai dernier, qui le rend vraiment incontournable : plusieurs fonctionnalités attendues par nos clients — les styles par élément, les gabarits personnalisés déclarés depuis le thème — ne sont tout simplement pas accessibles en v1.

Sur un projet livré à un client du secteur associatif, nous avons dû reprendre un thème bloc démarré en v1 quelques mois plus tôt. Le passage en v2 nous a pris une matinée, mais nous a évité de dupliquer des règles CSS que le nouveau schéma gère nativement. Voici ce qu'il faut savoir avant de vous lancer sur un projet similaire.

## Déclarer la version 2

La bascule commence par une ligne simple à la racine du fichier :

```
{
  "$schema": "https://schemas.wp.org/wp/6.0/theme.json",
  "version": 2,
  "settings": {},
  "styles": {}
}
```

Le champ `$schema` n'est pas obligatoire au sens strict, mais il apporte l'auto-complétion dans la plupart des éditeurs de code, ce qui limite les fautes de frappe sur des clés profondément imbriquées. Le champ `version`, lui, conditionne directement l'interprétation du fichier par le cœur de WordPress : sans lui, ou avec `"version": 1`, les nouvelles clés sont tout bonnement ignorées.

## appearanceTools : un raccourci pour activer un lot d'options

La nouveauté la plus visible de la v2 est la clé `appearanceTools`. En v1, activer les contrôles de bordure, d'espacement ou de couleur de lien pour les blocs supposait de déclarer chaque option une par une, bloc par bloc. Avec `appearanceTools` à `true` au niveau global, WordPress active en une fois :

- les contrôles de bordure (largeur, couleur, rayon)
- le padding, la marge et le `blockGap`
- la couleur des liens
- la hauteur de ligne du texte

Sur nos projets, cette clé nous fait gagner une dizaine de lignes de configuration à chaque nouveau thème, et surtout elle évite d'oublier une option que le client réclamera trois semaines plus tard.

> L'essentiel à retenir : appearanceTools active un lot d'options en une clé ; templates et styles d'éléments arrivent en v2 ; La v1 reste lue mais perd les nouveautés

## Styles d'éléments et templates personnalisés

La v2 introduit également la clé `styles.elements`, qui permet de styler globalement des éléments HTML transverses aux blocs : `link`, `heading`, `button`, `caption`. C'est une avancée réelle par rapport à la v1, où styler tous les liens du site obligeait à cibler chaque bloc individuellement dans une feuille CSS classique.

```
"styles": {
  "elements": {
    "link": {
      "color": { "text": "var(--wp--preset--color--accent)" },
      ":hover": {
        "color": { "text": "var(--wp--preset--color--contrast)" }
      }
    }
  }
}
```

Autre apport concret pour les auteurs de thèmes : la clé `customTemplates`, qui permet de déclarer, directement dans `theme.json`, les gabarits additionnels proposés à l'éditeur (par exemple un template « Page pleine largeur »), avec leur titre lisible et les types de contenus concernés. Avant la v2, cette information devait être placée en commentaire dans le fichier de template lui-même, une pratique héritée des thèmes classiques et assez peu naturelle dans un contexte bloc.

## Migrer un thème existant de la v1 vers la v2

Sur le projet associatif mentionné plus haut, la migration s'est faite en trois temps :

1. Changer `version` à `2` et mettre à jour `$schema`.
2. Repasser les clés `settings.color.palette`, `settings.typography` et consorts : leur structure ne change pas fondamentalement entre v1 et v2, mais certaines options renommées (comme le passage de `customGradient` à une organisation plus fine) méritent une relecture attentive.
3. Remplacer les règles CSS génériques du fichier `style.css` qui stylaient les liens ou les titres par l'équivalent en `styles.elements`, quand c'était pertinent.

Le point de vigilance principal concerne la rétrocompatibilité : un thème en v1 continue de fonctionner sous WordPress 6.0, mais il n'a accès à aucune des nouveautés listées ici. Il n'existe pas de mécanisme de migration automatique fourni par le cœur : la bascule reste manuelle, fichier par fichier.

> Sur un thème client, ne migrez jamais la version du schéma en même temps qu'une refonte visuelle. Faites la bascule technique seule, vérifiez que rien ne casse à l'écran, puis seulement ensuite ajoutez les nouveautés de la v2. Cela évite de chercher une régression dans deux changements à la fois.

## Ce qu'il ne faut pas confondre avec la v3

Ce guide couvre uniquement le passage de la v1 à la v2, tel qu'il se présente avec WordPress 6.0. Un schéma v3, avec son propre lot de nouveautés sur les presets par défaut, arrivera plus tard dans le cycle de WordPress ; nous y reviendrons le moment venu, sans anticiper ici des clés qui ne sont pas encore stabilisées.

## En résumé

Pour tout nouveau thème bloc démarré à partir de WordPress 6.0, la v2 doit être le point de départ par défaut : elle n'apporte aucune contrainte supplémentaire par rapport à la v1 et débloque des fonctionnalités que les clients demandent régulièrement, en particulier les styles de liens et les gabarits personnalisés déclarés proprement. Pour un thème déjà en production, la migration reste un chantier ciblé, à isoler de toute autre évolution visuelle ou fonctionnelle.