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

> Proposer cinq identités visuelles à un client sans dupliquer theme.json cinq fois : la structure du dossier styles répond exactement à ce besoin.

- Auteur : Clément Hadrot
- Publié le : 2024-10-14
- Mis à jour le : 2024-10-14
- Catégorie : Thèmes
- URL : https://wpmoderne.dev.wordpress-developpement.fr/themes/dossier-styles-theme-bloc-variations-json/

## L’essentiel

- Chaque fichier JSON du dossier styles est une variation autonome
- Les variations héritent du theme.json principal par défaut
- Un simple nom de fichier suffit à les faire apparaître dans l'éditeur

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

> L'essentiel à retenir : Chaque fichier JSON du dossier styles est une variation autonome ; Les variations héritent du theme.json principal par défaut ; Un simple nom de fichier suffit à les faire apparaître dans l'éditeur

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.