Que mettre dans un fichier theme.json WordPress

Un fichier theme.json WordPress est un fichier JSON placé à la racine d’un thème de blocs. Il déclare une seule fois les design tokens du thème (couleurs, tailles de police, familles de polices, espacements et largeurs de mise en page), afin que l’éditeur de blocs et le front-end lisent exactement les mêmes valeurs.

Si vous avez l’habitude des pipelines de design tokens, ce fichier vous semblera familier, jusqu’au moment où vous chercherez le CSS qu’il génère ou essaierez de comprendre pourquoi un thème enfant a effacé la moitié de la palette. Cet article passe en revue chaque partie du fichier, montre le CSS que WordPress en génère, explique comment utiliser ces variables dans votre propre feuille de style et précise les cas où du CSS écrit à la main reste nécessaire. Tous les exemples utilisent la version 3 du schéma, introduite avec WordPress 6.6.

Qu’est-ce que theme.json ?

theme.json est le fichier de design tokens d’un thème de blocs. Vous y déclarez une seule fois les couleurs, la typographie, les espacements et les largeurs de mise en page. WordPress utilise ensuite ces valeurs pour construire les contrôles de l’éditeur et générer la feuille de style du front-end. Le premier niveau est restreint : $schema, version, settings et styles, auxquels s’ajoutent customTemplates, templateParts et patterns pour enregistrer des modèles, des éléments de modèle et des compositions du répertoire de compositions.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {},
  "styles": {}
}

Faire pointer $schema vers le schéma theme.json de trunk vous donne l’autocomplétion et la validation dans VS Code.

Pourquoi theme.json existe-t-il ?

theme.json remplace trois éléments qui avaient tendance à se désynchroniser : les options add_theme_support() en PHP, la configuration de l’éditeur et le CSS du front-end. Le guide des réglages globaux du Block Editor Handbook fait correspondre chaque ancienne option add_theme_support à une clé theme.json. Si un thème définit le même réglage aux deux endroits, c’est la valeur de theme.json qui l’emporte.

Que contient settings ?

settings contrôle ce que propose l’éditeur : quels préréglages apparaissent dans les sélecteurs et quels contrôles libres sont autorisés. Les préréglages sont des tableaux d’objets comportant chacun un slug, une valeur et un nom d’affichage (name).

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "appearanceTools": true,
    "color": {
      "custom": false,
      "customGradient": false,
      "defaultPalette": false,
      "palette": [
        { "slug": "ink", "color": "#1b1f24", "name": "Ink" },
        { "slug": "accent", "color": "#3b5bdb", "name": "Accent" }
      ]
    },
    "typography": {
      "customFontSize": false,
      "defaultFontSizes": false,
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" },
        { "slug": "large", "size": "1.5rem", "name": "Large" }
      ],
      "fontFamilies": [
        { "slug": "system", "fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif", "name": "System" }
      ]
    },
    "spacing": { "blockGap": true, "units": ["px", "rem", "%"] },
    "layout": { "contentSize": "720px", "wideSize": "1100px" },
    "custom": { "radius": { "card": "12px" } }
  }
}

Définir color.custom, customGradient et customFontSize à false supprime les sélecteurs libres : les rédacteurs ne peuvent alors choisir que parmi vos préréglages. defaultFontSizes: false a son importance en version 3. La note de développement sur theme.json version 3 explique qu’un thème v3 ne peut réutiliser les slugs de tailles de police et de tailles d’espacement par défaut du cœur que si defaultFontSizes ou defaultSpacingSizes est défini à false, or small et large sont tous deux des slugs du cœur. appearanceTools: true active un ensemble d’outils de design répertoriés dans la référence évolutive de theme.json. Si vous chargez des polices web pour fontFamilies, consultez comment auto-héberger des Google Fonts dans WordPress.

Chaque type de préréglage produit une sortie différente :

theme.json comporte deux clés custom sans rapport entre elles. settings.color.custom: false masque le sélecteur de couleur. settings.custom est un objet libre dont les valeurs deviennent des variables CSS.

Comment fonctionnent layout.contentSize et wideSize ?

