Créer un thème FSE WordPress avec theme.json v3 (2026)

Le Full Site Editing a longtemps fait peur aux développeurs WordPress habitués au PHP et aux fichiers de template classiques — et c’est compréhensible. Mais en 2026, FSE est devenu incontournable, et theme.json v3 apporte enfin la maturité qu’on attendait pour construire des thèmes vraiment propres et maintenables. Dans ce guide complet, on va tout couvrir : de la structure minimale d’un thème FSE jusqu’à sa distribution sur WordPress.org ou ThemeForest.

Comprendre le Full Site Editing et theme.json v3 en 2026

Le Full Site Editing, c’est un vrai changement de paradigme pour les développeurs WordPress. On ne parle plus de bricoler un functions.php à rallonge ou d’empiler des hooks dans tous les sens. Tout — ou presque — se passe désormais via theme.json et des templates construits avec des blocs. Si vous n’avez pas encore sauté le pas, 2026 est vraiment le bon moment.

Ce que change vraiment le FSE pour le développement de thèmes

Avec le FSE, la logique de construction d’un thème est fondamentalement différente. Fini (ou presque) le duo header.php / footer.php géré en PHP. À la place, on utilise des templates de blocs en HTML, que l’utilisateur peut modifier directement depuis l’éditeur de site. C’est à la fois plus accessible côté client… et parfois déroutant pour les développeurs habitués à l’approche classique.

Ce qui change concrètement :

Plus de surcharge de functions.php : les styles, les palettes de couleurs, les préréglages typographiques — tout ça passe par theme.json.
Les templates sont des fichiers HTML avec des commentaires de blocs, pas du PHP imbriqué.
L’éditeur de site permet aux utilisateurs de modifier header, footer et templates sans toucher au code.
Les child themes évoluent aussi : on peut surcharger theme.json sans réécrire toute la logique PHP.

Bon, soyons honnêtes : il y a une courbe d’apprentissage. Mais une fois qu’on a compris la logique, le développement devient beaucoup plus propre et maintenable.

Les nouveautés de theme.json v3 à connaître absolument

La version 3 de theme.json est disponible depuis WordPress 6.5, et elle apporte plusieurs changements importants. La première chose à faire : déclarer "version": 3 en haut de votre fichier, c’est obligatoire pour activer les nouvelles fonctionnalités.

Voici ce qui change vraiment :

La propriété blockTypes pour le scope des styles On peut maintenant cibler un bloc spécifique dans un contexte précis. Par exemple, appliquer un style uniquement aux paragraphes à l’intérieur d’un core/group. C’est bien plus fin qu’avant.

{
  "version": 3,
  "styles": {
    "blocks": {
      "core/paragraph": {
        "color": {
          "text": "var(--wp--preset--color--primary)"
        }
      }
    }
  }
}

Support des custom properties CSS natives theme.json v3 gère nativement les CSS custom properties. Les valeurs définies dans settings.custom sont automatiquement exposées en tant que variables CSS, avec un nommage plus cohérent qu’en v2.

La gestion améliorée de settings.blocks On peut désormais activer ou désactiver des fonctionnalités spécifiques bloc par bloc. Par exemple, désactiver la palette de couleurs globale pour un bloc précis, ou lui autoriser des options qu’on a bloquées globalement. C’est un vrai gain de contrôle pour les thèmes « locked down ».

À noter : WordPress 6.7+ est la version recommandée en 2026 pour profiter pleinement de toutes ces fonctionnalités v3. Certaines options ne fonctionnent pas correctement sur des versions antérieures.

Structure d’un thème FSE minimaliste : les fichiers indispensables

Un thème FSE n’a pas besoin de 50 fichiers pour fonctionner. Voici la structure minimale viable en 2026 :

mon-theme/
├── style.css          ← headers uniquement (nom, auteur, version...)
├── theme.json         ← toute la configuration du thème
├── templates/
│   └── index.html     ← template obligatoire
├── parts/
│   ├── header.html    ← pattern de header
│   └── footer.html    ← pattern de footer
└── patterns/          ← optionnel, mais recommandé
    └── hero.php

Le fichier style.css ne contient plus de CSS réel (ou très peu) — juste les métadonnées du thème dans un commentaire en en-tête. Tout le design passe par theme.json et les styles de blocs.

