Comparé côte à côte, le panneau Customizer d’un thème hybride et son fichier theme.json déclaraient parfois exactement le même réglage sous deux formes différentes : une largeur de contenu définie à la fois via customize_register et via la clé settings.layout.contentSize de theme.json, chacune écrasant potentiellement l’autre selon l’ordre de chargement.
Ce qu’on observe dans ce genre de thème
Un thème hybride, construit à l’origine comme thème classique puis progressivement doté d’un fichier theme.json pour profiter des blocs, garde souvent son ancien panneau Customizer intact par habitude, sans jamais vérifier si les réglages qu’il propose font désormais doublon avec ceux que theme.json couvre nativement depuis la version 5.8 de WordPress, puis de façon stabilisée à partir de la 5.9.
Sur ce projet, neuf réglages du Customizer reproduisaient des fonctionnalités déjà disponibles dans theme.json : largeur de contenu, largeur large, espacement entre blocs, palette de couleurs, tailles de police. Chacun de ces réglages Customizer modifiait des variables CSS personnalisées via wp_add_inline_style, en parallèle des styles déjà générés automatiquement par WordPress à partir de theme.json.
Pourquoi c’est un problème
Deux sources de vérité pour un même réglage créent une ambiguïté difficile à déboguer : un contributeur qui modifie theme.json pour ajuster la largeur de contenu peut voir son changement silencieusement écrasé par la valeur retournée par le Customizer, sans message d’erreur, simplement parce que le CSS généré par le Customizer se charge après celui de theme.json dans l’ordre des feuilles de style.
Ce doublon complique aussi l’expérience de l’éditeur de blocs : les contrôles natifs de l’éditeur, alimentés par theme.json, proposent une valeur qui ne correspond pas toujours à ce qu’affiche réellement la page, faussée par le réglage Customizer parallèle. L’utilisateur qui personnalise une page dans l’éditeur ne comprend plus pourquoi son réglage n’a pas d’effet visible.
Quoi faire : migrer réglage par réglage
- Lister chaque réglage Customizer déclaré via
customize_registerdans le thème - Vérifier, pour chacun, s’il existe une clé équivalente dans le schéma de
theme.json(settings.layout,settings.color.palette,settings.typography.fontSizes) - Reporter la valeur actuellement choisie par les utilisateurs vers
theme.json, avant de retirer le contrôle Customizer correspondant - Ne retirer un contrôle Customizer qu’après avoir confirmé, sur un environnement de test, que le rendu reste identique
Cette migration se fait un réglage à la fois, jamais en bloc, car certains réglages Customizer n’ont effectivement aucun équivalent dans theme.json — les réglages liés au logo ou aux menus de navigation classiques, par exemple, restent légitimement dans le Customizer via add_theme_support( 'custom-logo' ).
Ce qui reste légitimement au Customizer
- Le logo personnalisé et les réglages associés
- Les couleurs propres à des widgets classiques encore utilisés sur certaines zones du site
- Les options qui ne concernent pas la mise en page ou les styles de blocs
Un signal qui aide à repérer ce doublon rapidement
Un indice fiable pour détecter ce genre de redondance sans avoir à comparer manuellement chaque réglage : ouvrir la console du navigateur sur le site en question et observer les variables CSS personnalisées déclarées deux fois dans des règles distinctes, l’une générée par le style engine à partir de theme.json, l’autre injectée par wp_add_inline_style depuis le Customizer. Deux définitions de la même variable, dans deux blocs <style> séparés, trahissent presque toujours ce type de doublon.
Ce signal se repère aussi plus simplement dans le code source du thème : une recherche de customize_register croisée avec le contenu de theme.json suffit, sans avoir besoin d’ouvrir le site en production, à condition de connaître la liste des clés que theme.json couvre nativement pour la mise en page et la typographie.
Un doublon de réglages ne se voit pas tant que personne ne modifie l’un des deux ; le jour où quelqu’un le fait, le diagnostic prend plus de temps que la migration elle-même.
En résumé
Un Customizer parallèle à theme.json part souvent d’une bonne intention : ne pas casser ce qui fonctionnait avant l’arrivée des blocs. Mais laisser cohabiter deux systèmes qui gèrent les mêmes réglages finit par produire des incohérences difficiles à tracer. La migration progressive, réglage par réglage, permet de simplifier le thème sans jamais retirer une fonctionnalité que les utilisateurs utilisaient réellement.
