Le guide du "theme.json" pour débutants

Tu as déjà passé une heure dans le Customizer à ajuster une couleur, puis à te demander pourquoi elle ne s’applique pas partout ? Ou à bricoler du CSS “vite fait” qui finit par casser un bouton au prochain update ? Depuis l’arrivée de l’éditeur de site, theme.json WordPress change la donne : un seul fichier peut piloter les styles globaux, les réglages des blocs et une bonne partie des “options de thème” qui, avant, vivaient dans des menus éparpillés. Le meilleur dans tout ça : même en étant débutant, tu peux obtenir des résultats propres et cohérents, sans te transformer en magicien du CSS.

Objectif

Comprendre ce qu’est theme.json WordPress, à quoi il sert, et comment l’utiliser sans se noyer dans la doc. L’idée : repartir avec un Guide débutant theme.json clair, des exemples concrets et une méthode pour modifier ton thème proprement, tout en gardant une cohérence visuelle sur l’ensemble du site.

Prérequis

Rien de très lourd. Pour suivre et tester tranquillement :

• Un site WordPress récent (idéalement WordPress 6.x) avec un thème compatible blocs (type Twenty Twenty-Four, ou un thème FSE).
• Un accès aux fichiers du thème (FTP, gestionnaire de fichiers, ou un environnement local comme LocalWP).
• Un éditeur de texte (VS Code, Sublime Text, même Notepad++).
• Une curiosité minimale : tu vas toucher à du JSON, donc attention aux virgules et aux accolades.

Astuce de terrain : fais tes tests sur un site de staging ou en local. Un simple caractère de trop dans un JSON peut empêcher WordPress de lire le fichier correctement.

Étape 1 : Comprendre le rôle de theme.json (et où il vit)

theme.json est un fichier de configuration qui permet de définir des réglages et styles globaux pour ton thème. Il se place généralement à la racine du thème : /wp-content/themes/ton-theme/theme.json. WordPress le lit pour :

• définir des valeurs par défaut (typographie, couleurs, espacements) ;
• contrôler les options disponibles dans l’éditeur (palette de couleurs autorisée, tailles de police proposées, etc.) ;
• styler des blocs spécifiques de façon cohérente ;
• uniformiser le rendu du site sans multiplier les options dispersées.

Le déclic : styles globaux plutôt que rustines

Un exemple simple. Sur un site vitrine, tu veux que tous les titres aient la même police et la même couleur, et que les boutons aient un arrondi et une couleur de fond cohérents. Avant, on jonglait entre CSS, options du thème, et réglages par bloc. Avec theme.json WordPress, tu centralises cette intention. Résultat : moins de surprises, moins de “pourquoi ça change ici et pas là”.

À quoi ressemble un theme.json minimal

Tu peux commencer avec une base très simple :

Exemple (structure typique)

{ "version": 2, "settings": {}, "styles": {} }

Ne te formalise pas : la magie se passe quand tu ajoutes progressivement des réglages dans settings (ce qui est disponible dans l’éditeur) et styles (ce qui s’applique visuellement).

Étape 2 : Ajouter des réglages utiles (couleurs, typo, largeur)

Le meilleur point de départ d’un Guide débutant theme.json, c’est la cohérence visuelle. Commence par verrouiller une palette et quelques tailles de police. Ça évite le fameux site “arc-en-ciel” où chaque page a sa propre humeur.

Créer une palette de couleurs propre

Tu définis des couleurs avec un nom et un slug. Ensuite, l’éditeur proposera ces couleurs, et tu peux même désactiver les couleurs personnalisées si tu veux cadrer la création.

Exemple (palette et blocage des couleurs custom)

{ "version": 2, "settings": { "color": { "custom": false, "palette": [ { "name": "Noir", "slug": "noir", "color": "#111111" }, { "name": "Blanc", "slug": "blanc", "color": "#ffffff" }, { "name": "Primaire", "slug": "primaire", "color": "#2563eb" }, { "name": "Accent", "slug": "accent", "color": "#f97316" } ] } } }

Anecdote très réelle : sur un site associatif, j’ai vu 14 bleus différents utilisés “à l’œil”. Après mise en place d’une palette dans theme.json, le rendu est devenu instantanément plus pro… sans toucher au contenu, juste en harmonisant.

Proposer des tailles de police cohérentes

Même logique pour la typographie : tu peux proposer 4 ou 5 tailles utiles. Pas besoin de 27 variations.

Exemple (tailles de police)

{ "version": 2, "settings": { "typography": { "fontSizes": [ { "name": "S", "slug": "s", "size": "14px" }, { "name": "M", "slug": "m", "size": "16px" }, { "name": "L", "slug": "l", "size": "20px" }, { "name": "XL", "slug": "xl", "size": "28px" } ] } } }

Définir une largeur de contenu raisonnable

Les pages trop larges fatiguent l’œil. Une largeur de contenu et une largeur “large” (wide) donnent un cadre clair.

Exemple (layout)

{ "version": 2, "settings": { "layout": { "contentSize": "720px", "wideSize": "1100px" } } }

