Dégradés theme.json → SCSS et utilitaires --gradient

[cedric07]

Contexte et objectif

Le thème exposait déjà la palette de couleurs de theme.json vers SCSS ($settings-palette, variables $settings-color-*) et des classes utilitaires qui copient la couleur du parent dans --color / --background-color (src/scss/04-utilities/_palette.scss).

Les dégradés déclarés dans settings.color.gradients (classes WordPress du type has-{slug}-gradient-background) n’étaient pas synchronisés avec cette chaîne. Les enfants ne pouvaient pas réutiliser la même valeur de fond dégradé que le parent via une variable CSS, contrairement aux aplats.

Cette PR aligne les dégradés sur le même modèle que la palette : génération webpack → _theme-json.scss → boucle @each dans _palette.scss.

Fichiers modifiés

Fichier	Rôle
config/webpack-theme-json-plugin.js	Nouvelle tâche settings-color-gradients dans generateScssVariables()
src/scss/04-utilities/_palette.scss	Génération des classes .has-{slug}-gradient-background avec --gradient
src/scss/01-abstract/_theme-json.scss	Régénéré au build : map $settings-gradients (vide tant qu’aucun dégradé n’est déclaré)

Le dépôt modèle garde gradients: [] dans src/theme-json/colors.json : aucun dégradé par défaut, pas de changement visuel tant qu’un projet n’en ajoute pas.

Pipeline de génération (webpack)

Pour chaque entrée de settings.color.gradients dans le theme.json fusionné :

{
  "name": "Mon dégradé",
  "slug": "brand-sunset",
  "gradient": "linear-gradient(135deg, #ffe600 0%, #111 100%)"
}

Le plugin produit :

1. Une variable SCSS par slug : $settings-gradient-{slug}: {gradient};
2. Une map : $settings-gradients: ( brand-sunset: $settings-gradient-brand-sunset, … );

Convention identique à la palette (settings-color-palette → $settings-color-* + $settings-palette).

_theme-json.scss reste généré automatiquement (ne pas éditer à la main).

Utilitaires CSS (_palette.scss)

Pour chaque couple (slug, valeur) dans $settings-gradients :

.has-{slug}-gradient-background {
  --gradient: #{valeur};
}

Le nom de classe suit les classes de fond dégradé du bloc editor WordPress (has-*-gradient-background), ce qui permet de cibler le même nœud que Gutenberg sans dupliquer la définition du dégradé.

Parallèle avec les couleurs unies

Type	Classe parent (ex.)	Variable exposée
Texte	.has-grey-900-color	--color
Fond uni	.has-yellow-500-background-color	--background-color
Fond dégradé	.has-brand-sunset-gradient-background	--gradient

Exemple d’usage

HTML (bloc ou template avec classe WP) :

<div class="has-brand-sunset-gradient-background">
  <span class="hero__badge">Texte ou forme qui reprend le dégradé</span>
</div>

SCSS :

.hero__badge {
  background-image: var(--gradient);
  // ou background: var(--gradient);
}

Même principe que color: var(--background-color) pour un enfant sur fond uni.

Ajouter des dégradés sur un projet

1. Déclarer les entrées dans src/theme-json/colors.json (ou le fragment JSON du projet) sous settings.color.gradients, avec name, slug et gradient (chaîne CSS valide).
2. Lancer le build front (webpack) pour régénérer theme.json racine et src/scss/01-abstract/_theme-json.scss.
3. Recompiler le CSS : les classes utilitaires --gradient sont émises automatiquement.

Exemple minimal dans colors.json :

"gradients": [
  {
    "name": "Sunset",
    "slug": "brand-sunset",
    "gradient": "linear-gradient(135deg, #ffe600 0%, #111 100%)"
  }
]

Les slugs doivent rester stables : ils servent aux classes WP et aux noms de variables SCSS.

Points d’attention

• Source unique : la valeur du dégradé vit dans theme.json ; SCSS et éditeur restent alignés après build.
• Map vide : avec gradients: [], $settings-gradients est vide et la boucle @each ne génère aucune classe — comportement sans risque pour les thèmes existants.
• Pas un remplacement du fond WP : WordPress continue d’appliquer le background-image via ses propres styles de bloc ; --gradient est un pont pour les descendants en CSS custom, pas une obligation de l’utiliser sur le parent lui-même.
• Accessibilité : comme pour tout dégradé en fond, vérifier contraste texte / icônes sur toute la zone du dégradé ; la variable ne change pas les règles de contraste.

Synthèse

Extension du pipeline theme.json → SCSS aux dégradés, plus utilitaires --gradient calqués sur --background-color. Le boilerplate reste sans dégradé prédéfini ; les projets en ajoutent dans colors.json et profitent des mêmes classes que l’éditeur pour faire hériter les enfants du fond dégradé du parent.

---

Note

Low Risk
Build-time SCSS/CSS utility generation only; empty gradient maps produce no extra classes for existing themes.

Overview
Extends the theme.json → SCSS webpack pipeline so settings.color.gradients is emitted as $settings-gradient-{slug} variables and a $settings-gradients map (empty () when no gradients are defined), mirroring the existing color palette task.

_palette.scss now generates WordPress-aligned .has-{slug}-gradient-background utilities that set --gradient, so child elements can reuse a parent’s gradient via var(--gradient) the same way solid backgrounds use --background-color. No default gradients in the boilerplate—behavior is unchanged until a project adds entries and rebuilds.

^{Reviewed by Cursor Bugbot for commit cd695eb. Bugbot is set up for automated code reviews on this repo. Configure here.}