Full Site Editing (FSE) in WordPress: The Block Theme Revolution of 2026

Full Site Editing shipped in WordPress 5.9 back in 2022, and the reaction from the theme development community was a mix of excitement and scepticism. Four years later, the dust has settled enough to separate what works from what was wishful thinking. Block themes in 2026 are genuinely capable — but they demand a fundamentally different architecture mindset than classic PHP themes.

This guide is for theme authors and WordPress developers who need to understand the current state of block theme development: what the template hierarchy looks like now, how theme.json has become the central design system file, where block themes outperform classic themes, and where they still fall short. If you are maintaining a classic theme and evaluating migration, or starting a new theme project, this is the decision framework you need.

What Changed Between 2022 and 2026

The initial FSE release was rough. Template editing was buggy, theme.json was limited, and the gap between what the block editor could do and what production themes required was substantial. Here is what has materially changed:

theme.json v3 is a real design system. The expanded schema covers typography presets, spacing scales, colour palettes with semantic naming, shadow tokens, border tokens, and layout constraints. It is now possible to encode a complete design system in theme.json without writing a line of CSS for token definitions.

Template parts are composable. Header, footer, sidebar, and custom template parts can be mixed and matched in the Site Editor with drag-and-drop. The template part system now supports conditional loading, so a page template can specify which header variant to use.

Block patterns have replaced widget areas. The pattern library is the primary content composition tool. Well-designed patterns give content editors the building blocks to create pages without touching theme code. Patterns are registered in PHP and can include any combination of core and custom blocks.

Global styles are per-block configurable. Each block type can have default styles, and users can override them globally or per-instance. Theme authors set the defaults in theme.json; users adjust through the Global Styles panel.

Custom template hierarchy is stable. Block themes follow the same template hierarchy as classic themes — single-{post-type}.html, archive-{taxonomy}.html, page-{slug}.html — but templates are HTML files containing block markup instead of PHP files with template tags.

Architecture: Block Theme vs Classic Theme

The WordPress theme structure guide covers classic theme architecture in depth. Block themes depart from that model significantly:

| Classic Theme | Block Theme | |---|---| | PHP template files with get_header(), the_content(), loops | HTML templates with block markup | | style.css + additional stylesheets | theme.json + minimal style.css | | functions.php for everything | functions.php for registration only; theme.json for design | | Widget areas | Block-based template parts + patterns | | Customizer settings | Global Styles panel | | Enqueued scripts/styles | Block editor handles most styling |

The philosophical shift: in a classic theme, the developer controls the output. In a block theme, the developer defines the constraints and the content editor composes within them.

theme.json as Your Design System

The theme.json file in 2026 is the most important file in a block theme. It defines:

Typography

{
  "settings": {
    "typography": {
      "fontFamilies": [
        {
          "fontFamily": "\"Instrument Serif\", serif",
          "slug": "heading",
          "name": "Heading",
          "fontFace": [
            {
              "fontFamily": "Instrument Serif",
              "fontWeight": "400",
              "fontStyle": "normal",
              "src": ["file:./assets/fonts/InstrumentSerif-Regular.woff2"]
            }
          ]
        }
      ],
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" },
        { "slug": "medium", "size": "1rem", "name": "Medium" },
        { "slug": "large", "size": "1.25rem", "name": "Large" },
        { "slug": "x-large", "size": "1.75rem", "name": "Extra Large" }
      ]
    }
  }
}

These tokens generate CSS custom properties that the block editor and the front end both use. One source of truth for the entire typographic system. The typography and readability guide covers the type scale decisions; theme.json is where you encode them.

Spacing and Layout

{
  "settings": {
    "spacing": {
      "spacingSizes": [
        { "slug": "10", "size": "0.25rem", "name": "2XS" },
        { "slug": "20", "size": "0.5rem", "name": "XS" },
        { "slug": "30", "size": "0.75rem", "name": "S" },
        { "slug": "40", "size": "1rem", "name": "M" },
        { "slug": "50", "size": "1.5rem", "name": "L" },
        { "slug": "60", "size": "2.5rem", "name": "XL" }
      ],
      "units": ["rem", "%"]
    },
    "layout": {
      "contentSize": "42rem",
      "wideSize": "72rem"
    }
  }
}

The contentSize and wideSize define the maximum widths for content and wide-aligned elements. These propagate through every block that uses the default layout system, creating consistent content widths without per-block CSS.

