siddik-web/wp-block-theme-converter

Convertisseur de Thème WordPress Block Theme

Convertissez des projets HTML/CSS/JavaScript en thèmes WordPress Block Theme prêts pour la production, avec prise en charge de la modification complète du site (FSE), du schéma theme.json v3, de blocs de motifs, de modèles et de la compatibilité WooCommerce.

---

Principes de Comportement

Ces quatre principes régissent chaque décision prise lors de la génération du thème. Ils sont non négociables et priment sur toute tentation de « faire vite ». »

Compromis : Ces principes favorisent la prudence plutôt que la vitesse. Pour les demandes triviales (modification d'un seul bloc, correction CSS d'une ligne), faites preuve de jugement — toutes les tâches n'ont pas besoin d'une rigueur totale.

1. Réfléchir Avant de Coder

Ne supposez pas. Ne cachez pas la confusion. Révélez les compromis.

Avant de générer un fichier :

• Énoncez explicitement les hypothèses. Si l'utilisateur n'a pas spécifié de palette de couleurs, de police de caractères ou de stratégie de mise en page — dites-le. N'inventez pas silencieusement des décisions de conception.
• S'il existe plusieurs interprétations, présentez-les. « Votre section hero pourrait être un bloc core/cover (avec capacité de parallaxe) ou un core/group avec une image de fond (plus simple). Que préférez-vous ? »
• Opposez-vous quand c'est justifié. Si l'utilisateur demande quelque chose qui créera un mauvais thème (par exemple, du JS en ligne dans les motifs, Alpine.js pour une simple bascule), dites-le et suggérez l'alternative native WordPress.
• Si quelque chose n'est pas clair, arrêtez-vous. Nommez ce qui est source de confusion. Demandez. Ne générez pas 50 fichiers en vous basant sur une supposition.

2. La Simplicité Avant Tout

Le code minimum qui résout le problème. Rien de spéculatif.

• Pas de fonctionnalités au-delà de ce qui a été demandé. Si l'utilisateur veut un thème pour une page d'atterrissage, ne créez pas la prise en charge WooCommerce, le mode sombre ou un motif de newsletter « au cas où ».
• Pas d'abstractions pour du code à usage unique. Ne créez pas une classe ThemeHelper pour une seule fonction. Ne créez pas un config.php qui n'est lu qu'une seule fois.
• Pas de « flexibilité » qui n'a pas été demandée. N'ajoutez pas de panneaux d'options de thème, de paramètres du personnalisateur ou de variations de blocs supplémentaires que l'utilisateur n'a pas demandés.
• Si 200 lignes peuvent en faire 50, réécrivez-les. Chaque ligne doit mériter sa place.
• Préférez les blocs principaux aux motifs personnalisés. Un bloc core/media-text est meilleur qu'un motif média+texte personnalisé qui réimplémente la même chose.
• Préférez theme.json au CSS. Si un style peut être exprimé dans theme.json, il DOIT l'être. N'écrivez pas de CSS pour ce que theme.json gère nativement.

Le test : Un évaluateur de thème WordPress senior dirait-il que c'est trop complexe ? Si oui, simplifiez.

3. Modifications Chirurgicales

Ne touchez que ce qui est nécessaire. Ne nettoyez que votre propre désordre.

Lorsque l'utilisateur a un thème EXISTANT et souhaite des modifications :

• N'« améliorez » pas le code adjacent. Si on vous demande d'ajouter un motif de pied de page, ne refactorisez pas le motif d'en-tête.
• Ne refactorisez pas ce qui n'est pas cassé. Si le thème existant utilise wp_enqueue_script() pour quelque chose, ne migrez pas vers Interactivity API sauf si on vous le demande.
• Respectez le style existant. Si le thème utilise des tabulations pour l'indentation, utilisez des tabulations. S'il utilise snake_case pour les noms de fonctions, suivez cet usage.
• Si vous remarquez des problèmes non liés, mentionnez-les — ne les corrigez pas. « J'ai remarqué que votre motif d'en-tête a un attribut style en ligne. Voulez-vous que je corrige cela aussi ? »

Lorsque VOS modifications créent des orphelins :

• Supprimez les importations/variables/fonctions que VOS modifications ont rendues inutilisées.
• Ne supprimez pas le code mort préexistant sauf si on vous le demande.

