WordPress Theme Development with the Block Editor

Classic WordPress themes are PHP templates with hardcoded layouts. Clients cannot edit the structure without touching code. Block themes change this: the client can move, resize, and rearrange sections from the WP admin. Here is how I build a block theme from scratch.

Why Block Themes

The goal is client self-sufficiency. A block theme lets them change the homepage hero, add a testimonial section, or tweak the footer without filing a support ticket. That autonomy is what clients actually want from a CMS.

The Minimum Viable Block Theme

A block theme needs four files:

• style.css (theme metadata)
• theme.json (design tokens and global settings)
• templates/index.html (homepage template)
• parts/header.html and parts/footer.html (reusable sections)

That is it. No PHP required. The theme is pure HTML and JSON.

theme.json Is the Heart

theme.json defines typography, colors, spacing, and which blocks the editor can use:

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {"slug": "primary", "color": "#0ea5e9", "name": "Primary"}
      ]
    },
    "typography": {
      "fontSizes": [
        {"slug": "large", "size": "24px", "name": "Large"}
      ]
    }
  }
}

Clients see these colors and sizes in the editor. They cannot invent off-brand colors because the palette is fixed by the theme.

Template Parts Are Reusable

Header and footer live in parts/. They get included in every template:

<!-- templates/index.html -->
<!-- wp:template-part {"slug":"header","tagName":"header"} /-->
<!-- wp:post-content /-->
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

Those HTML comments are block serialization. The editor understands them and renders the parts as editable regions.

Constrain the Options

Clients get overwhelmed when given every possible block. I disable blocks they do not need in theme.json:

"blocks": {
  "core/table": {"supports": false},
  "core/code": {"supports": false}
}

Fewer choices, cleaner sites. The client can still do what they need, not more.

Where AI Helps

I describe the desired theme structure to Claude Code and it generates the starting theme.json and templates. I then customize them for the client's brand. What used to be a two-day theme setup is now a two-hour customization pass.

Handoff to the Client

I record a five-minute video showing them how to edit the homepage, change colors, and add a new page. That video is usually all they need. The block editor is familiar enough to most users that deep training is not required.

See the WordPress block theme documentation for the full spec and available patterns.