Le dossier /templates doit contenir au minimum index.html. C’est le fallback universel. Ensuite, vous pouvez ajouter single.html, archive.html, 404.html, etc., selon vos besoins.

Le dossier /parts accueille vos « template parts » : le header et le footer en priorité. Ces fichiers sont référencés dans vos templates via le bloc core/template-part.

Et /patterns ? C’est optionnel, mais franchement utile dès qu’on veut proposer des mises en page prêtes à l’emploi à l’utilisateur depuis l’éditeur. C’est là que le FSE devient vraiment puissant.

Configurer theme.json v3 : settings, styles et custom properties

Le fichier theme.json v3, c’est vraiment le cœur du réacteur d’un thème FSE. Toute la configuration visuelle de votre thème — couleurs, typographies, espacements — passe par là. Fini les dizaines de fichiers PHP dispersés : on centralise tout dans un seul fichier JSON structuré et lisible.

Déclarer les couleurs, typographies et espacements dans settings

La section settings de theme.json v3 permet de définir l’ensemble des tokens de design de votre thème. Voici un exemple complet et commenté :

{
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        {
          "slug": "primary",
          "color": "#2563EB",
          "name": "Primaire"
        },
        {
          "slug": "secondary",
          "color": "#7C3AED",
          "name": "Secondaire"
        },
        {
          "slug": "neutral-dark",
          "color": "#1E293B",
          "name": "Sombre"
        },
        {
          "slug": "neutral-light",
          "color": "#F8FAFC",
          "name": "Clair"
        }
      ],
      "custom": true,
      "customDuotone": false
    },
    "typography": {
      "fontFamilies": [
        {
          "slug": "inter",
          "name": "Inter",
          "fontFamily": "Inter, sans-serif",
          "fontFace": [
            {
              "src": [ "file:./assets/fonts/inter-regular.woff2" ],
              "fontWeight": "400",
              "fontStyle": "normal"
            },
            {
              "src": [ "file:./assets/fonts/inter-bold.woff2" ],
              "fontWeight": "700",
              "fontStyle": "normal"
            }
          ]
        },
        {
          "slug": "serif-display",
          "name": "Playfair Display",
          "fontFamily": "'Playfair Display', serif"
        }
      ],
      "fontSizes": [
        { "slug": "sm",   "size": "0.875rem", "name": "Petit" },
        { "slug": "md",   "size": "1rem",     "name": "Normal" },
        { "slug": "lg",   "size": "1.25rem",  "name": "Grand" },
        { "slug": "xl",   "size": "1.75rem",  "name": "Très grand" },
        { "slug": "2xl",  "size": "2.5rem",   "name": "Titre" }
      ]
    },
    "spacing": {
      "spacingScale": {
        "operator": "*",
        "increment": 1.5,
        "steps": 7,
        "mediumStep": 1.5,
        "unit": "rem"
      },
      "spacingSizes": [
        { "slug": "20", "size": "0.5rem",  "name": "XS" },
        { "slug": "40", "size": "1rem",    "name": "S" },
        { "slug": "60", "size": "1.5rem",  "name": "M" },
        { "slug": "80", "size": "2.5rem",  "name": "L" },
        { "slug": "100","size": "4rem",    "name": "XL" }
      ],
      "padding": true,
      "margin": true,
      "customSpacingSize": true
    }
  }
}

Quelques points importants à noter : la clé "version": 3 est obligatoire pour activer les fonctionnalités de la dernière spécification. Et concernant les polices déclarées via fontFace, WordPress les enregistre automatiquement et les charge uniquement quand elles sont utilisées — ce qui est une bonne nouvelle pour les performances.

Appliquer les styles globaux et les styles par bloc

La section styles est distincte de settings : là où settings expose des options, styles applique des valeurs concrètes. On y définit les styles globaux du thème, les styles des éléments HTML courants et les styles spécifiques à chaque bloc.