layout.contentSize définit la largeur par défaut du contenu dans les mises en page contraintes. layout.wideSize définit la largeur des blocs alignés en « grande largeur » (wide). Le cœur expose ces deux valeurs sous la forme --wp--style--global--content-size et --wp--style--global--wide-size sur :root, depuis que la PR Gutenberg #42084 y a déplacé les propriétés personnalisées globales, auparavant déclarées sur body. Vos composants personnalisés peuvent ainsi s’aligner sur la grille des blocs :

.site-banner {
  max-width: var(--wp--style--global--wide-size);
  margin-inline: auto;
}

Que contient styles ?

styles applique des valeurs par défaut à trois niveaux. Les propriétés de premier niveau ciblent body, elements cible des éléments HTML comme link (qui correspond à a) et h1 à h6, et blocks cible chaque bloc par son nom. La section consacrée aux styles du Handbook documente chacun de ces niveaux.

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "styles": {
    "color": { "text": "var(--wp--preset--color--ink)" },
    "spacing": { "blockGap": "1.5rem" },
    "blocks": {
      "core/group": {
        "color": { "text": "var(--wp--preset--color--accent)" },
        "elements": {
          "h2": { "typography": { "fontSize": "var(--wp--preset--font-size--large)" } }
        }
      }
    }
  }
}

Résultat :

body {
  color: var(--wp--preset--color--ink);
}
:root :where(.wp-block-group) {
  color: var(--wp--preset--color--accent);
}
:root :where(.wp-block-group h2) {
  font-size: var(--wp--preset--font-size--large);
}

Depuis WordPress 6.6, l’encapsulation :root :where() maintient ces règles à une spécificité de 0-1-0, soit l’équivalent d’une seule classe. Toute règle du thème de spécificité égale ou supérieure chargée ensuite l’emporte. Les éléments link et button acceptent également des clés de pseudo-états comme ":hover" et ":focus".

Quel CSS WordPress génère-t-il à partir de theme.json ?

Tous les préréglages, à l’exception des filtres duotone, deviennent une propriété personnalisée CSS nommée --wp--preset--{category}--{slug}, et les préréglages qui génèrent des classes suivent le motif .has-{slug}-{category}. Les valeurs placées sous settings.custom deviennent des propriétés --wp--custom--. WordPress convertit les clés en camelCase en kebab-case et insère -- entre chaque niveau d’imbrication : custom.lineHeight.body devient ainsi --wp--custom--line-height--body. La FAQ du Handbook sur le nommage décompose ce nom segment par segment.

Avec les réglages et styles ci-dessus, la feuille de style globale contient une sortie de ce type. Les exemples du Handbook montrent body, mais le cœur actuel déclare ces propriétés sur :root, un changement introduit par la PR Gutenberg #42084 :

:root {
  --wp--preset--color--ink: #1b1f24;
  --wp--preset--color--accent: #3b5bdb;
  --wp--preset--font-size--large: 1.5rem;
  --wp--custom--radius--card: 12px;
  --wp--style--block-gap: 1.5rem;
}
.has-accent-color { color: var(--wp--preset--color--accent) !important; }

La valeur racine styles.spacing.blockGap est exposée sous la forme --wp--style--block-gap. La possibilité pour les rédacteurs de la modifier dépend de settings.spacing.blockGap :

Il s’agit de propriétés personnalisées ordinaires, que n’importe quelle feuille de style peut donc utiliser :

.pricing-card {
  background: var(--wp--preset--color--ink);
  color: #fff;
  border-radius: var(--wp--custom--radius--card);
  padding: var(--wp--style--block-gap);
  font-size: var(--wp--preset--font-size--large);
}

Si vous modifiez un token dans theme.json, ce composant est mis à jour en conséquence. La sortie de theme.json étant mise en cache, définissez WP_DEVELOPMENT_MODE à 'theme' dans wp-config.php pendant le développement.

Quelles sont les limites de theme.json, et comment les thèmes enfants se combinent-ils ?

theme.json ne couvre que les propriétés présentes dans son schéma de styles. Tout le reste relève du CSS :

• La mise en page du balisage qui n’est pas un bloc, comme la sortie d’extensions ou de services tiers
• Les animations, transitions et keyframes
• Les sélecteurs arbitraires non liés à un bloc ou à un élément
• La mise en forme de composants allant au-delà des propriétés de style disponibles (le guide thème WordPress responsive avec Bootstrap illustre l’approche centrée sur le CSS)

