Le fichier theme.json est un fichier de configuration au format JSON introduit avec WordPress 5.8. Il se place à la racine d’un thème et permet de définir de manière centralisée les réglages globaux ainsi que les styles par défaut d’un site WordPress.
Concrètement, theme.json contrôle les options disponibles dans l’éditeur de blocs (Gutenberg). Il détermine par exemple la palette de couleurs, les tailles de police, les espacements, les largeurs de contenu ou encore les unités CSS autorisées. Il gère aussi les styles appliqués aux blocs individuels comme les paragraphes, les titres ou les boutons.
Avant son arrivée, ces réglages étaient dispersés entre le fichier functions.php, les feuilles de style CSS et diverses fonctions PHP. Le theme.json simplifie cette approche en regroupant tout dans un seul fichier structuré. Il fonctionne selon un système de couches : WordPress charge d’abord ses propres valeurs par défaut, puis le thème parent applique les siennes, suivi du thème enfant, et enfin les personnalisations de l’utilisateur via l’éditeur.
Ce fichier joue un rôle clé dans les thèmes basés sur les blocs (block themes) et constitue la base du Full Site Editing. Il génère automatiquement les variables CSS et les classes utilitaires nécessaires au rendu du site.
💡 Bon à savoir : Lors d’une mise à jour de thème, toute modification apportée directement au theme.json du thème parent sera écrasée. Pour personnaliser les réglages sans risque, utilisez toujours un thème enfant avec son propre fichier theme.json.
