theme.json : le guide pratique des réglages et styles globaux

Thèmes & WordPress · Par la rédaction de Gabarit · Publié le 2026-10-27

Écran d'ordinateur portable affichant des lignes de code indentées, vu en biais, clavier au premier plan — Du code à l'écran. Photographie d'Artem Sapegin, CC0 (Wikimedia Commons).

Dans un thème blocs, l'essentiel de l'apparence ne se règle plus dans la feuille de style mais dans un fichier JSON placé à la racine du thème. Couleurs, typographie, espacements, largeurs de mise en page, réglages proposés ou cachés dans l'éditeur : tout part de theme.json. Voici comment il est organisé et comment l'utiliser sans se piéger.

Un fichier, plusieurs rôles

Le manuel des thèmes présente theme.json comme un fichier utile « pour configurer les couleurs comme pour définir la typographie par défaut ». En pratique, il joue trois rôles à la fois. Il déclare des préréglages : une palette de couleurs, une échelle de tailles de police, des familles de polices, des espacements. Il applique des styles, au site entier, à des éléments (liens, titres, boutons) ou à des blocs précis. Enfin, il encadre l'éditeur : il peut masquer le choix de couleurs libres, limiter les tailles de police à l'échelle du thème, ou désactiver un réglage pour un bloc donné.

Ces réglages ne sont pas figés. L'interface Styles de l'éditeur de site lit theme.json et permet à la personne qui gère le site de modifier les valeurs ; ses choix sont enregistrés en base de données et se superposent à ceux du fichier. Le fichier du thème fixe donc le point de départ et les limites, pas forcément le résultat final.

Les grandes sections

La page « Introduction to theme.json » du manuel liste les propriétés de premier niveau :

Propriété	Rôle
`$schema`	Adresse du schéma JSON : l'éditeur de code propose alors l'autocomplétion et signale les erreurs.
`version`	Version du format visée par le fichier.
`settings`	Contrôles des blocs, préréglages et options proposés dans l'éditeur.
`styles`	Couleurs, tailles de police, CSS personnalisée et autres styles appliqués.
`customTemplates`	Métadonnées des gabarits personnalisés du dossier `/templates`.
`templateParts`	Métadonnées des parties de gabarit du dossier `/parts` (en-tête, pied de page…).
`patterns`	Liste de compositions à charger depuis le répertoire de patterns de WordPress.org.

Un fichier minimal ressemble à ceci :

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "custom": false,
      "palette": [
        { "slug": "base", "color": "#fffefa", "name": "Fond" },
        { "slug": "contrast", "color": "#151a2d", "name": "Texte" },
        { "slug": "accent", "color": "#2f3fd6", "name": "Accent" }
      ]
    },
    "layout": { "contentSize": "42rem", "wideSize": "72rem" }
  },
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--base)",
      "text": "var(--wp--preset--color--contrast)"
    }
  }
}

La question de la version

Le champ version n'est pas décoratif : il dit à WordPress comment interpréter le reste du fichier. La « Living Reference » de l'éditeur de blocs indique qu'elle décrit la version 3 du format, qui « fonctionne avec WordPress 6.6 ou plus récent ». Elle renvoie vers les spécifications des versions 1 et 2, et vers un guide pour migrer depuis les anciennes versions. Certaines pages plus anciennes du manuel des thèmes parlent encore de la version 2 comme de la version courante : en cas de doute, c'est la référence de l'éditeur de blocs qui fait foi.

Conséquence pratique : un thème qui déclare la version 3 suppose un WordPress à jour. Si le thème doit fonctionner sur des installations plus anciennes, il faut soit rester sur une version antérieure du format, soit déclarer une version minimale de WordPress dans l'en-tête de style.css.

Des préréglages aux variables CSS

C'est le mécanisme le plus utile à comprendre. Pour chaque préréglage déclaré dans settings, WordPress génère une propriété personnalisée CSS. La page du manuel consacrée aux couleurs l'énonce ainsi : WordPress produit des variables « de la forme --wp--preset--{type}--{slug} ». Une couleur de palette dont le slug est contrast devient donc --wp--preset--color--contrast.

WordPress génère aussi, dans certains cas, des classes : la même couleur appliquée comme couleur de texte d'un bloc produit .has-contrast-color, et comme fond .has-contrast-background-color. D'autres sections suivent leur propre logique. Les valeurs libres placées sous settings.custom deviennent des variables de la forme --wp--custom--{clé}--{sous-clé}, et le réglage d'espacement entre blocs (blockGap) produit --wp--style--block-gap.

Bon réflexe

Choisir des slugs qui décrivent un rôle (base, contrast, accent) plutôt qu'une teinte (bleu) : la teinte peut changer, le rôle reste.
Utiliser les variables générées dans style.css au lieu de répéter les valeurs hexadécimales.
Garder les mêmes slugs d'une variation de style à l'autre, pour que le contenu existant change d'apparence sans être modifié.

Encadrer l'éditeur sans le brider

Beaucoup de réglages de settings sont des interrupteurs. "custom": false dans la section couleur retire le sélecteur de couleur libre : seules les couleurs de la palette restent proposées. Des options équivalentes existent pour les tailles de police ou les dégradés. On peut aussi définir des réglages par bloc, sous settings.blocks, pour autoriser une option sur un bloc et pas sur les autres.

Ces limites protègent la charte graphique, mais elles servent aussi l'accessibilité. Une palette restreinte, dont chaque combinaison texte-fond a été vérifiée, évite qu'un rédacteur choisisse un gris clair sur fond blanc. Notre article sur les contrastes de couleurs rappelle les ratios à respecter.

Les erreurs les plus courantes

Un JSON invalide. Une virgule de trop et WordPress ignore le fichier. Déclarer le $schema permet à l'éditeur de code de signaler l'erreur immédiatement.
Des styles qui ne s'appliquent pas. Souvent parce que des personnalisations enregistrées dans l'éditeur de site prennent le pas sur le fichier. Il faut les réinitialiser pour voir l'effet d'une modification du thème.
Des valeurs en dur partout. Une couleur écrite directement dans un gabarit ou dans la feuille de style échappe aux variations et à l'interface Styles.
Une version de format incohérente avec la version minimale de WordPress déclarée par le thème.

Bien tenu, theme.json devient la source unique de vérité du design : un endroit où lire, d'un coup d'œil, la palette, l'échelle typographique et les largeurs du site. C'est aussi le meilleur point d'entrée pour comprendre comment fonctionne un thème blocs.

Sources

WordPress Developer Resources, Theme Handbook, « Introduction to theme.json » et « Global Settings and Styles » (consultés le 27 octobre 2026).
Block Editor Handbook, « Theme.json Reference — Version 3 » (consulté le 27 octobre 2026).
WordPress Developer Resources, Theme Handbook, « Color » (réglages de couleur, consulté le 27 octobre 2026).