Notre starter thème bloc interne a connu quatre refontes de son organisation de patterns en trois ans, chacune motivée par le même symptôme : un dossier /patterns devenu illisible à mesure que le nombre de développeurs contribuant au thème augmentait. La cinquième version, celle que nous détaillons ici, tient depuis plus d’un an sans nouvelle refonte nécessaire.
Le problème n’était jamais la fonctionnalité de patterns elle-même, robuste depuis son introduction dans le cœur de WordPress, mais l’absence de convention partagée sur la façon de les nommer, de les catégoriser et de les faire évoluer d’un projet client à l’autre.
Le piège initial : tout mettre au même endroit
Nos premières versions du starter thème plaçaient tous les patterns dans un unique dossier /patterns, sans distinction entre les patterns véritablement génériques (un pied de page standard, un bandeau d’appel à l’action) et les patterns développés pour un client précis, jamais destinés à être réutilisés ailleurs. Résultat : chaque nouveau projet héritait de patterns propres à un ancien client, créant une confusion permanente sur ce qui devait rester dans le starter et ce qui devait en sortir.
L’arborescence qui a tenu
La structure actuelle sépare clairement trois niveaux, chacun avec sa propre logique de maintenance :
starter-theme/
├── patterns/
│ ├── generiques/
│ │ ├── pied-de-page-standard.php
│ │ └── bandeau-cta-simple.php
│ ├── sections/
│ │ ├── hero-image-texte.php
│ │ └── grille-services.php
│ └── projets/
│ └── .gitkeep
└── inc/
└── patterns.phpLe dossier projets/ reste volontairement vide dans le starter lui-même : c’est là que chaque nouveau projet client ajoute ses patterns propres, dans une branche dédiée qui ne remonte jamais vers le starter commun, sauf décision explicite de généralisation d’un pattern jugé suffisamment universel.
Un préfixe de nommage pour éviter les collisions
Chaque pattern est enregistré avec un identifiant préfixé par le nom du starter, une pratique qui évite les collisions avec des patterns d’extensions tierces ou d’un futur thème enfant :
register_block_pattern(
'starter-agence/hero-image-texte',
array(
'title' => __( 'Hero image et texte', 'starter-agence' ),
'categories' => array( 'starter-agence-sections' ),
'content' => file_get_contents( __DIR__ . '/patterns/sections/hero-image-texte.php' ),
)
);Ce même préfixe s’applique aux catégories de patterns personnalisées, pour qu’elles restent regroupées et identifiables dans l’inserteur de blocs, même sur un projet qui active par ailleurs plusieurs extensions ajoutant leurs propres patterns.
Documenter au moment de la création, pas après
La règle la plus difficile à faire respecter dans l’équipe a été la documentation systématique : chaque nouveau pattern générique doit être accompagné d’un court commentaire en tête de fichier précisant son usage prévu et les projets où il a déjà servi. Sans cette discipline, on se retrouvait régulièrement avec des patterns quasi identiques créés indépendamment par deux développeurs qui ignoraient l’existence de l’autre.
- Un commentaire d’en-tête obligatoire pour tout pattern ajouté au dossier
generiques/. - Une revue trimestrielle du dossier
sections/pour repérer les doublons apparus entre deux projets. - Une règle stricte : un pattern qui n’a servi qu’une seule fois reste dans
projets/, il ne monte engeneriques/qu’après un second usage confirmé.
Un pattern générique créé sur la base d’un seul projet n’est pas générique, c’est juste un pattern spécifique qu’on n’a pas encore renommé. Notre règle du second usage confirmé a mis fin à ce faux positif récurrent.
En résumé
Une bibliothèque de patterns d’agence ne se stabilise pas par accumulation, mais par une architecture pensée dès le départ : séparation stricte entre générique et spécifique à un projet, préfixe de nommage cohérent pour éviter les collisions, et discipline de documentation appliquée au moment de la création. Ces trois règles, simples sur le papier, sont ce qui a mis fin à nos refontes successives du dossier de patterns.
