Un client utilisant un thème classique premium acheté sur une place de marché m’a signalé un comportement étrange : après avoir ajouté un fichier theme.json à son thème enfant pour définir une palette de couleurs personnalisée, rien ne changeait dans l’éditeur de blocs. Aucune erreur, aucun message, juste une absence totale d’effet, comme si le fichier n’existait pas.
Ce symptôme revient régulièrement en support depuis l’introduction de theme.json en version 5.8. Voici le diagnostic complet de cet héritage partiel, sans entrer dans la construction d’un thème hybride complet, qui est un chantier différent et plus large.
Symptôme : le fichier est bien là, rien ne se passe
Le thème enfant contenait un theme.json syntaxiquement valide, vérifié avec un validateur JSON en ligne, à la racine du dossier du thème enfant. Pourtant, la palette de couleurs personnalisée n’apparaissait pas dans l’éditeur, et les réglages d’espacement ne montraient aucun changement. Le client avait suivi un tutoriel généraliste sans remarquer qu’il s’appliquait à un thème bloc, pas à un thème classique.
Diagnostic : la condition d’activation de theme.json
Un fichier theme.json ne s’active pleinement que si le thème (parent ou enfant) a préalablement déclaré le support des fonctionnalités de l’éditeur de blocs correspondant. Sur un thème pleinement classique n’ayant jamais déclaré add_theme_support( 'wp-block-styles' ) ni les autres supports associés à Gutenberg, une partie substantielle des réglages de theme.json reste sans effet, car l’éditeur ne les consomme que dans un contexte où le thème a explicitement opté pour cette intégration plus poussée.
Vérification simple : rechercher les supports de thème déjà déclarés dans le thème parent premium.
grep -n "add_theme_support" wp-content/themes/theme-parent-premium/functions.php
Le résultat a confirmé l’absence totale de support des couleurs d’éditeur (editor-color-palette) et de la typographie fluide côté thème parent : celui-ci avait été conçu avant l’existence de theme.json et n’avait jamais été mis à jour pour l’accueillir, même partiellement.
Comprendre l’héritage entre thème parent et thème enfant
Un point souvent mal compris : un thème enfant ne peut pas, à lui seul, transformer un thème parent classique en thème compatible theme.json. L’héritage fonctionne dans un sens précis : si le parent est un vrai thème bloc, doté de son propre theme.json et de templates HTML dans un dossier templates/, l’enfant peut fournir son propre theme.json qui fusionne avec celui du parent, réglage par réglage. Mais si le parent est un thème purement classique, sans cette infrastructure, le theme.json de l’enfant n’a personne avec qui fusionner correctement, et une bonne partie de son potentiel reste lettre morte.
Ce qui fonctionne quand même partiellement
Certains réglages de theme.json restent utilisables même dans ce contexte hybride imparfait, car ils s’appuient sur des mécanismes plus anciens et indépendants de l’infrastructure complète des thèmes blocs. C’est notamment le cas de la section settings.color.palette, qui peut fonctionner de façon partielle car elle recoupe en interne le même mécanisme que add_theme_support( 'editor-color-palette' ). En revanche, les sections plus récentes comme settings.spacing.spacingScale ou styles.blocks nécessitent une intégration bien plus complète pour produire un effet visible.
{
"version": 2,
"settings": {
"color": {
"palette": [
{ "slug": "primaire", "color": "#1c3d5a", "name": "Bleu primaire" }
]
}
}
}
Le correctif appliqué : déclarer les supports manquants
Plutôt que de renoncer au theme.json, la correction retenue a consisté à ajouter dans le thème enfant les supports de thème classiques manquants, en complément du fichier JSON, pour que l’éditeur reconnaisse effectivement le contexte attendu.
function child_setup_theme_support() {
add_theme_support( 'wp-block-styles' );
add_theme_support( 'editor-styles' );
add_theme_support( 'responsive-embeds' );
}
add_action( 'after_setup_theme', 'child_setup_theme_support' );
Après l’ajout de ces trois supports, la palette de couleurs définie dans theme.json est apparue correctement dans l’éditeur. Les réglages plus avancés d’espacement et de style par bloc sont, eux, restés partiellement inactifs, confirmant que le thème parent n’était tout simplement pas conçu pour aller plus loin sans une réécriture plus profonde.
Prévention : vérifier le type de thème parent avant d’ajouter theme.json
- Avant d’ajouter un
theme.jsonà un thème enfant, vérifier si le thème parent possède un dossiertemplates/et son propretheme.json: c’est le signe d’un vrai thème bloc. - Sur un thème parent purement classique, ne pas attendre de
theme.jsonun effet complet : au mieux un effet partiel après ajout des supports classiques correspondants. - Documenter dans le thème enfant les limites connues, pour éviter qu’un futur intervenant reproduise le même diagnostic depuis zéro.
En résumé
Un theme.json ajouté à un thème enfant classique ne produit un effet complet que si le thème parent supporte déjà l’infrastructure des thèmes blocs. Sans cette base, seule une portion des réglages fonctionne, et encore partiellement, après avoir ajouté manuellement les supports de thème classiques correspondants. Construire un véritable thème hybride complet, avec templates HTML et fusion propre parent-enfant, reste un chantier distinct et plus ambitieux que ce simple ajout de fichier.
