theme.json

Définition : Le fichier theme.json centralise des paramètres et styles WordPress pour l’éditeur de blocs et le rendu du site. Il décrit notamment palettes, typographie, espacements et styles des éléments compatibles.

Terminologie

Nom technique : theme.json

Appellations : Nom principal utilisé

À quoi cela sert, concrètement

Il crée un langage de configuration commun entre le Core, le thème et les préférences de l’utilisateur. Des réglages partagés réduisent la nécessité d’écrire du CSS spécifique pour chaque variante visuelle.

Fonctionnement détaillé

WordPress lit le document JSON du thème, fusionne les différentes origines de configuration selon leurs priorités et génère des styles ainsi que des contrôles d’édition. La version du schéma détermine quelles propriétés sont reconnues.

Quand l’utiliser : contexte et choix techniques

Le privilégier pour décrire une identité visuelle cohérente dans un thème moderne. Garder du CSS lorsque la propriété recherchée dépasse ce que l’API accepte ou exige un comportement très spécifique.

Situation professionnelle réaliste

ATOOLPHA souhaite limiter les couleurs proposées aux éditeurs tout en conservant un nom technique stable pour chaque couleur.

Exemple pratique — JSON commenté par l’explication

Exemple pédagogique : adapter le nom du thème, les fichiers et les conditions à un environnement de développement. Il ne constitue pas une preuve d’exécution sur ATOOLPHA.

{
  "version": 3,
  "settings": {
    "color": {
      "custom": false,
      "palette": [
        { "name": "Bleu", "slug": "bleu", "color": "#245A81" },
        { "name": "Or", "slug": "or", "color": "#D6A84B" }
      ]
    }
  }
}

Décryptage de l’exemple, étape par étape

La clé version sélectionne le format de configuration ; settings.color.palette définit les couleurs nommées ; custom:false retire la possibilité de choisir librement une couleur dans les contrôles qui respectent ce réglage.

Résultat observable

Les blocs compatibles disposent des couleurs Bleu et Or prédéfinies. Le comportement exact des contrôles dépend de leur support et de la version WordPress installée.

Exercice de vérification pratique

Créer theme.json dans un thème de développement, contrôler sa validité JSON, puis choisir un bloc Paragraphe. Vérifier les couleurs disponibles et inspecter les variables CSS générées.

Pièges, limites et sécurité

Ne pas confondre version de schéma theme.json et version de WordPress. Le schéma version 3 est pris en charge depuis WordPress 6.6 ; les nouveaux réglages ne sont pas tous rétrocompatibles.

Différences avec les notions voisines

La configuration theme.json n’est ni une API JavaScript ni le fichier style.css ; ces mécanismes peuvent coexister.

Diagnostic avancé et cas de maintenance

Cas avancé : une valeur du fichier ne se retrouve pas dans les styles calculés. Contrôler d’abord la version du schéma, le support de cette propriété, les règles de fusion et les personnalisations enregistrées dans l’éditeur. Une validation JSON réussie n’implique pas que toutes les clés soient interprétées par la version de WordPress.