Skip to Content
WordPressPartie 3 — Gutenberg & éditeur de sitetheme.json & styles globaux

Chapitre 3.4 — theme.json & styles globaux

⏱️ TL;DR — theme.json est le fichier de configuration central d’un thème moderne : un design system déclaratif en JSON qui définit la palette de couleurs, la typographie, les espacements, les réglages activés dans l’éditeur (alignements, unités…) et les styles par défaut. Il alimente à la fois l’interface « Styles » de l’éditeur de site (côté créateur) et le CSS généré (côté front). Le comprendre en tant qu’utilisateur avancé maintenant rend le développement de thèmes (Partie 6) beaucoup plus clair.

🎯 Objectifs

  • Comprendre le rôle et la structure de theme.json.
  • Voir le lien entre theme.json et l’onglet Styles de l’éditeur.
  • Saisir la notion de presets (palette, tailles de police) et de variables CSS générées.
  • Anticiper son usage en développement (Partie 6).

1. Pourquoi theme.json change tout

Avant, la config d’un thème était éparpillée : functions.php (supports, tailles d’images), une feuille CSS, des réglages du Customizer. theme.json centralise tout ça dans un fichier déclaratif que WordPress lit pour :

  • configurer l’éditeur (quelles couleurs, quelles tailles de police, quels réglages sont proposés) ;
  • générer du CSS (variables et styles par défaut) pour le front ;
  • alimenter l’onglet Styles de l’éditeur de site (l’UI par-dessus theme.json).

Un seul fichier → cohérence entre ce que le créateur voit dans l’éditeur et ce qui s’affiche sur le site.

2. La structure (survol)

theme.json s’organise en grandes sections :

{
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "primary", "color": "#3858e9", "name": "Primaire" },
        { "slug": "base", "color": "#ffffff", "name": "Fond" }
      ],
      "custom": true
    },
    "typography": {
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Petit" },
        { "slug": "large", "size": "1.5rem", "name": "Grand" }
      ]
    },
    "spacing": { "units": ["px", "rem", "%", "vh"] },
    "layout": { "contentSize": "720px", "wideSize": "1100px" }
  },
  "styles": {
    "color": { "background": "var(--wp--preset--color--base)" },
    "typography": { "lineHeight": "1.6" },
    "elements": {
      "button": {
        "color": { "background": "var(--wp--preset--color--primary)" }
      }
    }
  }
}
  • settings : ce que l’éditeur propose (palette, tailles de police, unités, largeurs de mise en page, activation de fonctionnalités).
  • styles : les styles par défaut appliqués (couleur de fond, hauteur de ligne, style des boutons, des liens…).

💡 Pour un dev React — theme.json est un design token file (comme un theme.ts chez vous, ou la config de Tailwind). Les presets (couleurs, tailles) deviennent des variables CSS au nom déterministe : --wp--preset--color--primary, --wp--preset--font-size--large. C’est du design system as data : vous déclarez les tokens une fois, l’éditeur et le front les consomment. Très proche de votre intuition « source de vérité de design centralisée ».

3. Presets → variables CSS

Chaque preset défini dans settings génère automatiquement une variable CSS et une classe utilitaire :

Preset dans theme.jsonVariable CSS généréeClasse générée
color.palette slug primary--wp--preset--color--primary.has-primary-color, .has-primary-background-color
typography.fontSizes slug large--wp--preset--font-size--large.has-large-font-size
spacing.spacingSizes--wp--preset--spacing--…—

Résultat : quand un créateur choisit « couleur primaire » dans l’éditeur, WordPress applique la classe correspondante, elle-même reliée à la variable — tout est cohérent et centralisé. Changez la couleur dans theme.json (ou dans Styles), elle se propage partout.

4. Les styles globaux (côté créateur)

L’onglet Styles de l’éditeur de site est l’interface visuelle de theme.json : le créateur ajuste couleurs, typo, mise en page sans éditer le JSON, et ses choix sont enregistrés en base (surchargeant theme.json). On peut aussi proposer plusieurs variations de styles (styles/*.json) — des « thèmes de couleur » alternatifs sélectionnables d’un clic.

⚠️ Piège — Ce que le créateur modifie dans Styles est stocké en base et prime sur le theme.json livré en fichiers. En développement, si vos changements de theme.json « ne s’appliquent pas », c’est peut-être qu’une personnalisation en base les écrase → Styles → Réinitialiser, ou vérifiez côté base (Partie 6).

5. Ce que ça prépare

En Partie 6, theme.json sera le fichier central de votre thème bloc : vous y déclarerez la palette, la typo, les largeurs, les supports (alignements, couleurs custom), et les styles par défaut. Bien le maîtriser, c’est livrer des thèmes cohérents, personnalisables et maintenables — et offrir au client une charte qu’il peut ajuster seul sans casser le design.

✏️ Exercices

  1. Un client veut que « couleur primaire » soit #e91e63 partout et disponible dans l’éditeur. Dans quelle section de theme.json l’ajoutez-vous ?
  2. Quelle variable CSS sera générée pour une taille de police de slug huge ?
  3. Vos modifications de theme.json semblent ignorées sur un site en ligne. Quelle cause vérifiez-vous ?

✅ Solution

  1. Dans settings.color.palette, avec un objet { "slug": "primary", "color": "#e91e63", "name": "Primaire" }. Elle apparaîtra dans l’éditeur et générera --wp--preset--color--primary.
  2. --wp--preset--font-size--huge (et la classe .has-huge-font-size).
  3. Une personnalisation via l’onglet Styles stockée en base qui surcharge le theme.json en fichiers ; réinitialiser les styles ou vérifier la base.

🧠 Quiz de révision

1. Quel est le rôle de theme.json ?

Centraliser la configuration de design d’un thème (palette, typo, espacements, réglages de l’éditeur, styles par défaut) en un fichier déclaratif.

2. Que génère un preset de couleur ?

Une variable CSS (--wp--preset--color--slug) et des classes utilitaires (.has-slug-color…).

3. Différence entre les sections settings et styles ?

settings = ce que l’éditeur propose (options disponibles) ; styles = les styles par défaut effectivement appliqués.

4. Qu’est-ce que l’onglet « Styles » de l’éditeur de site ?

L’interface visuelle de theme.json, où le créateur ajuste le design ; ses choix sont stockés en base et priment sur les fichiers.

5. À quel concept front-end theme.json ressemble-t-il ?

À un fichier de design tokens (comme la config Tailwind ou un theme.ts) : source de vérité centralisée, consommée par l’éditeur et le front.

Chapitre suivant : Gabarits & parties de gabarit (FSE).

Full Site Editing : l'éditeur de siteGabarits & parties de gabarit (FSE)