Étape 3 : Appliquer des styles globaux et styliser des blocs

Une fois les options en place, tu passes au rendu. Ici, styles te permet d’imposer des valeurs par défaut : couleur du texte, arrière-plan, typographie, et même styles par bloc.

Styles globaux : le socle du design

Tu peux définir un fond, une couleur de texte, et des réglages de typographie globaux. C’est le genre de base qui évite les pages incohérentes.

Exemple (styles globaux)

{ "version": 2, "styles": { "color": { "background": "#ffffff", "text": "#111111" }, "typography": { "fontSize": "16px", "lineHeight": "1.7" } } }

Styliser un bloc précis (boutons, titres, citations)

Là où theme.json WordPress devient vraiment agréable : tu peux cibler les blocs sans écrire des sélecteurs CSS interminables. Exemple avec le bouton : couleur, bordure, rayon, padding… tout en restant dans une logique “design system”.

Exemple (bloc Button)

{ "version": 2, "styles": { "blocks": { "core/button": { "border": { "radius": "10px" }, "color": { "background": "#2563eb", "text": "#ffffff" }, "spacing": { "padding": { "top": "12px", "bottom": "12px", "left": "18px", "right": "18px" } } } } } }

Theme.json vs Customizer WordPress : qui fait quoi ?

La question revient tout le temps, et elle est légitime : Theme.json vs Customizer WordPress, est-ce que l’un remplace l’autre ? Dans beaucoup de cas, oui, surtout sur les thèmes blocs.

• Customizer WordPress : historiquement pensé pour modifier l’apparence via une interface, souvent dépendante des options proposées par le thème (logo, couleurs, mise en page…).
• theme.json : pensé pour unifier les réglages et styles autour des blocs et des styles globaux, en rendant le thème plus “prévisible” et plus standard.

Concrètement, si ton thème est FSE, tu passeras de plus en plus par l’éditeur de site et par theme.json WordPress pour gérer l’apparence. Le Customizer reste utile sur certains thèmes classiques, ou pour des options spécifiques non migrées.

Conseils pratiques pour éviter les pièges

• Avance par petites touches : commence par palette + typo + layout, puis styles globaux, puis blocs un par un.
• Soigne la validité JSON : pas de virgule finale, guillemets droits, accolades bien fermées.
• Garde une logique de marque : 2 couleurs principales + 1 accent, et une hiérarchie typographique simple.
• Teste sur plusieurs pages : une page “Texte long” et une page “Landing” révèlent vite les incohérences.
• Documente tes choix : un petit fichier interne “design-notes.txt” avec codes couleurs et intentions, ça sauve du temps plus tard.

Résultat attendu

Après ces ajustements, tu dois obtenir :

• un éditeur WordPress plus cadré (palette et tailles de police propres) ;
• un site plus cohérent sans devoir retoucher chaque bloc à la main ;
• des boutons, titres et éléments récurrents harmonisés ;
• moins de dépendance aux options éparpillées, et une base plus maintenable.

Le vrai bénéfice se voit sur la durée : quand tu ajoutes une nouvelle page, tu n’as pas à “réinventer” le style. Tu poses le contenu, le design suit naturellement.

Troubleshooting

Le site ne reflète pas les changements

• Vérifie que tu modifies bien le theme.json du thème actif.
• Vide le cache (plugin de cache, cache serveur, cache navigateur).
• Regarde si tu as des styles personnalisés dans l’éditeur de site qui surchargent les valeurs globales.

Erreur JSON ou comportement étrange

• Copie/colle ton fichier dans un validateur JSON pour repérer une virgule en trop.
• Vérifie les guillemets : uniquement des guillemets droits (").
• Teste en supprimant une section récemment ajoutée pour isoler la cause.

Les réglages n’apparaissent pas dans l’éditeur

• Assure-toi d’être sur un thème qui supporte bien l’éditeur de site (thème blocs).
• Vérifie la structure : settings pour les options, styles pour l’apparence.
• Mets à jour WordPress si tu es sur une version ancienne : certaines clés ont évolué.

Je veux garder une liberté créative (sans chaos)

• Autorise les couleurs custom mais garde une palette forte : custom: true tout en proposant 4-6 couleurs officielles.
• Propose quelques tailles de police “maison” plutôt qu’un slider libre.

Conclusion engageante

Quand tu commences à utiliser theme.json WordPress, tu sens vite le changement : moins de bricolage, plus de cohérence, et une sensation de contrôle propre sur le design. Le plus agréable, c’est que tu n’as pas besoin de tout maîtriser d’un coup. Une palette bien pensée, une typographie cadrée et deux ou trois styles de blocs bien choisis suffisent déjà à donner un site plus solide. Si tu hésitais entre Theme.json vs Customizer WordPress, vois theme.json comme une base moderne et structurante, surtout pour les thèmes blocs. Et si tu veux aller plus loin, la prochaine étape naturelle consiste à créer des variations de styles (style variations) pour proposer plusieurs ambiances sans toucher au contenu.