Jusqu’à présent, configurer les capacités d’un thème passait par une accumulation d’appels à add_theme_support() dans functions.php, complétés par des feuilles de styles CSS pour tout le reste. Ça fonctionne, mais ça éparpille la configuration entre plusieurs fichiers, plusieurs syntaxes, et surtout ça ne dialogue pas nativement avec l’éditeur de blocs.
WordPress 5.8, sorti en juillet 2021, change la donne avec l’arrivée de theme.json. Ce fichier unique, placé à la racine du thème, centralise à la fois les réglages disponibles dans l’éditeur et les styles par défaut appliqués au site. Voici comment il fonctionne, et pourquoi il mérite qu’on migre dès maintenant les nouveaux projets.
Pourquoi un nouveau fichier de configuration
L’éditeur de blocs a besoin de savoir, pour chaque bloc, quelles options proposer : quelles couleurs afficher dans la palette, si la taille de police est réglable, si les marges sont personnalisables. Avant theme.json, cette information passait par des tableaux PHP disséminés dans add_theme_support( 'editor-color-palette', ... ) et consorts.
Le problème, c’est que ces réglages ne produisaient aucun style réel : il fallait ensuite recopier à la main les mêmes valeurs dans une feuille CSS, au risque de désynchroniser les deux. theme.json résout ce doublon en devenant la source unique de vérité : WordPress lit le fichier, configure l’éditeur en conséquence, et génère automatiquement les styles CSS correspondants côté front.
La structure du fichier
Un fichier theme.json se compose principalement de deux grandes sections :
settings: définit ce que l’utilisateur peut régler dans l’éditeur (palettes de couleurs, échelle typographique, unités d’espacement autorisées, etc.) ;styles: applique des styles par défaut au site et aux blocs, sans passer par une feuille CSS séparée.
On y trouve aussi une clé version, obligatoire, qui indique le schéma utilisé par WordPress pour interpréter le fichier. Voici un exemple réaliste pour un thème de blog simple :
{
"version": 1,
"settings": {
"color": {
"palette": [
{
"slug": "primaire",
"color": "#1e3a5f",
"name": "Bleu primaire"
},
{
"slug": "accent",
"color": "#e07a3f",
"name": "Orange accent"
},
{
"slug": "sombre",
"color": "#1a1a1a",
"name": "Texte sombre"
}
]
},
"typography": {
"fontSizes": [
{
"slug": "petit",
"size": "14px",
"name": "Petit"
},
{
"slug": "normal",
"size": "18px",
"name": "Normal"
},
{
"slug": "grand",
"size": "32px",
"name": "Grand"
}
],
"customFontSize": false
},
"spacing": {
"units": ["px", "%", "em", "rem"],
"customPadding": true
}
},
"styles": {
"color": {
"background": "#ffffff",
"text": "#1a1a1a"
},
"typography": {
"fontSize": "18px",
"lineHeight": "1.6"
},
"blocks": {
"core/heading": {
"color": {
"text": "#1e3a5f"
}
}
}
}
}
Chaque entrée de palette ou d’échelle typographique génère automatiquement une classe CSS utilitaire. La couleur accent produit par exemple .has-accent-color et .has-accent-background-color, directement utilisables dans l’éditeur sans écrire une ligne de CSS supplémentaire.
settings : ce que l’utilisateur peut régler
La section settings agit comme un tableau de bord de permissions. Elle ne définit aucun style directement : elle indique quelles options sont proposées, et éventuellement les valeurs prédéfinies parmi lesquelles choisir. On y configure notamment :
color.palette: la liste des couleurs proposées dans les sélecteurs de couleur ;color.custom: autorise ou non le sélecteur de couleur libre (roue chromatique) ;typography.fontSizes: l’échelle de tailles de police disponibles ;spacing.units: les unités autorisées pour les marges et espacements internes ;layout.contentSizeetlayout.wideSize: les largeurs de contenu standard et large, utilisées notamment par le bloc groupe.
Il est possible d’affiner ces réglages par bloc, en les imbriquant sous une clé blocks, pour par exemple désactiver la personnalisation de couleur sur un bloc précis tout en la laissant ouverte ailleurs.
styles : appliquer des valeurs par défaut
La section styles reprend une structure très proche de settings, mais avec un objectif différent : elle applique réellement des styles, au niveau global du site ou d’un bloc spécifique. C’est un vrai changement d’approche par rapport à une feuille style.css classique : ici, les styles sont déclarés en JSON et WordPress se charge de générer le CSS correspondant, avec une spécificité maîtrisée.
Cibler un bloc précis se fait via la clé styles.blocks, en utilisant le nom complet du bloc comme dans l’exemple ci-dessus avec core/heading. Cette approche permet de styliser les blocs natifs sans écrire le moindre sélecteur CSS, ni se soucier de la spécificité des règles générées par le cœur de WordPress.
theme.json face à add_theme_support
La comparaison avec l’ancienne méthode est éclairante :
| Besoin | Avant (functions.php) | Avec theme.json |
|---|---|---|
| Palette de couleurs | add_theme_support('editor-color-palette', $colors) | Clé settings.color.palette |
| Tailles de police | add_theme_support('editor-font-sizes', $sizes) | Clé settings.typography.fontSizes |
| Application des styles au front | Feuille CSS séparée, à synchroniser à la main | Générée automatiquement depuis styles |
| Largeur de contenu | Variables CSS personnalisées | Clé settings.layout |
L’avantage principal n’est pas seulement la centralisation : c’est la cohérence garantie entre ce que l’éditeur affiche et ce que le front rend réellement. Fini les palettes qui existent dans l’éditeur mais ne correspondent à aucune classe CSS effective sur le site.
Sur un projet en cours de migration, gardez
add_theme_support()en parallèle tant quetheme.jsonn’est pas complet : les deux systèmes coexistent sans conflit, ce qui permet une transition progressive plutôt qu’une bascule brutale.
En résumé
theme.json n’est pas un simple gadget de configuration : c’est la pierre angulaire d’une nouvelle façon de penser les thèmes WordPress, où la frontière entre réglages d’éditeur et styles front s’efface. Pour un thème classique, l’adopter dès aujourd’hui simplifie déjà la maintenance des palettes et de la typographie.
C’est aussi, sans grande surprise, une brique indispensable pour tout ce qui touche à l’édition de site (FSE) que le plugin Gutenberg explore depuis plusieurs mois en version expérimentale. Comprendre theme.json maintenant, c’est se donner une longueur d’avance sur les évolutions qui arrivent.
