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

> Symptôme, diagnostic, correctif et prévention pour un panneau Styles qui s'affiche vide après la mise à jour d'un thème bloc ayant changé la structure de son theme.json.

- Auteur : Clément Hadrot
- Publié le : 2025-12-31
- Mis à jour le : 2025-12-31
- Catégorie : FSE
- URL : https://wpmoderne.dev.wordpress-developpement.fr/fse/panneau-styles-vide-theme-json-invalide/

## L’essentiel

- Le panneau se charge mais reste vide
- La structure JSON est valide, la logique ne l'est pas
- Prévenir avec une validation avant déploiement

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.

> L'essentiel à retenir : Le panneau se charge mais reste vide ; La structure JSON est valide, la logique ne l'est pas ; Prévenir avec une validation avant déploiement

```
{
    "$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.