Building a Block Theme in 2025

August 18, 2025
WordPress logo on a light, abstract background with an angled stack of theme snapshots and the title “Building a Block Theme in 2025.”

If you’re building a block theme in 2025, good news: the platform does more of the heavy lifting than ever. With theme.json handling design tokens and block settings, templates written as block markup, and helpful tools to export your work, you can move fast and still keep things clean.

Related reads: Emmet Tips & Tricks for Beginners, 10 Must-Use HTML Tags in 2025, and Exploring New CSS Features in 2025.

What we’ll build (quick overview)

Prereqs & versions

1) Start your theme folder

Create /wp-content/themes/my-block-theme/ with:

my-block-theme/
├─ style.css
├─ theme.json
├─ templates/
│  └─ index.html
├─ parts/
│  ├─ header.html
│  └─ footer.html
└─ patterns/
   └─ hero.php

style.css (header only)

/*
 Theme Name: My Block Theme
 Description: Clean, modern block theme.
 Requires at least: 6.6
 Version: 1.0.0
*/

2) Add a modern theme.json (v3)

Here’s a compact starter you can expand later:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "appearanceTools": true,
    "color": {
      "palette": [
        { "name": "Ink", "slug": "ink", "color": "#111827" },
        { "name": "Sky", "slug": "sky", "color": "#38bdf8" },
        { "name": "Peach", "slug": "peach", "color": "#fb923c" }
      ]
    },
    "typography": {
      "fontFamilies": [
        { "fontFamily": "Inter, system-ui, sans-serif", "slug": "inter", "name": "Inter" }
      ],
      "fluid": true
    },
    "spacing": { "units": [ "px", "rem", "%" ] }
  },
  "styles": {
    "typography": { "fontFamily": "var(--wp--preset--font-family--inter)", "lineHeight": 1.6 },
    "elements": {
      "heading": { "typography": { "lineHeight": 1.2 } }
    }
  },
  "templateParts": [
    { "name": "header", "title": "Header", "area": "header" },
    { "name": "footer", "title": "Footer", "area": "footer" }
  ]
}

3) Templates & template parts

templates/index.html

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

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
  <!-- wp:query {"query":{"perPage":10}} -->
    <!-- wp:post-template -->
      <!-- wp:post-title {"isLink":true} /-->
      <!-- wp:post-excerpt /-->
      <!-- wp:separator /-->
    <!-- /wp:post-template -->
    <!-- wp:query-pagination /-->
  <!-- /wp:query -->
<!-- /wp:group -->

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

parts/header.html

<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} -->
  <!-- wp:site-title /-->
  <!-- wp:navigation /-->
<!-- /wp:group -->

parts/footer.html

<!-- wp:group {"layout":{"type":"constrained"}} -->
  <!-- wp:paragraph -->© <em>My Block Theme</em> — Built with the Site Editor.<!-- /wp:paragraph -->
<!-- /wp:group -->

4) Patterns (author reusable sections)

Create patterns/hero.php with the pattern header comment + block markup:

<?php
/**
 * Title: Hero with headline & CTA
 * Slug: my-block-theme/hero
 * Categories: featured
 */
?>
<!-- wp:group {"align":"wide","style":{"spacing":{"padding":{"top":"4rem","bottom":"4rem"}}}} -->
  <!-- wp:heading {"level":1} -->Design that ships fast.<!-- /wp:heading -->
  <!-- wp:paragraph -->A modern block theme starter.<!-- /wp:paragraph -->
  <!-- wp:buttons --><div class="wp-block-buttons">
    <!-- wp:button {"backgroundColor":"sky"} --><div class="wp-block-button">
      <a class="wp-block-button__link has-sky-background-color has-background">Get Started</a>
    </div><!-- /wp:button -->
  </div><!-- /wp:buttons -->
<!-- /wp:group -->

WordPress auto-registers patterns with this header when bundled in /patterns. (Exporting via the Create Block Theme plugin is also supported.) WordPress Developer Resources

5) Interactivity (tiny, no-framework behaviors)

The Interactivity API lets you add light client behavior to blocks without rolling your own framework. Great for toggles, tabs, and small UI touches. WordPress Developer Resources

HTML (in a pattern or template):

<div data-wp-interactive data-wp-context='{"open": false}'>
  <button data-wp-on--click="actions.toggle">Menu</button>
  <nav data-wp-bind--hidden="!state.open">…</nav>
</div>

JS (enqueue once in your theme):

import { store } from '@wordpress/interactivity';

store('my-theme', {
  state: { open: false },
  actions: {
    toggle: ({ state }) => { state.open = !state.open; }
  }
});

Docs + directives reference here. WordPress Developer Resources

6) Nice-to-have upgrades

7) Export & ship

Easiest path: install Create Block Theme, then Export your active theme as a ZIP from the admin. You can also clone, create a child theme, or start blank—right from the Site Editor. WordPress Developer ResourcesLearn WordPress

Copy-paste checklist

  • style.css header with min WP version
  • theme.json (v3) with palette, typography, spacing
  • /templates/index.html wired to /parts/header.html & /parts/footer.html
  • At least one pattern in /patterns
  • Optional: a tiny Interactivity API enhancement
  • Export ZIP via Create Block Theme

Leave a Reply

Your email address will not be published. Required fields are marked *