Deux thèmes hybrides installés en parallèle : quel theme.json l’emporte

Un thème enfant activé, un fichier theme.json ajouté à sa racine, et pourtant certaines couleurs affichées sur le site ne correspondent à aucune des deux palettes déclarées — ni celle du thème enfant, ni celle du thème parent tel qu’on pensait le connaître. Ce genre de résultat surprenant a presque toujours la même origine : une mauvaise hypothèse sur la façon dont WordPress fusionne deux fichiers theme.json plutôt qu’un remplacement pur et simple de l’un par l’autre.

Le mécanisme de fusion, pas de remplacement

Quand un thème enfant possède son propre theme.json, WordPress ne l’utilise pas à la place de celui du thème parent : il fusionne les deux, en donnant priorité aux valeurs déclarées côté enfant quand elles existent, et en conservant les valeurs du parent pour tout ce que l’enfant ne redéclare pas. Cette fusion s’opère récursivement, propriété par propriété, pas fichier entier contre fichier entier.

Concrètement, si le thème parent déclare une palette de dix couleurs et que le thème enfant n’en déclare que deux, le résultat final ne contient pas seulement ces deux couleurs : il contient les dix couleurs du parent, avec les deux couleurs de l’enfant qui viennent soit s’ajouter, soit remplacer celles qui portent le même identifiant (slug).

Le piège des tableaux contre les objets

C’est ici que se cache la source la plus fréquente de surprise. Les propriétés de theme.json organisées en objets (comme les styles d’un bloc précis) fusionnent proprement, propriété par propriété. Mais certaines propriétés sont des tableaux numériques — la liste des couleurs de palette en est l’exemple le plus courant. Le comportement de fusion sur les préréglages (couleurs, dégradés, tailles) suit une règle particulière : chaque entrée est identifiée par son slug, et une entrée de l’enfant portant le même slug qu’une entrée du parent remplace bien cette entrée précise, sans toucher aux autres.

Le problème survient quand un thème enfant redéclare une palette avec des slug différents de ceux du parent, en pensant remplacer entièrement la liste : dans ce cas, les deux jeux de couleurs coexistent dans le résultat final, ce qui explique la présence de couleurs qu’on pensait avoir supprimées.

Vérifier le résultat réellement fusionné

Plutôt que de deviner à partir des deux fichiers sources, l’inspection directe du résultat fusionné évite toute mauvaise interprétation. La commande WP-CLI suivante affiche les styles globaux tels qu’effectivement résolus par WordPress, thème enfant compris :

wp eval 'echo wp_json_encode( WP_Theme_JSON_Resolver::get_merged_data()->get_raw_data(), JSON_PRETTY_PRINT );'

Le résultat de cette commande correspond exactement à ce que l’éditeur de site utilise pour construire ses styles, ce qui permet de comparer directement cette sortie aux deux fichiers sources et de repérer où la fusion diverge de l’intuition initiale.

Corriger une palette qu’on pensait remplacée

Pour réellement supprimer une couleur héritée du parent plutôt que d’en ajouter une nouvelle à côté, le thème enfant doit redéclarer l’intégralité de la palette avec les mêmes slug que ceux à conserver, en omettant ceux à retirer :

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        { "slug": "primaire", "color": "#1d3557", "name": "Primaire" },
        { "slug": "accent",   "color": "#e63946", "name": "Accent" }
      ]
    }
  }
}

Si la palette du parent contenait d’autres slug non repris ici, ils disparaissent bien du résultat final, à condition que le thème enfant ait explicitement redéclaré la totalité de la liste souhaitée plutôt qu’un sous-ensemble additif.

Ce qu’il faut vérifier en priorité face à ce symptôme

• Comparer les slug utilisés côté parent et côté enfant pour la propriété concernée, pas seulement les valeurs affichées.
• Utiliser la commande d’inspection du résultat fusionné avant toute hypothèse sur la cause.
• Se rappeler que la fusion s’applique à toutes les sections de theme.json — couleurs, typographie, espacements — pas uniquement aux couleurs, qui sont simplement le cas le plus visible.

Sur les projets construits autour d’un thème parent partagé, l’habitude qu’on garde : jamais de supposition sur le résultat d’une fusion de theme.json sans être passé par l’inspection du résultat réellement résolu.

En résumé

Un style inattendu après l’activation d’un thème enfant vient presque toujours d’une fusion mal anticipée entre deux fichiers theme.json, et non d’un bug du cœur. Le comportement de fusion par slug sur les listes de préréglages explique la grande majorité de ces cas, une fois qu’on sait où regarder.