Le panneau Styles reste vide : diagnostiquer une structure theme.json invalide

Le panneau Styles s’ouvre normalement, aucun message d’erreur n’apparaît dans la console du navigateur, et pourtant : rien. Pas de section couleurs, pas de section typographie, un panneau vide qui ne réagit à aucun clic. C’est le symptôme rapporté après la mise à jour d’un thème bloc dont la structure de theme.json venait de changer entre deux versions.

Ce type de panne est particulièrement frustrant parce qu’elle ne produit aucune trace visible côté serveur : PHP ne remonte aucune erreur fatale, le site continue de s’afficher correctement en façade. Seul le panneau Styles, dans l’éditeur de site, refuse de se peupler.

Symptôme : un panneau qui charge sans rien afficher

En ouvrant les outils de développement du navigateur pendant le chargement du panneau, la requête vers wp-json/wp/v2/global-styles répond bien avec un code 200, mais le contenu retourné est incomplet ou structurellement différent de ce qu’attend l’éditeur. Aucune exception PHP n’est levée côté serveur : le fichier theme.json est syntaxiquement valide, ce qui explique l’absence totale d’erreur visible.

Diagnostic : une structure valide en JSON, invalide pour Gutenberg

La confusion vient de là : un fichier peut être un JSON parfaitement valide tout en étant rejeté silencieusement par le mécanisme de fusion des styles de WordPress, parce qu’il ne respecte pas le schéma attendu. Le cas le plus fréquent après une mise à jour de thème : la clé version a été incrémentée sans que la structure interne des settings ne suive les changements attendus pour ce numéro de schéma.

{
    "$schema": "https://schemas.wp.org/trunk/theme.json",
    "version": 3,
    "settings": {
        "color": {
            "palette": "à corriger : doit être un tableau, pas une chaîne"
        }
    }
}

Ici, la valeur de palette a été renseignée comme une simple chaîne de caractères au lieu d’un tableau d’objets couleur. Le fichier reste un JSON valide au sens strict, mais le schéma de theme.json attend une structure précise que la fonction WP_Theme_JSON::get_settings() ne parvient pas à interpréter, sans pour autant lever d’exception bloquante.

Isoler la source avec WP-CLI

La commande suivante permet de valider la structure sans passer par l’interface graphique, en s’appuyant sur le schéma officiel publié par le projet :

wp eval 'var_dump( wp_get_global_settings() );' --path=/var/www/site

Si le tableau retourné est anormalement vide ou tronqué par rapport à ce qui est attendu, la source du problème se situe bien dans la structure du fichier plutôt que dans un cache ou une extension tierce.

Correctif : revenir au schéma attendu section par section

1. Comparer le fichier theme.json actuel avec la version précédente du thème, section par section, en commençant par settings.color et settings.typography.
2. Valider chaque section isolément en la collant dans un validateur JSON Schema pointant vers le schéma officiel https://schemas.wp.org/trunk/theme.json.
3. Corriger la structure incriminée, ici en transformant palette en tableau d’objets avec les clés slug, color et name attendues.
4. Vider le cache d’objets si un système de cache persistant est actif, car les styles globaux peuvent y être mis en cache après un premier chargement défaillant.

Prévention : valider avant chaque déploiement

Ajouter le schéma officiel en en-tête du fichier, via la clé $schema, permet à la plupart des éditeurs de code modernes de signaler l’erreur de structure avant même le déploiement, directement dans l’environnement de développement. C’est une prévention gratuite qui aurait évité l’incident sur ce thème bloc mis à jour sans cette vérification préalable.

Un theme.json syntaxiquement valide n’est pas nécessairement un theme.json utilisable : le schéma compte autant que la syntaxe.

Ce qu’il faut retenir

Un panneau Styles vide sans erreur visible pointe presque toujours vers une structure de theme.json non conforme au schéma attendu, plutôt que vers une panne serveur classique. La comparaison section par section entre versions du thème, complétée par une validation via le schéma officiel, reste la méthode la plus rapide pour retrouver la section fautive sans tout réécrire depuis zéro.