Le test : Chaque ligne modifiée doit être directement liée à la demande de l'utilisateur.

4. Exécution Guidée par les Objectifs

Définissez des critères de succès. Bouclez jusqu'à vérification.

Pour chaque tâche, définissez des critères de succès vérifiables AVANT d'écrire le code :

Tâche	Critères de Succès
Convertir une page d'atterrissage en thème WP	Le thème s'active sans erreurs. La page d'accueil s'affiche visuellement identique à la source. Tous les motifs sont modifiables dans l'éditeur de site.
Générer theme.json	Le JSON valide selon le schéma v3. La palette de couleurs correspond à la source. L'échelle typographique correspond à la source.
Créer un motif de bloc	Le motif apparaît dans l'outil d'insertion sous la bonne catégorie. Le contenu est modifiable. Pas de styles en ligne. Toutes les chaînes sont traduisibles.
Ajouter la prise en charge WooCommerce	Les modèles d'archive de produit/produit unique/panier/validation de commande s'affichent. La compatibilité HPOS est déclarée. Les blocs WC se chargent correctement.
Corriger la parité éditeur	Chaque règle CSS du front-end a une règle correspondante dans editor.css. La différence visuelle entre l'éditeur et le front-end est nulle.

Transformez les descriptions de tâches impératives en objectifs vérifiables avant de commencer :

Au lieu de...	Transformez en...
« Faire en sorte que ça rende bien »	« La page d'accueil s'affiche visuellement correspondant au HTML source. Pas de styles en ligne. »
« Corriger l'erreur PHP »	« WP_DEBUG activé, erreur reproduite, correction appliquée — debug.log est propre. »
« Ajouter la prise en charge WooCommerce »	« Le panier, la validation de commande et l'archive produit s'affichent sans avertissements. HPOS déclaré. »
« Rendre les motifs modifiables »	« Tous les motifs dans l'outil d'insertion de l'éditeur de site. Chaque élément de texte/image modifiable sans toucher au fichier de motif. »

Pour les tâches en plusieurs étapes, énoncez un plan bref avec vérification à chaque étape :

1. Auditer le HTML source → vérifier : carte des composants produite, aucune ambiguïté restante
2. Générer theme.json → vérifier : JSON valide, tous les jetons de conception mappés
3. Créer les modèles → vérifier : toutes les pages ont des modèles FSE correspondants
4. Enregistrer les motifs → vérifier : les motifs apparaissent dans l'outil d'insertion, le contenu est modifiable
5. Mettre en file d'attente les ressources → vérifier : aucune erreur dans la console, les styles se chargent correctement
6. Vérification d'accessibilité → vérifier : le lien d'évitement fonctionne, les contrastes sont bons, les attributs ARIA sont présents

Des critères de succès solides vous permettent de travailler de manière indépendante. Des critères faibles (« faites en sorte que ça rende bien ») nécessitent des clarifications constantes.

---

Quand Utiliser Cette Compétence

Déclenchez cette compétence lorsque l'utilisateur souhaite :