{
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--neutral-light)",
      "text": "var(--wp--preset--color--neutral-dark)"
    },
    "typography": {
      "fontFamily": "var(--wp--preset--font-family--inter)",
      "fontSize": "var(--wp--preset--font-size--md)",
      "lineHeight": "1.65"
    },
    "spacing": {
      "blockGap": "var(--wp--preset--spacing--60)"
    },
    "elements": {
      "link": {
        "color": {
          "text": "var(--wp--preset--color--primary)"
        },
        ":hover": {
          "color": {
            "text": "var(--wp--preset--color--secondary)"
          }
        }
      },
      "h1": {
        "typography": {
          "fontFamily": "var(--wp--preset--font-family--serif-display)",
          "fontSize": "var(--wp--preset--font-size--2xl)",
          "fontWeight": "700"
        }
      },
      "h2": {
        "typography": {
          "fontSize": "var(--wp--preset--font-size--xl)"
        }
      }
    },
    "blocks": {
      "core/button": {
        "color": {
          "background": "var(--wp--preset--color--primary)",
          "text": "#ffffff"
        },
        "typography": {
          "fontWeight": "600"
        },
        "border": {
          "radius": "6px"
        }
      },
      "core/heading": {
        "typography": {
          "fontFamily": "var(--wp--preset--font-family--serif-display)"
        }
      }
    }
  }
}

La clé styles.blocks est particulièrement puissante : elle permet de cibler n’importe quel bloc par son nom (core/button, core/paragraph, core/group, etc.) et de lui appliquer des styles sans écrire une seule ligne de CSS manuellement. WordPress se charge de générer les sélecteurs CSS appropriés.

Exploiter les custom properties CSS générées automatiquement

C’est l’une des fonctionnalités les plus pratiques de theme.json. WordPress génère automatiquement des custom properties CSS (variables CSS) pour chaque preset déclaré dans settings. Le schéma de nommage suit une convention précise :

Couleurs → --wp--preset--color--{slug}
Tailles de police → --wp--preset--font-size--{slug}
Familles de police → --wp--preset--font-family--{slug}
Espacements → --wp--preset--spacing--{slug}

Donc si vous déclarez une couleur avec le slug primary, WordPress génère automatiquement --wp--preset--color--primary dans la balise <style> du front-end. Vous pouvez ensuite l’utiliser partout : dans theme.json lui-même (comme on l’a vu ci-dessus), dans un fichier style.css, ou dans des blocs custom.

/* Dans votre style.css ou un fichier CSS enregistré */
.mon-composant-custom {
  background-color: var(--wp--preset--color--primary);
  font-size: var(--wp--preset--font-size--lg);
  padding: var(--wp--preset--spacing--60);
}

Par contre, attention : si vous renommez ou supprimez un slug dans theme.json, toutes les références à cette variable CSS seront cassées sur le front-end. C’est pour ça qu’il faut bien réfléchir à la nomenclature dès le départ !

Gérer les variations de styles (style variations)

Les variations de styles sont une fonctionnalité vraiment intéressante, surtout si vous envisagez de commercialiser votre thème. Le principe : vous créez plusieurs fichiers JSON dans un dossier /styles/ à la racine de votre thème, chacun représentant une variante visuelle complète.

mon-theme/
├── theme.json          ← configuration par défaut
├── styles/
│   ├── dark-mode.json
│   ├── colorful.json
│   └── minimal.json

Chaque fichier de variation ne contient que les valeurs qu’il souhaite surcharger. Par exemple, dark-mode.json :

{
  "version": 3,
  "title": "Mode sombre",
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--neutral-dark)",
      "text": "var(--wp--preset--color--neutral-light)"
    },
    "blocks": {
      "core/button": {
        "color": {
          "background": "var(--wp--preset--color--secondary)"
        }
      }
    }
  }
}

L’utilisateur peut ensuite changer de variation directement depuis l’éditeur de site, dans Apparence → Éditeur → Styles. C’est donc un moyen très élégant de proposer plusieurs looks sans dupliquer l’intégralité du thème. Et pour les développeurs qui vendent des thèmes premium, c’est un argument de vente non négligeable.

Créer les templates et patterns de blocs

Maintenant qu’on a configuré theme.json, il faut donner vie au thème avec les templates et les patterns. C’est ici que le FSE révèle toute sa logique : fini les fichiers PHP bourrés de get_header() et the_loop(). On travaille désormais avec du markup de blocs WordPress — des fichiers .html contenant des commentaires HTML du type . Déroutant au début, mais très cohérent une fois qu’on comprend la mécanique.

Construire le template index.html et les templates spécialisés

Le fichier index.html est le point d’entrée obligatoire de votre thème FSE. Il doit se trouver dans le dossier /templates/. Sa structure est simple : on y assemble des block comments pour inclure les parts (header, footer) et définir le contenu central.