Template Architecture

Block theme templates live in the /templates/ directory. A minimal blog theme needs:

templates/
├── index.html          # Fallback for everything
├── single.html         # Individual posts
├── page.html           # Individual pages
├── archive.html        # Post archives
├── 404.html            # Not found
└── search.html         # Search results

parts/
├── header.html         # Site header
├── footer.html         # Site footer
└── sidebar.html        # Optional sidebar

Each template is HTML with block markup. A simplified single.html:

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

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
  <!-- wp:post-title {"level":1} /-->
  <!-- wp:post-featured-image /-->
  <!-- wp:post-content {"layout":{"type":"constrained"}} /-->
</div>
<!-- /wp:group -->

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

This is declarative. The template says what to include and how to lay it out. The block editor handles rendering. The user can customise this template through the Site Editor without editing files.

Block Patterns: The Content Composition Layer

Patterns are the most underappreciated part of block theme architecture. A well-designed pattern library is what makes a block theme genuinely useful for content editors.

Register patterns in your theme:

register_block_pattern('mytheme/hero-with-overlay', [
    'title'       => 'Hero with Text Overlay',
    'description' => 'Full-width hero image with centred heading and subtitle',
    'categories'  => ['featured'],
    'content'     => '<!-- wp:cover {"dimRatio":50} -->...',
]);

The pattern provides the structure. The editor fills in the content. This is fundamentally different from classic theme page templates where the developer hardcoded the layout and the editor could only change text within it.

What Breaks in Block Themes

Complex conditional layouts. Classic themes can use PHP logic to show different layouts based on post meta, user roles, or query parameters. Block themes handle this through template hierarchy (different templates for different content types) but lack the granular conditional logic that PHP provides.

Third-party plugin compatibility. Plugins that output shortcodes or custom markup may not integrate smoothly with block themes. The block ecosystem is improving, but some plugins still assume classic theme functions like the_content() filters or widget areas.

Performance in the editor. The block editor with a complex page (50+ blocks, nested groups, multiple patterns) can become sluggish. Front-end performance is fine because the output is static HTML. Editor performance is the current bottleneck.

Developer workflow. Editing HTML templates with block markup in a code editor is not as ergonomic as editing PHP templates. The block markup is verbose and nesting is difficult to read. Most block theme developers use the Site Editor to compose templates and export the HTML, rather than hand-writing block markup.

When to Choose Block Theme vs Classic Theme

Choose a block theme when:

• Content editors need layout flexibility without developer intervention
• The design system can be expressed through theme.json tokens
• The site primarily uses core blocks and well-supported custom blocks
• You want users to customise through the WordPress UI, not code

Choose a classic theme when:

• Complex conditional rendering is required (e-commerce, membership sites)
• Performance-critical applications where editor overhead matters
• Heavy custom functionality that integrates at the template level
• The team is more productive in PHP than in block markup

Checklist

• [ ] theme.json defines complete typography, colour, and spacing token system
• [ ] Templates use constrained layout for content width consistency
• [ ] Template parts registered for header, footer, and reusable sections
• [ ] Block patterns provided for common page compositions
• [ ] Font files self-hosted and declared in theme.json fontFace
• [ ] Global styles defaults set for all core blocks used in the theme
• [ ] style.css contains only styles that theme.json cannot express
• [ ] Template hierarchy follows standard WordPress conventions
• [ ] Editor performance tested with 50+ block pages
• [ ] Front-end output validated for semantic HTML structure

FAQ

Can I use both classic and block approaches in one theme? Technically yes — hybrid themes exist. But they create maintenance complexity and confuse content editors. Pick one approach and commit to it.

How do I handle custom post types in block themes? Create specific templates: single-{post-type}.html and archive-{post-type}.html. Register custom block patterns for the post type's content structure. Custom fields can be exposed through custom blocks.

Is Full Site Editing ready for client projects? For content-focused sites (blogs, portfolios, small business sites), yes. For complex applications (e-commerce with custom checkout, membership sites with gated content), evaluate carefully — classic themes may still be more practical.

Next Steps

• Review the WordPress theme structure guide for classic theme architecture comparison
• Check the typography and readability guide for type scale decisions that map to theme.json tokens
• Read the container queries guide for responsive component patterns that complement block layouts
• Browse all guides for more front-end implementation patterns