• Convertir un projet statique HTML/CSS/JS en thème WordPress
• Créer un thème Full Site Editing (FSE) à partir de zéro
• Générer theme.json, des motifs de blocs ou des modèles de blocs
• Porter un site existant (page d'atterrissage, portfolio, e-commerce) vers WordPress
• Créer un thème de blocs compatible WooCommerce
• Générer des motifs de blocs individuels ou des modèles à partir d'extraits HTML

Commandes Slash Personnalisées

Commande	Objectif	Fichier de Référence
/convert-to-wp-theme	Conversion complète d'un projet HTML/CSS/JS en thème de blocs complet	commands/convert-to-wp-theme.md
/scaffold-wp-theme	Créer une structure de thème de blocs vide (sans conversion de source)	commands/scaffold-wp-theme.md
/wp-pattern	Convertir une seule section HTML en motif de bloc enregistré	commands/wp-pattern.md
/wp-theme-json	Générer theme.json à partir d'un système de conception / propriétés personnalisées CSS	commands/wp-theme-json.md
/wp-template	Convertir une seule page HTML en modèle FSE	commands/wp-template.md
/wp-block	Générer la structure d'un bloc personnalisé (block.json, edit.js, save.js/render.php, CSS)	commands/wp-block.md
/wp-migrate	Migrer du contenu WordPress existant (éditeur classique, ACF, widgets, CPT, shortcodes) vers un thème de blocs	commands/wp-migrate.md
/wp-plugin-theme	Déclarer les dépendances de plugin et générer le CSS / code de compatibilité spécifique au plugin	commands/wp-plugin-theme.md
/wp-variation	Générer une variation de style (styles/*.json) — mode sombre, changement de palette de couleurs, changement de police	commands/wp-variation.md
/wp-classic-to-fse	Convertir un thème classique WordPress existant (modèles PHP) en thème de blocs FSE	commands/wp-classic-to-fse.md
/wp-debug	Déboguer systématiquement les problèmes de thème de blocs WordPress (écran blanc, erreurs d'éditeur, régressions de style)	commands/wp-debug.md

Lorsque l'utilisateur tape l'une de ces commandes, lisez le fichier de commande correspondant dans commands/ et exécutez le workflow qui y est défini.

---

Workflow Principal

Pour TOUTE demande de conversion (qu'elle soit déclenchée par une commande slash ou un langage naturel) :

Étape 1 : Réfléchir — Capturer et Clarifier (Principe 1)

Recueillez ces entrées (ne demandez que si elles ne sont pas fournies) :

• Identité du thème (nom, slug, auteur, description)
• Type de projet source (page d'atterrissage, blog, e-commerce, portfolio, SaaS)
• Fichiers HTML à convertir
• Jetons de conception (couleurs, polices, espacement)
• Préférence du système de build (Vite 6 par défaut, ou wp-scripts, ou aucun)
• Prise en charge WooCommerce (oui/non)

Avant de continuer, énoncez explicitement :

• Ce que vous supposez (par exemple, « Je suppose que vous voulez une licence GPL-2.0-or-later car vous avez mentionné une soumission à WordPress.org »)
• Ce que vous NE faites PAS (par exemple, « Je ne vais pas créer la prise en charge WooCommerce puisque vous n'avez pas mentionné l'e-commerce »)
• Toute ambiguïté que vous devez résoudre (par exemple, « Votre hero utilise un fond vidéo — devrait-ce être un bloc core/cover avec vidéo ou un motif personnalisé avec une balise <video> ? »)

Pour les valeurs par défaut lorsque l'utilisateur ne répond pas, utilisez le tableau dans references/defaults.md.

Étape 2 : Planifier — Définir les Critères de Succès (Principes 1 + 4)

Avant d'écrire du code, produisez un Plan de Conversion qui mappe :

• Chaque fichier HTML source → modèle WordPress
• Chaque section répétée → motif de bloc
• En-tête/pied de page → parties de modèle
• Composants interactifs → stratégie JS (Interactivity API privilégiée, file d'attente classique pour les bibliothèques complexes — lisez references/modern-blocks.md)
• Jetons de conception → structure theme.json
• Besoins en données dynamiques → candidats Block Bindings API

Énoncez également les critères de succès pour cette conversion spécifique :

CRITÈRES DE SUCCÈS :
1. Le thème s'active sur WordPress [version] sans erreurs ni avis PHP
2. [Liste des pages] s'affiche visuellement conforme au HTML source
3. Tous les motifs apparaissent dans l'outil d'insertion de l'éditeur de site sous [catégories]
4. Tous les composants interactifs fonctionnent (les lister)
5. Aucun style en ligne dans le balisage des blocs
6. Toutes les chaînes sont prêtes pour la traduction
7. PHPCS WordPress-Extra passe avec zéro erreur
8. [Tout critère spécifique au projet]

Montrez ce plan à l'utilisateur. Obtenez une confirmation avant de procéder à la génération de fichiers (sauf si l'utilisateur dit explicitement « construis-le »).

Étape 3 : Exécuter — Méthodologie en 10 Phases (Principe 2)

Suivez les phases documentées dans references/methodology.md. Appliquez « Simplicité Avant Tout » à chaque phase — ne générez que ce dont le projet a besoin :

1. Auditer et Extraire — analyser la source, identifier les composants réutilisables
2. theme.json — générer le schéma v3 avec tous les paramètres + styles (incluant les styles de section, dimensions, position)
3. Modèles et Parties — convertir les pages HTML en balisage de blocs FSE
4. Motifs de Blocs — enregistrer les sections en tant que motifs réutilisables
5. Styles et Variations de Blocs — enregistrer des variantes personnalisées via theme.json + PHP
6. Intégration JavaScript — Interactivity API pour les motifs interactifs ; wp_enqueue_script() uniquement pour les bibliothèques complexes. Lisez references/modern-blocks.md D'ABORD.
7. functions.php et inc/ — fichiers d'amorçage conformes aux normes de codage WordPress
8. Accessibilité et Performance — WCAG 2.1 AA + Core Web Vitals + chargement CSS par bloc + préchargement des polices
9. i18n — chaînes prêtes pour la traduction partout
10. README et Docs — readme.txt au format WordPress.org

Vérifications de simplicité lors de l'exécution :

• Est-ce que je génère un fichier qui n'est pas nécessaire pour ce projet spécifique ? → Supprimez-le.
• Est-ce que j'ajoute un motif que l'utilisateur n'a pas demandé ? → Supprimez-le.
• Est-ce que j'écris du CSS pour quelque chose que theme.json gère ? → Déplacez-le dans theme.json.
• Est-ce que je crée une abstraction utilisée une seule fois ? → Intégrez-la.
• Est-ce que ce fichier de 200 lignes peut en faire 50 ? → Réécrivez-le.

Étape 4 : Générer les Fichiers (Principe 3)

Utilisez la structure de fichiers documentée dans references/file-structure.md. Générez chaque fichier avec un en-tête clair :

=== FILE: {{theme-slug}}/path/to/file.ext ===
<contenu>

Pour les grands projets (10+ pages HTML ou thèmes WooCommerce), divisez la livraison en 3 tours en utilisant references/multi-turn-strategy.md.

Précision chirurgicale pour les thèmes existants : Si vous modifiez un thème existant, ne générez QUE les fichiers modifiés. Incluez un résumé des différences montrant exactement ce qui a changé et pourquoi.

Étape 5 : Vérifier — Post-Génération (Principe 4)

Exécutez d'abord le docteur automatisé. Avant de fournir la sortie à l'utilisateur, exécutez :

node scripts/doctor.mjs <theme-dir>

Cela exécute les quatre vérifications de qualité (validation theme.json, lint du balisage des blocs, vérification de l'enregistrement des motifs, couverture i18n). Ne déclarez pas le succès tant que doctor ne se termine pas avec le code 0. S'il se termine avec un code non nul, revenez à la phase pertinente et corrigez chaque violation signalée avant de continuer.

Ensuite, fournissez :

• Instructions d'installation
• Liste de contrôle post-installation (activer, définir la page d'accueil, installer les plugins requis)
• Commandes de construction (npm install, npm run dev, npm run build)
• Section « Décisions Prises » — chaque hypothèse listée avec sa justification
• Étapes de vérification — comment confirmer que chaque critère de succès a été rempli :

VÉRIFICATION :
✅ node scripts/doctor.mjs <theme-dir> → se termine avec le code 0 (toutes les vérifications passent)
✅ Activer le thème → Confirmer aucune erreur PHP dans debug.log
✅ Visiter la page d'accueil → Confirmer la correspondance visuelle avec la source
✅ Ouvrir l'éditeur de site → Confirmer que tous les modèles sont listés
✅ Insérer un bloc → Confirmer que tous les motifs apparaissent sous les catégories correctes
✅ Exécuter `npx phpcs --standard=WordPress-Extra .` → Confirmer zéro erreur
✅ Vérifier la console du navigateur → Confirmer zéro erreur JS
✅ Exécuter Lighthouse → Confirmer un score d'accessibilité ≥ 90

Si une étape de vérification échoue, revenez à la phase pertinente et corrigez-la avant de signaler comme terminé. Ne déclarez pas le succès après un échec de vérification.

Si l'utilisateur signale un problème avec un thème généré, dirigez-le vers /wp-debug. Consultez references/troubleshooting.md pour la référence complète symptôme → cause racine → correction.

---

Règles de Qualité — Non Négociables

Ces règles s'appliquent à CHAQUE fichier généré. Voir references/quality-rules.md pour plus de détails.

❌ NE JAMAIS :

• Utiliser des attributs style="" en ligne dans le balisage des blocs
• Balises <style> ou <script> à l'intérieur des modèles/parties/motifs
• Couleurs/espacements codés en dur dans le CSS — utiliser var(--wp--preset--color--{slug})
• Fonctions WordPress obsolètes
• Sortie non échappée (toujours esc_htm

…