Depuis le début de l’année, j’ai structuré une offre d’audit technique pour les agences qui héritent d’un site FSE existant et veulent en connaître l’état réel avant de s’engager sur une maintenance. En reprenant mes notes sur une trentaine d’audits menés depuis janvier, dix erreurs de configuration de theme.json reviennent avec une régularité frappante, tous secteurs confondus.
Voici ce constat organisé selon la méthode que j’applique systématiquement en audit : ce qu’on observe, pourquoi c’est un problème concret, et ce qu’il faut faire pour corriger.
1. Une version de schéma obsolète
Ce qu’on voit : un fichier déclarant encore "version": 1, hérité d’un thème créé avant la generalisation du schéma version 2.
Pourquoi c’est un problème : plusieurs réglages introduits depuis, comme les espacements personnalisés ou les tailles de police fluides, ne fonctionnent tout simplement pas avec l’ancien schéma, sans message d’erreur explicite.
Quoi faire : migrer vers "version": 2, en revalidant chaque section du fichier contre le schéma officiel disponible sur la documentation du bloc-editor.
2. Des couleurs codées en dur malgré une palette définie
Ce qu’on voit : une palette de couleurs propre déclarée dans theme.json, mais des blocs individuels avec des couleurs en style inline (style="color:#1d3557") au lieu de la classe has-primaire-color correspondante.
Pourquoi c’est un problème : un futur changement de palette globale, demandé par le client pour un rebranding, ne touche jamais ces blocs codés en dur, créant des incohérences visuelles ponctuelles impossibles à corriger globalement.
Quoi faire : rechercher systématiquement le motif style="color dans un export du contenu, et remplacer par les classes de palette natives.
3. Des presets de couleur ou d’espacement jamais utilisés
Ce qu’on voit : dix ou douze couleurs déclarées dans theme.json, dont seulement quatre ou cinq réellement utilisées dans le contenu du site.
Pourquoi c’est un problème : chaque preset génère des classes CSS correspondantes, chargées sur toutes les pages, ce qui gonfle inutilement la feuille de style générée, sans bénéfice pour l’utilisateur final.
Quoi faire : nettoyer la palette pour ne conserver que les couleurs réellement utilisées, quitte à en ajouter une nouvelle plus tard si un besoin apparaît.
4. L’absence de appearanceTools
Ce qu’on voit : des réglages activés un par un (border, spacing, typography) de façon incomplète, plutôt que le raccourci global disponible depuis la 5.9.
Quoi faire : activer "appearanceTools": true dans les réglages globaux, qui active en une fois l’ensemble des contrôles de bordure, d’espacement et de typographie avancée, sauf exception explicitement désactivée ensuite.
5. Une police personnalisée non déclarée dans fontFamilies
Ce qu’on voit : une police importée via une feuille de style additionnelle, mais jamais référencée dans settings.typography.fontFamilies.
Pourquoi c’est un problème : l’éditeur ne propose pas cette police dans son sélecteur natif, poussant les utilisateurs à définir un style personnalisé bloc par bloc, incohérent d’une page à l’autre.
6. Des espacements en pixels codés en dur dans le contenu
Ce qu’on voit : des marges définies en valeur fixe (32px) sur des blocs individuels, plutôt que via les presets d’espacement de theme.json (var(--wp--preset--spacing--50)).
Quoi faire : déclarer une échelle d’espacement cohérente et l’imposer via spacingSizes, avec "custom": false pour empêcher les valeurs libres à l’avenir.
7. Un fichier theme.json qui ne correspond plus aux styles réellement affichés
Ce qu’on voit : des couleurs affichées sur le site qui ne correspondent à aucune valeur du fichier theme.json versionné en Git, signe que des modifications ont été faites depuis la zone Styles de l’éditeur sans jamais être exportées dans le code.
Pourquoi c’est un problème : en cas de restauration depuis une sauvegarde de code sans la base de données, ces personnalisations disparaissent silencieusement.
8. Des tailles de police non fluides sur un projet récent
Ce qu’on voit : des tailles de police fixes en pixels sur un thème créé après la 6.1, qui a pourtant introduit la typographie fluide nativement.
Quoi faire : utiliser "fluid": true avec des valeurs min et max par taille, pour un texte qui s’adapte à la largeur d’écran sans média query manuelle.
9. L’absence de couleurs de fond et de texte par défaut
Ce qu’on voit : aucune couleur de fond ni de texte définie dans la section styles globale, laissant le rendu dépendre entièrement du navigateur ou d’une feuille de style externe non documentée.
10. Des styles d’éléments qui contredisent les blocs
Ce qu’on voit : une couleur de lien définie dans styles.elements.link, contredite par une couleur différente appliquée directement sur des blocs individuels contenant des liens, créant une incohérence visuelle selon l’endroit du site.
| Fréquence observée | Erreur |
|---|---|
| 27 sur 30 audits | Couleurs codées en dur malgré une palette définie |
| 21 sur 30 audits | Presets jamais utilisés |
| 14 sur 30 audits | Absence d’appearanceTools |
Un theme.json propre ne se mesure pas à sa longueur, mais à la cohérence entre ce qu’il déclare et ce qui est réellement utilisé dans le contenu du site.
Notre verdict
La majorité de ces erreurs ne cassent rien visuellement à court terme, ce qui explique qu’elles survivent des années sans être corrigées. Elles pèsent en revanche lourdement sur la maintenabilité et la cohérence du site dès qu’un changement de palette ou de typographie est demandé par le client, ce qui en fait un excellent point d’entrée pour toute offre d’audit FSE structurée.
