# theme.json expliqué : la nouvelle façon de configurer un thème WordPress

> WordPress 5.8 introduit theme.json pour piloter réglages et styles des blocs. Structure, exemple concret et comparaison avec add_theme_support.

- Auteur : Clément Hadrot
- Publié le : 2021-06-22
- Mis à jour le : 2021-06-22
- Catégorie : FSE
- URL : https://wpmoderne.dev.wordpress-developpement.fr/fse/theme-json-guide-wordpress-5-8/

## L’essentiel

- Un seul fichier JSON pour réglages et styles, à la racine du thème
- Remplace progressivement add_theme_support et les feuilles CSS custom
- Génère automatiquement des classes CSS utilitaires

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.

> L'essentiel à retenir : Un seul fichier JSON pour réglages et styles, à la racine du thème ; Remplace progressivement add_theme_support et les feuilles CSS custom ; Génère automatiquement des classes CSS utilitaires

## 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.contentSize` et `layout.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 que `theme.json` n'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.