Thèmes de blocs WP

Quand l'utiliser

Utilisez cette skill pour les travaux sur les thèmes de blocs tels que :

• éditer theme.json (presets, settings, styles, styles par bloc)
• ajouter ou modifier des templates (templates/*.html) et des parties de template (parts/*.html)
• ajouter des patterns (patterns/*.php) et contrôler ce qui apparaît dans l'inserter
• ajouter des variations de style (styles/*.json)
• déboguer « les styles ne s'appliquent pas » / « l'éditeur ne reflète pas theme.json »

Entrées requises

• Racine du repo et quel thème est ciblé (répertoire du thème s'il en existe plusieurs).
• Plage de versions WordPress cible (la version et les fonctionnalités de theme.json varient selon la version core).
• Où le problème se manifeste : Site Editor, post editor, frontend, ou partout.

Procédure

0) Triage et localisation des racines des thèmes de blocs

1. Exécutez le triage :
   • node skills/wp-project-triage/scripts/detect_wp_project.mjs
2. Détectez les racines des thèmes et les dossiers clés :
   • node skills/wp-block-themes/scripts/detect_block_themes.mjs

S'il existe plusieurs thèmes, choisissez-en un et limitez toutes les modifications à la racine de ce thème.

1) Créer un nouveau thème de blocs (si nécessaire)

Si vous créez un nouveau thème de blocs à partir de zéro (ou convertissez un thème classique) :

• Préférez partir d'un scaffold connu et fonctionnant (ou exporter à partir d'un environnement WP) plutôt que de deviner la structure des fichiers.
• Soyez explicite sur la version WordPress minimale supportée, car les versions de schéma theme.json diffèrent.

Lisez :

• references/creating-new-block-theme.md

Après la création de la racine du thème, réexécutez detect_block_themes et continuez ci-dessous.

2) Confirmer le type de thème et les attentes de remplacement

• Indicateurs de thème de blocs :
  • theme.json présent
  • templates/ et/ou parts/ présents
• Souvenez-vous de la hiérarchie des styles :
  • defaults core → theme.json → child theme → user customizations
  • les user customizations peuvent faire en sorte que les modifications de theme.json semblent « ignorées »

Lisez :

• references/debugging.md (hiérarchie des styles + vérifications rapides)

3) Modifier theme.json en toute sécurité

Décidez si vous modifiez :

• settings (ce que l'UI autorise) : presets, échelle typographique, couleurs, layout, spacing
• styles (comment cela apparaît par défaut) : règles de type CSS pour les éléments/blocs

Lisez :

• references/theme-json.md

4) Templates et parties de template

• Les templates se trouvent sous templates/ et sont en HTML.
• Les parties de template se trouvent sous parts/ et ne doivent pas être imbriquées dans des sous-répertoires.

Lisez :

• references/templates-and-parts.md

5) Patterns

Préférez les patterns du système de fichiers sous patterns/ quand vous voulez des patterns owned by theme.

Lisez :

• references/patterns.md

6) Variations de style

Les variations de style sont des fichiers JSON sous styles/. Remarque : une fois qu'un utilisateur choisit une variation de style, cette sélection est stockée dans la DB, donc modifier le fichier peut ne pas « mettre à jour ce que l'utilisateur voit » automatiquement.

Lisez :

• references/style-variations.md

Vérification

• Site Editor reflète les modifications où attendues (UI Styles, templates, patterns).
• Frontend s'affiche avec les styles attendus.
• Si les styles ne changent pas, confirmez si les user customizations remplacent les defaults du thème.
• Exécutez les scripts build/lint du repo s'il y a des assets impliqués (fonts, custom JS/CSS build).

Modes d'échec / débogage

Commencez par :

• references/debugging.md

Problèmes courants :

• mauvaise racine de thème (édition d'un thème inactif)
• les user customizations remplacent vos defaults
• forme/typos invalides dans theme.json empêchent l'application
• templates/parts dans les mauvais dossiers (ou parts imbriquées)

Escalade

Si le comportement upstream n'est pas clair, consultez la documentation canonique :

• Theme Handbook et Block Editor Handbook pour theme.json, templates, patterns, et style variations.