wp-block-themes

Use when developing WordPress block themes: theme.json (global settings/styles), templates and template parts, patterns, style variations, and Site Editor troubleshooting (style hierarchy, overrides, caching).

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 2, 2026

When & Why to Use This Skill

This Claude skill streamlines the development of modern WordPress block themes by automating the creation and management of theme.json files, HTML templates, and PHP patterns. It ensures adherence to WordPress 6.9+ standards, simplifies style hierarchy debugging, and facilitates the implementation of global settings and style variations for Full Site Editing (FSE).

Use Cases

  • Configuring global styles, color palettes, and typography presets within the theme.json framework to ensure site-wide consistency.
  • Building and organizing block-based templates and template parts (e.g., headers, footers) for custom page layouts.
  • Developing reusable block patterns and style variations to provide flexible design options within the WordPress Site Editor.
  • Troubleshooting and resolving style conflicts between theme.json settings, user customizations, and core CSS defaults.
  • Automating the structural setup of new WordPress block themes, including required file hierarchies and JSON schema validation.
namewp-block-themes
description"Use when developing WordPress block themes: theme.json (global settings/styles), templates and template parts, patterns, style variations, and Site Editor troubleshooting (style hierarchy, overrides, caching)."
compatibility"Targets WordPress 6.9+ (PHP 8.0+). Filesystem-based agent with bash + node."

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: