Variations de style d'un thème de blocs WordPress

Les variations de style sont des apparences de rechange qu’un thème de blocs offre à ses utilisateurs, comme un jeu de couleurs sombre ou des polices plus chaleureuses. Cet article s’adresse aux développeurs de thèmes et aux personnes qui entretiennent les sites bâtis sur ces thèmes. Chaque variation est un petit fichier JSON dans le dossier styles/ du thème. Il remplace une partie de theme.json, le fichier où un thème de blocs déclare ses couleurs, ses polices et ses espacements. Quand quelqu’un choisit une variation et enregistre, WordPress la copie dans la base de données du site, et les changements faits ensuite au fichier n’atteignent jamais ce site d’eux-mêmes. Gardez dans chaque variation les mêmes identifiants (slugs) de couleurs et de polices que le thème de base, ces noms courts par lesquels votre contenu désigne un préréglage. Prévoyez aussi comment vous livrerez les changements aux sites qui l’utilisent déjà.

Ce que vous allez accomplir

Ajouter à un thème de blocs une variation nommée Night, avec sa propre palette et sa propre typographie.
Garder le contenu lisible dans chaque variation en réutilisant les identifiants de préréglages du thème.
Vérifier que WordPress lit le fichier, puis l’appliquer dans l’Éditeur de site.
Trouver la copie enregistrée en base de données et confirmer les valeurs qu’un site utilise vraiment.
Livrer une variation mise à jour aux sites qui avaient choisi l’ancienne version.

Prérequis

WordPress 6.6 ou plus récent, la première version qui prend en charge theme.json version 3, et un thème de blocs que vous pouvez modifier. Utilisez un thème enfant si le thème vient de quelqu’un d’autre.
Un theme.json de base qui déclare "version": 3. Les exemples supposent une palette avec les identifiants base, contrast et accent, et des familles de polices avec les identifiants body et heading.
Un compte Administrateur pour l’Éditeur de site, qui se trouve sous Apparence > Éditeur.
Un accès SSH avec WP-CLI et jq, un petit outil JSON en ligne de commande. Installez-le avec sudo apt install jq sur Debian ou Ubuntu.

Comment ça fonctionne

WordPress construit le design d’un site par couches. Le theme.json du thème sert de base. Par-dessus se trouvent les styles enregistrés du site, une publication de type wp_global_styles qui contient tout ce qu’une personne a changé dans l’Éditeur de site. La valeur de la couche supérieure l’emporte.

Une variation se tient à l’écart de ces deux couches : c’est un ensemble de changements en attente d’être appliqués. Quand quelqu’un ouvre Styles, choisit une variation et enregistre, WordPress copie ses réglages et ses styles dans la publication des styles enregistrés. Dès lors, le site lit la copie, pas le fichier du dossier styles/.

Schéma en deux zones : à gauche, les fichiers du thème, avec theme.json et la variation styles/night.json ; à droite, la base de données du site, avec les styles enregistrés dans wp_global_styles ; choisir et enregistrer copie la variation d'un côté à l'autre, tandis qu'une mise à jour ultérieure de night.json est bloquée et n'atteint jamais un site qui l'avait déjà enregistrée

Le schéma montre la conséquence. Mettez à jour le thème avec une meilleure palette Night : les nouveaux sites l’obtiennent la première fois qu’ils choisissent Night. Un site qui a choisi Night le mois dernier garde les couleurs du mois dernier. Le manuel des thèmes WordPress documente le format du fichier sur sa page consacrée aux variations de style.

Deux règles plus modestes comptent quand vous écrivez le fichier. WordPress lit chaque fichier .json sous styles/, sous-dossiers compris, et les présente dans l’ordre de leurs chemins. Si une variation n’a pas de title, WordPress affiche le nom du fichier à la place. Un thème enfant peut remplacer une variation du thème parent en livrant un fichier du même nom dans son propre dossier styles/.

Étapes

