Le dossier /styles d’un thème bloc : des variations en JSON

Un client dans le secteur de l’événementiel nous demandait de pouvoir changer l’ambiance visuelle complète de son site plusieurs fois par an, au gré de ses événements, sans jamais toucher au contenu ni à la structure des pages. La réponse tenait dans une fonctionnalité du thème bloc trop souvent sous-exploitée : le dossier /styles, qui permet de déclarer plusieurs variations de theme.json sans dupliquer l’intégralité du fichier à chaque fois.

Cette fonctionnalité existe depuis les débuts des thèmes blocs modernes et s’est enrichie au fil des versions de WordPress, mais reste mal comprise par beaucoup d’auteurs de thème qui persistent à dupliquer un theme.json complet pour chaque variante, avec tous les inconvénients de maintenance que cela implique.

Structure minimale du dossier

À la racine du thème, à côté du theme.json principal, un dossier styles contient un fichier JSON par variation proposée. Chaque fichier ne définit que ce qui diffère du theme.json principal, considéré comme la base commune :

mon-theme/
├── theme.json
├── style.css
└── styles/
    ├── festival-ete.json
    ├── festival-hiver.json
    └── conference-pro.json

Un fichier de variation reprend la même structure que theme.json, mais se limite généralement aux clés settings et styles, avec un title obligatoire qui sert de libellé dans le panneau Styles de l’éditeur de site :

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "title": "Festival d'été",
  "settings": {
    "color": {
      "palette": [
        { "slug": "primaire", "color": "#f59e0b", "name": "Primaire" },
        { "slug": "secondaire", "color": "#0891b2", "name": "Secondaire" }
      ]
    }
  }
}

Ce qui est hérité et ce qui ne l’est pas

Une variation hérite par défaut de l’intégralité du theme.json principal : templates, template parts, configuration générale. Seules les clés explicitement redéfinies dans le fichier de variation viennent surcharger celles du fichier principal, à la manière d’une fusion de tableaux plutôt que d’un remplacement complet.

• Redéfinir settings.color.palette remplace entièrement la palette de couleurs pour cette variation, sans conserver les entrées du fichier principal.
• Redéfinir seulement une police dans settings.typography.fontFamilies conserve les autres réglages typographiques hérités du fichier principal.
• Les templateParts et customTemplates déclarés dans le theme.json principal restent valables pour toutes les variations, elles ne sont jamais redéfinies au niveau du dossier /styles.

Le comportement dans le panneau Styles

Dès qu’un fichier JSON valide est présent dans /styles, il apparaît automatiquement comme vignette sélectionnable dans le panneau Styles de l’éditeur de site, sans code PHP supplémentaire à écrire. Le nom affiché correspond à la clé title du fichier, pas au nom du fichier lui-même, ce qui laisse une liberté totale sur le nommage technique des fichiers.

Sur le projet événementiel cité plus haut, le client change lui-même de variation selon la saison, directement depuis l’éditeur de site, sans intervention technique de notre part : un gain d’autonomie qui a justifié à lui seul l’investissement initial dans cette structuration.

Variations imbriquées : le sous-dossier /styles/blocks

Une évolution moins connue permet également de cibler les réglages d’un bloc précis à l’intérieur d’une variation, via un sous-dossier structuré, mais cette granularité reste rarement nécessaire pour un besoin de changement d’identité visuelle globale comme celui décrit ici. Nous la réservons aux cas où une variation doit vraiment ajuster le comportement d’un bloc spécifique, plutôt que l’ensemble de la palette et de la typographie.

En résumé

Le dossier /styles est la manière recommandée de proposer plusieurs identités visuelles au sein d’un même thème bloc, sans dupliquer theme.json ni écrire de code PHP dédié. Cette structuration réduit la maintenance à long terme : ajouter une nouvelle variation revient à créer un simple fichier JSON, jamais à dupliquer et resynchroniser un fichier de configuration complet.