Geler un cahier de styles globaux avant de passer la main à un repreneur

« theme.json centralise les réglages de style qui, dans un thème classique, se dispersaient entre functions.php, style.css et le Customizer » : c’est à peu près ce que dit la documentation officielle du bloc, et c’est exactement ce qui rend ce fichier précieux au moment de quitter un projet. Quand une équipe termine sa mission sur un site construit avec l’éditeur de site, la question qui se pose rarement au démarrage devient centrale à la fin : qu’est-ce qui doit rester stable pour que le repreneur ne casse rien dès sa première intervention ?

Nous avons livré cette année un site vitrine pour une savonnerie artisanale, construit sur un thème enfant de Twenty Twenty-Two. Le contrat s’arrêtait à la mise en ligne ; la maintenance passait à une autre équipe, moins familière de l’éditeur de site. Plutôt que de remettre un simple export de thème, nous avons pris le temps de figer et documenter le cahier de styles globaux. Voici la méthode retenue, et ce qu’elle ne résout pas.

Pourquoi un theme.json ne suffit pas tel quel

Un theme.json exporté depuis l’éditeur contient les valeurs explicitement modifiées, mais il hérite aussi de réglages par défaut du cœur qui n’apparaissent nulle part dans le fichier. La palette de couleurs, les tailles de police ou les espacements définis par WordPress s’appliquent silencieusement tant qu’ils ne sont pas surchargés. Un repreneur qui ouvre ce fichier sans connaître cet héritage risque de modifier une valeur en pensant reproduire un comportement, alors qu’il en supprime un autre, invisible jusque-là.

Ce que nous avons figé avant la passation

Trois éléments nous ont semblé mériter un gel explicite plutôt qu’un simple export :

• les valeurs de settings.color.palette et settings.typography.fontSizes, recopiées avec leur origine (thème ou cœur) en commentaire dans un fichier annexe ;
• les templates et template parts modifiés depuis l’éditeur, exportés vers le thème via la fonctionnalité d’export de blocs pour éviter qu’ils ne restent uniquement en base ;
• les variations de style actives, avec une capture d’écran de chaque variation dans un dossier de documentation livré à part.

Documenter ce qui ne se voit pas dans le fichier

Le fichier theme.json ne raconte pas pourquoi une valeur a été choisie. Nous avons ajouté un fichier PASSATION.md à la racine du thème, qui explique par exemple pourquoi la taille de police large a été réduite de 32 à 28 pixels — un ajustement demandé après un test sur mobile — ou pourquoi le contraste entre les couleurs primary et background a été volontairement resserré pour respecter les couleurs de la marque plutôt que les recommandations d’accessibilité par défaut.

Un exemple de réglage à risque

Voici un extrait simplifié du fichier livré, avec un commentaire qui n’existe pas dans le format JSON standard mais que nous conservons dans le fichier de documentation associé :

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        { "slug": "primary", "color": "#2f5233", "name": "Vert savon" },
        { "slug": "background", "color": "#f7f3ec", "name": "Blanc lin" }
      ]
    }
  }
}

Sans annotation, rien n’indique que le nom « Vert savon » correspond à une charte graphique validée par la cliente, et qu’il ne faut donc pas le renommer ni ajuster sa teinte sans repasser par elle.

Ce que le gel ne protège pas

Figer le cahier de styles globaux n’empêche pas un repreneur, ou la cliente elle-même, de modifier les couleurs et les tailles directement depuis le panneau Styles de l’éditeur de site. Ces changements s’enregistrent dans la table wp_posts, dans une entrée de type wp_global_styles, indépendamment du fichier theme.json livré. Autrement dit, le gel porte sur le point de départ, pas sur ce qui se passe après la livraison. Nous l’avons précisé noir sur blanc dans le document de passation, pour éviter tout malentendu sur ce qui était garanti.

Nous recommandons désormais de livrer systématiquement une capture des styles globaux au moment de la recette finale, datée et signée par la cliente : c’est la seule preuve fiable de l’état du site au jour de la passation.

Ce qu’on referait différemment

Avec le recul, nous aurions dû verrouiller certains blocs dès la conception plutôt qu’au moment de partir, pour limiter les dérives avant même la fin du projet. Le verrouillage de blocs et la documentation du cahier de styles globaux sont deux réponses complémentaires à deux problèmes différents : l’un empêche un contenu de bouger, l’autre explique pourquoi une valeur de style a été choisie. Confondre les deux nous a fait perdre du temps sur ce projet, en particulier au moment d’expliquer à la nouvelle équipe pourquoi certains blocs restaient modifiables alors que la charte semblait figée.

Ce qu’il faut retenir

Un export de theme.json n’est jamais une passation complète : c’est un point de départ qu’il faut annoter pour qu’il reste lisible sans la mémoire du projet. La prochaine fois, nous livrerons ce document de passation avant la dernière facture, pas après, pour qu’il fasse partie de la définition même de « site terminé ».