style.css reste obligatoire, car il contient l’en-tête du thème. Pour un thème enfant, le champ Template désigne le thème parent par le nom de son dossier dans wp-content/themes, orthographié exactement de la même manière, comme l’explique la page du Theme Handbook consacrée à la feuille de style principale :

/*
Theme Name: Studio Child
Template: studio
*/

Le theme.json d’un thème enfant est fusionné par-dessus celui du parent, mais toute liste de préréglages qu’il déclare remplace intégralement la liste du parent. Ce fichier enfant ne laisse qu’une seule couleur dans la palette :

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "accent", "color": "#c2255c", "name": "Accent" }
      ]
    }
  }
}

Pour modifier uniquement accent, copiez la palette complète et modifiez cette seule entrée :

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "ink", "color": "#1b1f24", "name": "Ink" },
        { "slug": "accent", "color": "#c2255c", "name": "Accent" }
      ]
    }
  }
}

Dans le theme.json d’un thème enfant, les clés d’objet que vous ne déclarez pas continuent d’hériter du parent. Si l’enfant ne définit que styles.spacing.padding.top et bottom, les marges internes gauche et droite du parent sont conservées. Lorsqu’un slug supprimé fait basculer du contenu vers une autre couleur sur le site en production, mais pas dans l’aperçu de l’éditeur, une relecture de session (session replay) du front-end permet d’identifier l’élément et le modèle qui ont perdu le préréglage.

Conclusion

theme.json est un fichier de tokens que WordPress compile en propriétés personnalisées, en classes utilitaires et en règles par défaut de faible spécificité. Placez les préréglages dans settings, les valeurs par défaut dans styles, et tout le reste dans du CSS qui exploite les variables --wp-- générées. Prochaine étape : ouvrez global-styles-inline-css dans les outils de développement de votre navigateur sur une page utilisant votre thème, et comparez les propriétés déclarées avec votre fichier. Tout token manquant révèle une erreur de slug ou de schéma que vous pourrez corriger avant qu’elle n’atteigne vos utilisateurs.

FAQ

Pourquoi une valeur modifiée dans theme.json n'apparaît-elle pas sur mon site ?

Une personnalisation enregistrée dans l'éditeur de site la remplace. Lorsqu'un utilisateur modifie les styles via Apparence > Éditeur, WordPress enregistre ce JSON dans la base de données du site, et le Theme Handbook place cette configuration utilisateur au-dessus des valeurs par défaut du cœur, du theme.json parent et du theme.json enfant. Vérifiez si le token a été personnalisé dans le panneau Styles, réinitialisez-le à cet endroit, puis rechargez le front-end.

Puis-je écrire du CSS brut dans theme.json ?

Oui. Depuis WordPress 6.2, theme.json accepte des chaînes CSS dans styles.css pour les règles globales, et dans la propriété css d'un bloc sous styles.blocks pour les règles propres à un bloc. Le CSS propre à un bloc apparaît pour ce bloc dans le panneau Styles, où les utilisateurs peuvent le modifier. Le CSS personnalisé de l'utilisateur peut remplacer ou supprimer le CSS de thème ajouté de cette façon : placez donc les règles dont dépend le design dans une feuille de style chargée via enqueue.

Un thème PHP classique peut-il utiliser theme.json ?

Oui. Un thème classique peut inclure un fichier theme.json pour configurer les réglages et préréglages de l'éditeur de blocs sans appels à add_theme_support, une configuration que la communauté appelle thème hybride. L'ajout de ce fichier n'en fait pas un thème de blocs, car WordPress ne considère un thème comme thème de blocs que s'il contient templates/index.html. Si le thème conserve certains appels à add_theme_support, tout réglage correspondant dans theme.json est prioritaire.

Comment lire les valeurs de theme.json en PHP ?

Appelez wp_get_global_settings() pour les réglages et wp_get_global_styles() pour les styles. Ces deux fonctions acceptent un tableau de chemin : wp_get_global_settings( array( 'color', 'palette', 'theme' ) ) renvoie ainsi uniquement les entrées de palette du thème. Un tableau de contexte comportant une clé block_name restreint la recherche à un seul bloc. Par défaut, le résultat inclut les personnalisations de l'utilisateur. Définissez origin à 'base' dans le tableau de contexte pour obtenir uniquement les valeurs du cœur et du thème.