« theme.json de l’enfant remplace, complète ou fusionne avec celui du parent ? » Cette question, posée telle quelle sur les forums de développeurs de thèmes hybrides, cache une réponse plus nuancée qu’il n’y paraît : cela dépend du niveau de la structure JSON concerné, et le comportement n’est pas uniforme.
Ce billet s’adresse aux auteurs de thèmes hybrides qui déboguent un preset de couleur qui ne s’applique pas comme prévu, en particulier lorsqu’un thème enfant redéfinit un preset déjà présent dans le thème parent. Il ne traite pas de l’autoload d’options, un sujet totalement distinct malgré une confusion parfois faite entre les deux.
Le cas qui pose problème
Le thème parent déclare un preset de couleur nommé « Bleu principal », avec le slug bleu-principal :
{
"settings": {
"color": {
"palette": [
{ "name": "Bleu principal", "slug": "bleu-principal", "color": "#1d4ed8" }
]
}
}
}Le thème enfant tente de redéfinir la même couleur, avec une teinte différente, mais un nom légèrement différent :
{
"settings": {
"color": {
"palette": [
{ "name": "Bleu de marque", "slug": "bleu-principal", "color": "#0f172a" }
]
}
}
}Résultat observé : la couleur appliquée dans l’éditeur correspond bien à celle du thème enfant, mais le nom affiché dans le sélecteur de couleurs reste parfois celui du thème parent, selon la version du cœur utilisée.
Ce que révèle le slug
Le mécanisme de fusion entre thème parent et thème enfant repose sur le slug de chaque entrée, jamais sur son nom affiché. Deux presets partageant le même slug sont considérés comme une seule et même entrée, et non comme deux entrées distinctes qui coexisteraient dans la palette finale.
- Le slug est la clé de fusion, le nom n’est qu’une étiquette d’affichage.
- Une palette du thème enfant portant un slug déjà présent chez le parent redéfinit cette entrée, elle ne s’y ajoute pas.
- Une incohérence entre nom et couleur affichés trahit presque toujours un slug dupliqué mal maîtrisé.
Pourquoi le résultat semble parfois incohérent
La fusion entre thème parent et enfant s’opère niveau par niveau dans la structure JSON, pas de façon globale sur l’ensemble du fichier. Selon la profondeur à laquelle une clé est redéfinie, le comportement de fusion peut donner l’impression que certaines parties du thème parent « survivent » alors que d’autres sont bien remplacées — ce qui explique la confusion fréquente autour du nom affiché dans l’exemple précédent.
Face à un résultat qui semble incohérent, mieux vaut toujours vérifier le slug exact de chaque entrée avant de suspecter un défaut du mécanisme de fusion lui-même.
Vérifier concrètement le résultat final
Le panneau des styles globaux de l’éditeur de site, dans son mode d’affichage détaillé, permet d’inspecter la palette réellement appliquée après fusion. Une comparaison manuelle entre les deux fichiers theme.json, slug par slug, reste toutefois le moyen le plus fiable de repérer une collision avant qu’elle ne surprenne quelqu’un en production.
La bonne pratique à adopter
Pour éviter toute ambiguïté, mieux vaut aligner systématiquement le nom affiché sur la couleur réellement appliquée après fusion, plutôt que de conserver deux libellés différents pour un même slug. Si l’intention est réellement de proposer deux couleurs distinctes, il faut leur attribuer des slugs différents, sans exception.
En résumé
Un preset de couleur qui semble mal s’appliquer dans un thème enfant cache le plus souvent une collision de slug avec le thème parent, la fusion se faisant sur cet identifiant technique et non sur le nom affiché. Vérifier systématiquement les slugs avant de conclure à un bug du mécanisme de fusion évite bien des pertes de temps.
