Block Themes (FSE)

<?php
// ===== What block themes are =====
// Theme architecture introduced in WordPress 5.9+ and matured through 6.x.
// Templates are HTML (not PHP), driven by blocks.
// Site editor lets non-engineers edit headers, footers, archives, single posts.
// theme.json centralises styling tokens (colours, fonts, spacing, layout).

// ===== Minimum block theme =====
// my-block-theme/
//   style.css           (theme header still required)
//   theme.json          (global styles + settings)
//   templates/
//     index.html        (the only required template)
//     single.html
//     archive.html
//     404.html
//   parts/
//     header.html
//     footer.html
//   functions.php       (optional)

// ===== style.css header =====
/*
Theme Name: My Block Theme
Version: 1.0.0
*/

// ===== theme.json (the centrepiece) =====
{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "layout": { "contentSize": "720px", "wideSize": "1200px" },
    "color": {
      "palette": [
        { "slug": "primary", "color": "#2563eb", "name": "Primary" },
        { "slug": "background", "color": "#ffffff", "name": "Background" }
      ]
    },
    "typography": {
      "fontFamilies": [
        { "slug": "sans", "name": "Sans", "fontFamily": "Inter, system-ui, sans-serif" }
      ],
      "fontSizes": [
        { "slug": "sm", "size": "14px", "name": "Small" },
        { "slug": "md", "size": "16px", "name": "Medium" }
      ]
    },
    "spacing": {
      "units": ["px", "rem", "em"],
      "spacingScale": { "steps": 8 }
    }
  },
  "styles": {
    "color": { "background": "var(--wp--preset--color--background)" },
    "typography": { "fontFamily": "var(--wp--preset--font-family--sans)" }
  }
}

// ===== templates/index.html =====
<!-- wp:template-part {"slug":"header","theme":"my-block-theme"} /-->

<!-- wp:group {"layout":{"type":"constrained"}} -->
<main class="wp-block-group">
  <!-- wp:post-title /-->
  <!-- wp:post-content /-->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","theme":"my-block-theme"} /-->

// ===== parts/header.html =====
<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} -->
<header class="wp-block-group">
  <!-- wp:site-title /-->
  <!-- wp:navigation /-->
</header>
<!-- /wp:group -->

// ===== Editor experience =====
// Appearance -> Editor (full-site editor).
// Drag blocks; save; the HTML template files are updated.
// No PHP to edit for layout changes.

// ===== Classic theme + block theme coexistence =====
// You can ship a classic PHP theme but use block templates for new pages — hybrid mode.
// New sites in 2026: lean block themes.

// ===== Custom blocks =====
// Use @wordpress/create-block or wp-cli scaffolding.
// Blocks are React components registered via JS + a PHP companion file.

// ===== Patterns to internalise =====
// - theme.json as the single source of design truth
// - Template parts for header/footer/sidebars
// - Custom blocks for repeating layout patterns
// - Child themes still apply; block theme children override parent templates

// ===== Pitfalls =====
// - Mixing classic PHP templates with block templates inconsistently
// - Heavy CSS overrides that fight theme.json defaults
// - Plugins assuming classic templates (e.g. custom widgets) -> use block alternatives
// - theme.json schema drift between WP versions; pin the $schema URL or test

// FSE (Full Site Editing). theme.json + block templates in /templates and /parts.