WordPress Block Themes from First Principles

For most of its history, a WordPress theme was a pile of PHP files that took a request, queried the database, and printed HTML. If you wanted to change the layout, you edited a template. If you wanted to change a colour, you edited a stylesheet and hoped nothing else depended on it. Block themes rearrange this entire model, and the change is more profound than the marketing suggests. To use them well, it helps to understand them from the ground up rather than by analogy to what came before.

Three ideas, stacked

A block theme rests on three ideas that fit together like layers. Each is simple; the power comes from the combination.

• Blocks are the atomic units of content — a paragraph, a heading, an image — each one a small, self-describing object.
• Templates are arrangements of blocks written in HTML, with no PHP required, that describe whole pages.
• theme.json is a single configuration file that defines the design system every block inherits.

The old theme answered the question “how do I render this page?” with code. The block theme answers it with data. That shift — from imperative templates to declarative configuration — is the whole story.

The old theme rendered pages with code. The block theme describes them with data.

Why theme.json changes everything

In a classic theme, design values were scattered: a hex code in the stylesheet, a font size in a template, a width hard-coded in three different places. theme.json gathers all of it into one declarative document and then generates the CSS for you. Define a colour once and it appears in the editor palette, applies to the front end, and stays consistent everywhere.

{
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "primary", "color": "#78716C", "name": "Primary" }
      ]
    },
    "layout": { "contentSize": "680px", "wideSize": "1200px" }
  }
}

That small block does a surprising amount of work. It registers a colour the user can pick in the editor, exposes a CSS custom property named --wp--preset--color--primary, and sets the two layout widths every block will align to. You are not writing styles; you are declaring intentions, and WordPress translates them into a consistent system.

Templates without PHP

A block template is just block markup saved as an HTML file. A minimal index template references two template parts and a loop, and contains no logic at all.

<!-- wp:template-part {"slug":"header"} /-->
<!-- wp:query -->
  <!-- wp:post-template -->
    <!-- wp:post-title {"isLink":true} /-->
    <!-- wp:post-excerpt /-->
  <!-- /wp:post-template -->
<!-- /wp:query -->
<!-- wp:template-part {"slug":"footer"} /-->

What used to require the_loop(), conditional tags, and a tangle of template hierarchy logic is now a readable outline. The Query Loop block inherits the main query automatically, so the same template serves the home page, an archive, or a search result without a line of PHP.

The template hierarchy did not disappear. It simply moved from a set of file-naming conventions into a set of HTML files you can read top to bottom.

On the new mental model

Where PHP still belongs

Block themes do not abolish functions.php; they shrink its job. A healthy block theme keeps PHP for a handful of tasks and resists the temptation to do more.

1. Registering pattern categories and enqueuing the stylesheet.
2. Declaring theme support for editor features.
3. Adding resource hints such as font preloads.

Anything beyond presentation — custom post types, SEO output, form handling — belongs in a plugin. This is not bureaucracy. It is the line that keeps a theme switchable: a user should be able to change themes without losing their content or their functionality.

One token, many effects

To feel why the declarative model matters, follow a single value through the system. Suppose you define a spacing scale in theme.json and add one step to it. In a classic theme, a new spacing value would touch nothing until you wrote CSS to use it. In a block theme, that one declaration immediately becomes a choice in every block’s spacing controls, a CSS custom property available to your templates, and a consistent rhythm applied wherever a user selects it. You changed one line of data; the system propagated it everywhere it could possibly be relevant.

This is the quiet superpower of design tokens. They turn a thousand scattered decisions into a handful of named ones. A colour is no longer a hex code copied into forty files; it is a slug — primary, surface, text-secondary — with a single source of truth. When the brand shifts, you edit the definition, not the forty copies. The editor, the front end, and any future style variation all update together because they were never really separate to begin with.

Patterns and the inserter

If templates describe whole pages, patterns describe the reusable pieces in between — a hero section, a call to action, a three-column grid of recent posts. A pattern is simply block markup with a header comment, dropped into the theme’s patterns directory, and WordPress registers it automatically. Once registered, it appears in the inserter, ready for a user to drop in and edit. Crucially, a pattern is a starting point, not a locked component: the user owns the result and can change anything.