Listez les variations que le thème contient déjà. Depuis le répertoire de WordPress sur le serveur :
```
wp eval 'foreach ( WP_Theme_JSON_Resolver::get_style_variations() as $v ) { echo $v["title"], PHP_EOL; }'
```
Exemple de sortie, tirée de Twenty Twenty-Five et réduite à ses premières lignes :
```
Evening
Noon
Dusk
Afternoon
```
La liste comprend aussi les fichiers de couleurs seules et de polices seules (étape 8). Un thème comme Twenty Twenty-Five affiche donc plus de vingt lignes et répète des noms comme Evening. Si rien ne s’affiche, le thème n’a pas encore de variation, ou pas de dossier styles/. Les deux conviennent, puisque vous créez le dossier à l’étape 3.
Lisez les identifiants de couleurs et de polices du thème de base. Un identifiant (slug) est le nom court qui sert à WordPress pour construire la variable CSS d’une couleur, comme --wp--preset--color--accent. Le contenu enregistré avec une couleur garde cet identifiant, pas la valeur hexadécimale. Affichez les identifiants :
```
jq -r '.settings.color.palette[].slug' "$(wp theme path "$(wp option get stylesheet)" --dir)/theme.json"
```
Exemple de sortie :
```
base
contrast
accent
```
Puis les identifiants des familles de polices :
```
jq -r '.settings.typography.fontFamilies[].slug' "$(wp theme path "$(wp option get stylesheet)" --dir)/theme.json"
```
Exemple de sortie :
```
body
heading
```
Notez-les. Votre variation doit utiliser les mêmes, sinon les blocs colorés avec un identifiant absent perdent leur couleur dans cette variation.
Créez le fichier de variation. Dans le dossier du thème, créez styles/night.json. Listez toutes les couleurs de la palette, car une palette dans une variation remplace celle du thème au lieu de s’y fusionner. Night change aussi la police du texte, et c’est ce qui la fait présenter par WordPress comme un style complet :
```
{
    "$schema": "https://schemas.wp.org/trunk/theme.json",
    "version": 3,
    "title": "Night",
    "settings": {
        "color": {
            "palette": [
                { "slug": "base", "color": "#10161f", "name": "Base" },
                { "slug": "contrast", "color": "#e8edf3", "name": "Contrast" },
                { "slug": "accent", "color": "#f2b544", "name": "Accent" }
            ]
        }
    },
    "styles": {
        "color": {
            "background": "var:preset|color|base",
            "text": "var:preset|color|contrast"
        },
        "typography": {
            "fontFamily": "var:preset|font-family|heading"
        },
        "elements": {
            "link": {
                "color": { "text": "var:preset|color|accent" }
            }
        }
    }
}
```
La forme var:preset|color|base est la façon dont theme.json désigne un préréglage. WordPress la transforme en variable CSS correspondante. Omettez tout ce qui doit rester comme dans le thème de base.

La ligne typography fait utiliser au texte courant de l’apparence Night la police des titres. Gardez dans le fichier au moins une valeur autre que des couleurs. Un fichier qui ne règle que les couleurs est proposé comme palette sous Couleurs (Colors), pas comme style complet (étape 8). Pour ajouter une police que le thème n’a pas, listez-la sous settings.typography.fontFamilies dans la variation, avec les familles existantes du thème, car cette liste remplace elle aussi celle du thème. Donnez à chaque fichier de police un src comme file:./assets/fonts/inter.woff2. WordPress lit ce chemin à partir du dossier racine du thème, pas de styles/.
Vérifiez le JSON et que WordPress le prend en compte. D’abord la syntaxe, depuis le dossier du thème :
```
jq empty styles/night.json && echo "valid JSON"
```
Exemple de sortie :
```
valid JSON
```
Une erreur d’analyse avec un numéro de ligne signale une virgule ou un crochet manquant. Corrigez-la à cet endroit, car WordPress ignore un fichier qu’il ne peut pas lire. Relancez ensuite la commande de l’étape 1. Night doit maintenant figurer dans la liste. Sinon, vérifiez que le fichier se trouve dans le dossier styles/ du thème actif lui-même et qu’il se termine par .json.
Appliquez-la dans l’Éditeur de site. Allez dans Apparence > Éditeur > Styles. Les variations s’affichent sous forme de cartes d’aperçu ; dans le panneau Styles de l’éditeur, la même liste se trouve sous Parcourir les styles (Browse styles). Choisissez Night, parcourez quelques modèles, puis cliquez sur Enregistrer. Rien ne change sur le site en ligne avant l’enregistrement.

Confirmez ce que le site a enregistré. Trouvez la publication des styles enregistrés du thème actif :

wp post list --post_type=wp_global_styles --fields=ID,post_name,post_modified

Exemple de sortie :

+-----+------------------------------------+---------------------+
| ID  | post_name                          | post_modified       |
+-----+------------------------------------+---------------------+
| 512 | wp-global-styles-harbour-theme     | 2026-10-29 10:16:44 |
+-----+------------------------------------+---------------------+

Le nom se termine par le nom du dossier du thème. Relisez les styles copiés :

wp post get 512 --field=post_content | jq '.styles.color'

Exemple de sortie :

{
  "background": "var:preset|color|base",
  "text": "var:preset|color|contrast"
}

C’est la copie de votre fichier. Désormais, le site lit ces valeurs, pas styles/night.json.

