theme.json est devenu le centre de gravité d’un thème WordPress moderne. Il ne remplace pas totalement le CSS, mais il permet de définir les règles que l’éditeur, le front et les blocs partagent : couleurs, typographie, espacements, largeurs, styles globaux et presets. Pour une agence ou un développeur freelance, bien le configurer évite deux problèmes classiques : un éditeur trop libre qui casse la direction artistique, et un thème trop rigide qui oblige à écrire du CSS pour chaque variation.
Dans ce tutoriel, on va construire une base theme.json orientée production : typographie fluide, échelle d’espacement propre, largeur de contenu claire et variables réutilisables. L’objectif n’est pas de couvrir toutes les options possibles, mais de donner un socle stable pour un thème bloc WordPress en 2026.
1. Comprendre le rôle de theme.json
Dans un thème classique, beaucoup de décisions vivent dans style.css, functions.php et parfois dans des options dispersées. Dans un thème bloc, theme.json sert de contrat. WordPress lit ce fichier, génère des variables CSS, active ou désactive des contrôles dans l’éditeur et applique des styles globaux.
La structure minimale ressemble à ceci :
{
"version": 3,
"settings": {},
"styles": {}
}settings décrit ce que le thème autorise ou expose. styles décrit les styles appliqués par défaut. Cette séparation est importante : autoriser un contrôle de marge ne signifie pas définir toutes les marges ; définir une taille de texte par défaut ne signifie pas laisser l’utilisateur choisir n’importe quelle taille.
2. Activer une typographie fluide maîtrisée
La typographie fluide adapte progressivement les tailles de police à la largeur d’écran, souvent via clamp(). WordPress peut générer ces règles à partir des presets déclarés. Cela évite les ruptures brutales entre mobile et desktop, tout en conservant une vraie échelle de design.
{
"version": 3,
"settings": {
"typography": {
"fluid": true,
"customFontSize": false,
"fontSizes": [
{
"slug": "small",
"name": "Small",
"size": "0.95rem"
},
{
"slug": "body",
"name": "Body",
"size": "1.05rem",
"fluid": {
"min": "1rem",
"max": "1.125rem"
}
},
{
"slug": "heading-1",
"name": "Heading 1",
"size": "3rem",
"fluid": {
"min": "2.1rem",
"max": "3.4rem"
}
}
]
}
}
}Le choix important ici est customFontSize: false. Les rédacteurs conservent des presets utiles, mais ne peuvent pas entrer une taille arbitraire qui rendra le site incohérent dans six mois. Pour un site client, c’est souvent préférable.
3. Définir une échelle d’espacement cohérente
Les espacements sont l’autre point sensible. Quand chaque bloc reçoit une marge manuelle différente, le site devient vite impossible à maintenir. WordPress permet de déclarer des tailles d’espacement qui deviennent des presets et des variables CSS.
{
"version": 3,
"settings": {
"spacing": {
"customSpacingSize": false,
"units": ["rem", "px", "%", "vh", "vw"],
"spacingSizes": [
{ "slug": "20", "name": "2XS", "size": "0.25rem" },
{ "slug": "30", "name": "XS", "size": "0.5rem" },
{ "slug": "40", "name": "S", "size": "1rem" },
{ "slug": "50", "name": "M", "size": "1.5rem" },
{ "slug": "60", "name": "L", "size": "2.5rem" },
{ "slug": "70", "name": "XL", "size": "4rem" }
]
}
}
}Ces presets génèrent des variables comme --wp--preset--spacing--50. Vous pouvez ensuite les utiliser dans theme.json, dans des patterns ou dans un CSS complémentaire. L’intérêt est énorme : quand l’échelle change, les composants qui l’utilisent restent synchronisés.
4. Régler les largeurs de contenu
Un thème bloc a besoin de limites claires pour le contenu standard et les sections larges. Sans cela, les alignements wide et full deviennent imprévisibles selon les templates.
{
"version": 3,
"settings": {
"layout": {
"contentSize": "720px",
"wideSize": "1120px"
},
"useRootPaddingAwareAlignments": true
},
"styles": {
"spacing": {
"padding": {
"right": "var:preset|spacing|40",
"left": "var:preset|spacing|40"
}
}
}
}useRootPaddingAwareAlignments aide à gérer les alignements pleine largeur tout en respectant le padding racine. C’est un détail qui évite beaucoup de débordements horizontaux sur mobile, surtout avec des groupes alignfull.
5. Appliquer des styles globaux sans enfermer le site
Une fois les presets définis, on peut styliser les éléments courants. Le but n’est pas de tout contrôler au pixel près, mais de poser des valeurs par défaut solides.
{
"version": 3,
"styles": {
"typography": {
"fontSize": "var:preset|font-size|body",
"lineHeight": "1.65"
},
"elements": {
"heading": {
"typography": {
"lineHeight": "1.12",
"fontWeight": "750"
},
"spacing": {
"margin": {
"top": "var:preset|spacing|60",
"bottom": "var:preset|spacing|30"
}
}
},
"link": {
"typography": {
"textDecoration": "underline"
}
}
}
}
}Avec cette logique, les titres, paragraphes et liens partent d’une base lisible. Les variations restent possibles dans l’éditeur, mais elles s’appuient sur des tokens communs au lieu d’une collection de valeurs improvisées.
6. Utiliser les variables générées dans le CSS
theme.json ne supprime pas le CSS. Il le rend plus propre. Pour un composant spécifique, utilisez les variables générées plutôt que de recopier des valeurs fixes :
.wp-block-query .wp-block-post {
padding-block: var(--wp--preset--spacing--50);
border-bottom: 1px solid color-mix(in srgb, currentColor 14%, transparent);
}
.wp-block-post-title {
font-size: var(--wp--preset--font-size--heading-1);
}Cette approche garde le CSS lisible et aligné avec les réglages de l’éditeur. Elle facilite aussi les refontes : on peut modifier l’échelle typographique ou les espacements sans repasser dans chaque composant.
7. Tester dans le Site Editor
Après chaque modification, ouvrez l’éditeur de site, le livre de styles et plusieurs templates. Vérifiez les blocs qui utilisent les contrôles de marge, padding, taille de police et alignement. Testez aussi le front en mobile. Le fichier peut être valide JSON tout en produisant une expérience médiocre si les presets sont trop nombreux, mal nommés ou incohérents.
Un bon theme.json doit rester court, lisible et assumé. Il ne doit pas devenir un dumping ground de toutes les valeurs vues dans une maquette. Commencez par six espacements, cinq tailles de police, deux largeurs de layout, puis élargissez seulement si un besoin réel apparaît.
Conclusion
Maîtriser theme.json, c’est reprendre le contrôle du design system WordPress sans rendre l’éditeur hostile. La typographie fluide améliore la lisibilité, les espacements presets évitent la dérive visuelle, et les variables générées unifient le front avec l’expérience d’édition. Pour un thème bloc professionnel, ce fichier n’est pas un détail technique : c’est la charte graphique exécutable du site.
Commentaires (0)
Laisser un commentaire
Les commentaires sont modérés. Questions WordPress, cybersécurité ou dev web bienvenues.