This is a genuinely different contract from the page-builder era, where layouts were often trapped inside proprietary shortcodes that broke the moment you switched themes. Patterns are plain blocks. Disable the theme and the content remains valid, editable markup. The theme contributed a head start; it did not take the content hostage. That distinction is the difference between a tool that serves the user and one that captures them.

Migrating an old theme, realistically

Teams with a large classic theme often ask whether they should convert it. The honest answer is: rarely all at once. WordPress supports hybrid themes, where a classic theme adopts block features incrementally — a theme.json here, a block template part there. This lets you migrate the way you should migrate anything large: in slices, with the site working at every step.

1. Add a theme.json and move your colours and font sizes into it. Nothing breaks; the presets simply become available.
2. Convert the header and footer to block template parts, so editors can manage them without code.
3. Replace individual PHP templates with block templates one at a time, starting with the simplest.
4. Only when the pieces are proven do you flip the switch to a full block theme.

The mistake is treating the move as a single dramatic rewrite. The block system was designed to be adopted gradually, and the gradual path is almost always the wiser one.

Common mistakes to avoid

The most frequent error is reaching for PHP out of habit when theme.json or a block would do the job declaratively. The second is over-styling style.css until it fights the design system you so carefully defined. The third is bundling functionality — custom post types, SEO, analytics — into the theme, which quietly breaks the promise that a user can switch themes safely. Each of these is a reversion to old instincts, and each undoes part of what makes block themes worth using.

Style variations, almost for free

One of the quietly remarkable features of the block model is the style variation. A variation is a small JSON file in the theme’s styles directory that overrides parts of theme.json — most often the colour palette. Because every block already reads its colours from named tokens rather than hard-coded values, a single variation file can re-theme an entire site without touching a single template or stylesheet. A light theme and a dark theme become two small files describing the same structure in different colours.

This is only possible because of the discipline imposed earlier. If you had scattered hex codes through your templates, a dark mode would mean hunting them all down. Because you instead declared background, text-primary, and the rest as tokens, the variation simply redefines what those tokens mean. The lesson generalises: the constraints of the declarative model are not a cage but a foundation. The work you do to define a system cleanly is what later lets you transform it cheaply.

The Site Editor as the source of truth

The final shift block themes ask of us is conceptual. In the classic model, the files on disk were the truth, and the database merely held content. In the block model, the Site Editor lets users change templates, parts, and global styles, and those changes are stored in the database, layered on top of the theme’s files. The theme provides defaults; the user’s edits override them. This is powerful and occasionally confusing, because the page a visitor sees is now a merge of what the developer shipped and what the user changed.

The practical consequence is that a theme is no longer a finished artefact but a well-considered starting point. Your job as a theme author is to ship sensible defaults and a coherent system, then hand genuine authority to the user. Some developers find this loss of total control unsettling. But it is precisely the point: the block model was designed to give ordinary users the kind of power that once required a developer, and a good block theme is one that makes that power feel safe to wield.

---

The learning curve, honestly

None of this is free. The block model asks you to learn block markup, to think in design tokens, and to give up some of the fine control that raw PHP afforded. For a developer fluent in the old way, the first week feels like working with mittens on. Then something clicks: you realise you are describing a system rather than hand-building pages, and that the system will keep paying you back every time you reuse a pattern or adjust a token.

Start small. Build a theme with one template, one part, and a handful of colours. Watch how a single change in theme.json ripples through the editor and the page at once. Once you have felt that, the rest of the model stops being abstract and starts being obvious. First principles are not a detour here; they are the shortest path to using block themes with confidence.

Seen from far enough back, block themes are part of a long arc in software: the slow movement from imperative instructions toward declarative description, from telling the machine each step to telling it what we want. That arc has played out in everything from infrastructure to user interfaces, and it tends to feel like a loss of control before it reveals itself as a gain in leverage. WordPress is simply walking the same path, carrying its enormous community along with it. The reward at the end is a system where content, design, and structure each live in the place best suited to them — content in the editor, design in tokens, structure in readable templates — and where a small change in the right file ripples outward to exactly the places it should. Learn the model on its own terms, resist the urge to drag old habits into it, and it stops feeling like a constraint and starts feeling like what it is: a more honest way to describe a website.