theme.json expérimental dans un thème hybride : ce qu’on peut déjà figer

WordPress 5.8, sorti en juillet 2021, a stabilisé la première version de theme.json après plus d’un an de développement expérimental derrière un indicateur de fonctionnalité. Pour un thème hybride — un thème classique qui adopte certains blocs et certains réglages de l’éditeur sans basculer vers un thème 100 % bloc — la question se pose concrètement : que peut-on déjà figer dans ce fichier sans risquer de tout réécrire à la prochaine version mineure ?

Ce qu’est vraiment theme.json à ce stade

theme.json centralise, dans un unique fichier JSON à la racine du thème, les réglages qui pilotaient auparavant add_theme_support() et une bonne partie du CSS de l’éditeur. Il définit deux grandes catégories : les settings, qui activent ou désactivent des fonctionnalités (couleurs personnalisées, tailles de police, alignement large), et les styles, qui appliquent des valeurs par défaut aux éléments et aux blocs. Depuis WordPress 5.8, ce fichier est officiellement supporté, et son schéma correspond à la version 1.

{
    "version": 1,
    "settings": {
        "color": {
            "palette": [
                { "slug": "primaire", "color": "#1a4d8f", "name": "Bleu primaire" },
                { "slug": "secondaire", "color": "#f2f2f2", "name": "Gris clair" }
            ]
        },
        "typography": {
            "fontSizes": [
                { "slug": "petit", "size": "14px", "name": "Petit" },
                { "slug": "moyen", "size": "18px", "name": "Moyen" }
            ]
        }
    }
}

Ce qui est déjà solide à figer

Certains blocs de réglages ont peu bougé depuis les premières versions expérimentales et peuvent être considérés comme fiables pour un projet livré aujourd’hui :

• La palette de couleurs (settings.color.palette) et son activation ou non de la palette par défaut de WordPress.
• Les tailles de police personnalisées (settings.typography.fontSizes).
• L’activation de la largeur large et pleine (settings.layout dans sa forme simple, largeur de contenu et largeur large).
• Les styles globaux de base appliqués au corps du site (styles.color, styles.typography).

Ce qui reste marqué expérimental

Plusieurs réglages plus fins, en particulier autour de l’espacement, restent à ce stade sous une clé préfixée __experimental dans le code source de Gutenberg, ce qui signale explicitement une API encore instable :

{
    "settings": {
        "spacing": {
            "__experimentalDefaultControls": {
                "padding": true
            }
        }
    }
}

Le préfixe __experimental n’est pas qu’une convention de nommage : il signifie concrètement que la structure de cette clé peut changer de forme, voire être renommée, dans une version future sans processus de dépréciation en douceur. Adopter ces réglages aujourd’hui dans un thème livré à un client, c’est accepter de potentiellement devoir réécrire cette partie du fichier lors d’une future mise à jour majeure.

La stratégie retenue pour un thème hybride

Sur ce projet, la décision a été de figer immédiatement le socle stable (couleurs, tailles de police, largeurs) dans theme.json, tout en continuant à gérer l’espacement fin via le CSS classique du thème, en dehors du fichier, le temps que ces réglages sortent de leur statut expérimental :

.wp-block-group {
    padding: 2rem;
}

Cette approche évite de dépendre d’une API encore mouvante pour un réglage visuel qui peut très bien continuer à vivre dans une feuille de style classique en attendant la stabilisation.

Adopter theme.json sans tout migrer

Un point souvent mal compris : un thème hybride peut déclarer un theme.json sans pour autant migrer l’ensemble de ses templates PHP vers des fichiers HTML de blocs. Les templates classiques (header.php, page.php, single.php) continuent de fonctionner normalement ; theme.json influence uniquement les réglages disponibles dans l’éditeur de blocs et le CSS global généré, sans exiger l’éditeur de site complet, qui n’existera d’ailleurs officiellement qu’à partir de WordPress 5.9.

Piège à anticiper

Un thème enfant qui ne définit pas son propre theme.json hérite silencieusement de celui du thème parent : un changement dans le fichier parent peut donc modifier l’apparence d’un site enfant sans qu’aucune ligne de code du thème enfant n’ait été touchée. Ce comportement, hérité du fonctionnement classique des thèmes enfants sur style.css, s’applique désormais aussi à theme.json.

En résumé

Avec WordPress 5.8, le socle de theme.json — couleurs, typographies, largeurs — peut être adopté en confiance dans un thème hybride. Les réglages encore marqués __experimental, en particulier autour de l’espacement, méritent d’attendre leur stabilisation avant d’y engager la charte graphique complète d’un projet client.