Voici un exemple minimal mais fonctionnel :

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">

  <!-- wp:query {"queryId":0,"query":{"perPage":10,"offset":0,"postType":"post","order":"desc","orderBy":"date","author":"","search":"","exclude":[],"sticky":"","inherit":true}} -->
  <div class="wp-block-query">

    <!-- wp:post-template -->
      <!-- wp:post-title {"isLink":true} /-->
      <!-- wp:post-excerpt /-->
      <!-- wp:post-date /-->
    <!-- /wp:post-template -->

    <!-- wp:query-pagination -->
      <!-- wp:query-pagination-previous /-->
      <!-- wp:query-pagination-numbers /-->
      <!-- wp:query-pagination-next /-->
    <!-- /wp:query-pagination -->

  </div>
  <!-- /wp:query -->

</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Le bloc core/query avec "inherit":true est la clé : il récupère automatiquement le contexte de la requête en cours (archive, recherche, etc.). Pas besoin de le configurer manuellement selon la page.

Les templates prioritaires à créer en 2026 :

index.html — obligatoire, fallback universel
single.html — articles de blog
page.html — pages statiques
archive.html — archives, catégories, étiquettes
404.html — page d’erreur (à ne pas négliger !)
search.html — résultats de recherche

La hiérarchie des templates FSE suit exactement la hiérarchie de templates WordPress classique. Si single-product.html existe, WordPress le charge pour les CPT « product ». Sinon, il remonte dans la hiérarchie jusqu’à single.html, puis index.html. Même logique qu’avant, mais en .html avec des blocs. Et WordPress cherche d’abord dans la base de données (templates personnalisés via l’éditeur) avant de lire vos fichiers — c’est important à savoir pour le debug.

Pour les template parts (header, footer, sidebar), créez-les dans /parts/ et déclarez-les dans theme.json sous la clé templateParts :

"templateParts": [
  { "name": "header", "title": "En-tête", "area": "header" },
  { "name": "footer", "title": "Pied de page", "area": "footer" }
]

Concevoir des patterns réutilisables avec le dossier /patterns

Les Block Patterns, c’est un peu la fonctionnalité qui change vraiment le workflow. On définit des compositions de blocs réutilisables — une section hero, une grille de cards, un CTA — que l’éditeur peut insérer en un clic. Et bonne nouvelle : en 2026, plus besoin d’appeler register_block_pattern() dans functions.php. WordPress enregistre automatiquement tous les fichiers .php présents dans le dossier /patterns/ de votre thème.

La structure d’un fichier pattern est simple : un header en commentaire PHP, puis le markup de blocs.

Voici un exemple concret — une section hero avec titre, sous-titre et bouton :

<?php
/**
 * Title: Section Hero
 * Slug: montheme/hero-section
 * Categories: featured, banner
 * Block Types: core/cover
 * Viewport Width: 1280
 */
?>
<!-- wp:cover {"url":"","dimRatio":50,"style":{"spacing":{"padding":{"top":"var(--wp--preset--spacing--80)","bottom":"var(--wp--preset--spacing--80)"}}}} -->
<div class="wp-block-cover">
  <div class="wp-block-cover__inner-container">

    <!-- wp:heading {"textAlign":"center","level":1} -->
    <h1 class="wp-block-heading has-text-align-center">Bienvenue sur mon site</h1>
    <!-- /wp:heading -->

    <!-- wp:paragraph {"align":"center"} -->
    <p class="has-text-align-center">Une accroche claire et percutante pour capter l'attention.</p>
    <!-- /wp:paragraph -->

    <!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
    <div class="wp-block-buttons">
      <!-- wp:button {"backgroundColor":"primary"} -->
      <div class="wp-block-button">
        <a class="wp-block-button__link has-primary-background-color has-background wp-element-button">Découvrir</a>
      </div>
      <!-- /wp:button -->
    </div>
    <!-- /wp:buttons -->

  </div>
</div>
<!-- /wp:cover -->

Quelques précisions sur les headers du fichier PHP :

Title : le nom affiché dans l’éditeur (obligatoire)
Slug : identifiant unique au format nom-theme/nom-pattern (obligatoire)
Categories : catégories de l’inserteur de patterns (featured, text, gallery, call-to-action, etc.)
Block Types : associe le pattern à un type de bloc spécifique — il s’affichera alors comme suggestion quand l’utilisateur insère ce bloc
Viewport Width : largeur de l’aperçu dans l’inserteur (en pixels)

