WP Block Themes

When to use

Use this skill for block theme work such as:

• Editing theme.json (presets, settings, styles, per-block styles)
• Adding or changing templates (templates/*.html) and template parts (parts/*.html)
• Adding patterns (patterns/*.php) and controlling inserter visibility
• Adding style variations (styles/*.json)
• Debugging "styles not applying" / "editor doesn't reflect theme.json"

Inputs required

• Repo root and which theme is targeted
• Target WordPress version range (theme.json version varies by core version)
• Where the issue manifests: Site Editor, post editor, frontend, or all

Procedure

1) Verify block theme structure

Required structure:

theme-name/
├── style.css          # Theme header (required)
├── theme.json         # Global settings and styles (required)
├── templates/         # Full page templates
│   ├── index.html     # Fallback template (required)
│   ├── single.html
│   ├── archive.html
│   └── ...
├── parts/             # Template parts
│   ├── header.html
│   ├── footer.html
│   └── ...
├── patterns/          # Block patterns (optional)
│   └── *.php
└── styles/            # Style variations (optional)
    └── *.json

2) theme.json structure

Settings (what the UI allows):

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "primary", "color": "#0073aa", "name": "Primary" }
      ]
    },
    "typography": {
      "fontSizes": [
        { "slug": "small", "size": "14px", "name": "Small" }
      ]
    },
    "layout": {
      "contentSize": "800px",
      "wideSize": "1200px"
    }
  }
}

Styles (how it looks by default):

{
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--base)",
      "text": "var(--wp--preset--color--contrast)"
    },
    "elements": {
      "link": {
        "color": { "text": "var(--wp--preset--color--primary)" }
      }
    },
    "blocks": {
      "core/button": {
        "color": {
          "background": "var(--wp--preset--color--primary)"
        }
      }
    }
  }
}

3) Templates and template parts

Templates (templates/*.html):

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

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

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

Template parts (parts/*.html):

• Must NOT be nested in subdirectories
• Must have matching slug in template-part block

4) Patterns

Create patterns in patterns/*.php:

<?php
/**
 * Title: Hero Section
 * Slug: theme-name/hero
 * Categories: featured
 * Keywords: hero, banner
 */
?>
<!-- wp:cover {"url":"..."} -->
...
<!-- /wp:cover -->

5) Style variations

Create variations in styles/*.json:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "title": "Dark Mode",
  "settings": {},
  "styles": {
    "color": {
      "background": "#1a1a1a",
      "text": "#ffffff"
    }
  }
}

6) Style hierarchy (debugging)

Styles apply in this order (later overrides earlier):

1. Core defaults
2. theme.json (parent theme)
3. theme.json (child theme)
4. User customizations (stored in DB)

If your theme.json changes don't appear:

• Check if user customizations override them
• Clear any caches
• Validate JSON syntax

Verification

• Site Editor reflects changes (Styles UI, templates, patterns)
• Frontend renders with expected styles
• If styles aren't changing, confirm user customizations don't override

Failure modes / debugging

Common issues:

• Wrong theme root: Editing inactive theme
• User overrides: Customizations in DB override theme.json
• Invalid JSON: Typos prevent application
• Wrong folder: Templates/parts in wrong location or nested

Debug commands:

# Validate theme.json
cat theme.json | python3 -m json.tool

# Check template files
ls -la templates/ parts/

# Verify theme is active
wp theme list --status=active

Escalation

Consult canonical docs:

• Theme Handbook - Block Themes
• theme.json Reference