Livrez une variation modifiée aux sites existants. Disons que vous changez plus tard l’accent pour #e9a23b et que vous publiez la mise à jour du thème. Les sites qui ont enregistré Night gardent l’ancien accent. Sur chacun, ouvrez Apparence > Éditeur > Styles, choisissez une autre variation, puis de nouveau Night, et enregistrez. Cela recopie le fichier actuel. Lisez ensuite l’accent dans la copie enregistrée :
```
wp post get 512 --field=post_content | jq -r '.settings.color.palette | .. | objects | select(.slug == "accent") | .color'
```
Exemple de sortie :
```
#e9a23b
```
La copie enregistrée peut regrouper la palette sous une clé theme au lieu d’une simple liste ; ce filtre cherche donc l’identifiant au lieu de lire un chemin fixe. S’il affiche encore #f2b544, l’enregistrement n’a pas eu lieu ou la mise à jour du thème n’a pas atteint ce serveur.

Choisir de nouveau une variation peut écraser les changements faits dans Styles depuis le dernier choix. Si le site a été personnalisé, examinez d’abord ses styles enregistrés. Sous Styles, Révisions (Revisions) montre les enregistrements précédents, où vous pouvez revenir si le résultat ne convient pas.
Ajoutez des palettes ou des polices seules, au besoin. Depuis WordPress 6.6, un fichier qui ne règle que les couleurs est proposé comme palette plutôt que comme style complet. Un fichier qui ne règle que la typographie est proposé comme jeu de polices. On peut alors combiner une palette avec un autre jeu de polices. Twenty Twenty-Five, par exemple, range ces fichiers dans styles/colors/ et styles/typography/. Ils suivent la même règle de copie à l’enregistrement.

Valider que ça fonctionne

Vérifiez trois choses, dans cet ordre :

wp eval 'foreach ( WP_Theme_JSON_Resolver::get_style_variations() as $v ) { echo $v["title"], PHP_EOL; }' | grep -x Night
curl -s https://www.example.com/ | grep -o -- '--wp--preset--color--accent: #[0-9a-fA-F]*'
wp post get 512 --field=post_content | jq -r '.styles.color.background'

Exemple de sortie :

Night
--wp--preset--color--accent: #f2b544
var:preset|color|base

La première ligne prouve que WordPress lit le fichier. La deuxième prouve que la page en ligne publie la couleur d’accent de la variation dans ses variables CSS. La troisième prouve que les styles enregistrés du site visent le bon préréglage. C’est terminé quand les trois correspondent au fichier, que le site s’affiche correctement dans un fureteur après avoir vidé tout cache de pages, et que les liens utilisent la couleur d’accent de Night.

Dépannage

La variation n’apparaît pas dans Styles. WordPress n’a pas pu lire le fichier ou ne l’a pas trouvé. Faites la vérification jq empty, confirmez que le fichier est sous le dossier styles/ du thème actif et qu’il n’a pas de clé blockTypes. Un fichier avec blockTypes est traité comme un style pour certains blocs, pas pour tout le site. Si Night n’apparaît que sous Couleurs, le fichier ne règle que des couleurs ; ajoutez la valeur typography de l’étape 3.
Certains blocs ont perdu leur couleur dans la nouvelle variation. Leur identifiant de couleur n’existe pas dans la palette de la variation. Comparez la liste de l’étape 2 avec votre fichier et ajoutez l’identifiant manquant.
Une mise à jour du thème n’a pas changé l’apparence du site. C’est la règle de copie à l’enregistrement. Choisissez de nouveau la variation comme à l’étape 7.
La variation affiche le nom du fichier au lieu d’un vrai nom. La clé title manque ou est mal orthographiée. Ajoutez "title": "Night" ; c’est aussi ce nom que voient les traducteurs.
Un thème enfant présente la même apparence deux fois. Le parent et l’enfant la livrent tous deux, sous des noms de fichiers différents. Donnez au fichier de l’enfant le même nom que le fichier du parent qu’il remplace.

Quand cette approche ne convient pas

Une variation ne change que des réglages et des styles. Elle ne peut pas ajouter de modèles, de parties de modèle ni de compositions ; une mise en page différente demande donc un thème enfant ou de nouveaux modèles. Si plusieurs équipes modifient le même design de base, réglez d’abord qui est responsable de theme.json ; notre guide sur la gouvernance de theme.json pour les équipes réparties traite de cette question. Quand les styles enregistrés et les valeurs du thème semblent se contredire d’autres façons, les pièges des styles globaux de WordPress passe en revue les règles de priorité.

Pour un seul site avec une seule apparence, une variation ajoute un fichier que personne ne choisit. Placez le design directement dans theme.json, comme le décrit notre guide sur la structure de fichiers d’un thème de blocs.

Un WordPress qui rapporte vraiment mérite un opérateur — Stack Harbor opère cette pile sous WordPress Entreprise ; réservez une consultation d’infrastructure.