Bon, une dernière chose pratique : si vous voulez qu’un pattern soit non modifiable par l’utilisateur (synced pattern géré en code), vous pouvez ajouter Inserter: false pour le masquer de l’interface tout en le gardant utilisable via le code. Utile pour les patterns internes à votre thème.

Tester, optimiser et distribuer son thème FSE

On a vu comment construire son thème de A à Z : theme.json, templates, patterns… Maintenant, il faut s’assurer que tout fonctionne correctement avant de le partager. Et croyez-moi, cette étape est souvent sous-estimée.

Outils et bonnes pratiques pour déboguer theme.json

Pour développer un thème FSE dans de bonnes conditions en 2026, quelques outils sont vraiment indispensables.

L’environnement local d’abord. On recommande wp-env (l’outil officiel de l’équipe Gutenberg) ou LocalWP si vous préférez une interface graphique. Les deux font très bien le boulot, mais wp-env s’intègre mieux dans un workflow Docker si vous êtes à l’aise avec la ligne de commande.

Le plugin Create Block Theme est votre meilleur ami pour les thèmes FSE. Il permet de :

Scaffolder un thème FSE complet en quelques clics
Exporter votre thème après modifications dans l’éditeur visuel (pratique pour récupérer les changements de styles faits « à la souris »)
Synchroniser les modifications entre l’éditeur et vos fichiers sources

Et pour valider que votre thème respecte les standards WordPress, Theme Check reste la référence. Il analyse automatiquement les fichiers, détecte les fonctions dépréciées ou les éléments manquants.

Pour déboguer theme.json concrètement :

Activez WP_DEBUG dans votre wp-config.php — les erreurs silencieuses deviennent visibles
Ouvrez les DevTools de votre navigateur et inspectez les custom properties CSS générées par WordPress (elles commencent toutes par --wp--preset-- ou --wp--custom--). C’est le moyen le plus rapide de vérifier que vos presets sont bien appliqués
Dans l’éditeur Gutenberg, l’inspecteur de blocs affiche la hiérarchie des styles appliqués : styles globaux → styles de bloc → styles inline. Très utile pour comprendre pourquoi un style ne s’applique pas comme prévu

Une bonne pratique de performance à ne pas négliger : chaque preset déclaré dans theme.json génère du CSS, même si vous ne l’utilisez jamais. Déclarez 40 nuances de couleurs dont vous n’utilisez que 6 ? WordPress génère quand même les 40 custom properties et les classes utilitaires associées. Donc : ne déclarez que ce dont vous avez réellement besoin. Préférez aussi les styles inline (via theme.json) aux feuilles de style séparées quand c’est possible — ça réduit les requêtes HTTP et simplifie la maintenance.

Soumettre son thème sur WordPress.org ou le vendre

Une fois votre thème testé et peaufiné, deux grandes options s’offrent à vous : la distribution gratuite via WordPress.org, ou la vente sur des plateformes dédiées.

Pour WordPress.org, le processus passe par la Theme Review. Les critères sont stricts, mais bien documentés. Pour les thèmes FSE, quelques points importants :

Un fichier readme.txt est obligatoire (version testée, auteur, licence GPL)
Un screenshot.png aux dimensions exactes 1200x900px est requis — c’est la miniature affichée dans le répertoire
Le thème doit respecter les standards d’accessibilité de base
Tous les textes doivent être traduits (fonctions __() et _e(), ou équivalents)

La review prend du temps (parfois plusieurs semaines), mais la visibilité offerte par le répertoire officiel est imbattable. C’est gratuit, et votre thème peut être installé directement depuis l’admin WordPress.

Pour la vente, ThemeForest reste la plateforme la plus connue, avec une audience énorme mais une concurrence féroce. Gumroad est une alternative plus simple à mettre en place si vous voulez vendre en direct, avec moins d’intermédiaires et plus de contrôle sur votre pricing.

Bon, voilà : développer et distribuer un thème FSE en 2026, c’est exigeant mais vraiment accessible. Le Full Site Editing a énormément mûri, theme.json v3 offre une flexibilité impressionnante, et les outils autour de l’écosystème Gutenberg n’ont jamais été aussi bons. Lancez-vous, testez, itérez — et n’hésitez pas à soumettre votre thème à la communauté. C’est comme ça qu’on progresse !