Block theme development: theme.json, templates, parts, patterns and style variations

A block theme is a WordPress theme built from blocks rather than PHP template files. Its templates are HTML files full of block markup, its design settings live in theme.json, and site owners can customize every template, header and footer in the Site Editor. Technically, WordPress needs only two files to recognize one: style.css and templates/index.html.

Building a good block theme is mostly about structure and restraint: define a clear design system in theme.json, keep templates thin by composing template parts and patterns, and give users choices through style variations instead of a sprawling options panel. The official Create Block Theme plugin lets you design visually in the Site Editor and export the result as clean theme files.

As of October 2026, WordPress 7.1.2 is current and Twenty Twenty-Five is still the newest bundled default theme (there is no Twenty Twenty-Six). This guide walks through the file structure, theme.json, templates, template parts, patterns and style variations, the tooling, and the practices that make a block theme maintainable.

The file structure of a block theme

The Theme Handbook's structure page lays out a typical block theme:

Larger themes add an assets folder (fonts, images, small scripts) and an inc folder for PHP classes. Keep business logic, custom post types and custom blocks in plugins; a theme should be safe to switch away from without losing content. If you are deciding between this model and a traditional PHP theme, see our guide to developing a custom WordPress theme from scratch.

theme.json: your design system

theme.json is the heart of a block theme. It has a version number, a settings object that controls what the editor offers (color palettes, font sizes, spacing scale, layout widths, which controls appear), and a styles object that applies design to the whole site, to HTML elements and to individual blocks. The current schema is version 3, documented in the theme.json version 3 reference; start every file with { "$schema": "https://schemas.wp.org/trunk/theme.json", "version": 3, "settings": { }, "styles": { } } so your editor validates it.

A few decisions shape the rest of the theme:

• Presets: define a small palette (with base and contrast slugs), a font size scale, a spacing scale and font families. Each preset becomes a CSS custom property such as --wp--preset--color--contrast that blocks and patterns reference.
• Layout: settings.layout.contentSize and wideSize set the default and wide widths used by constrained layouts.
• Fonts: declare fontFamilies with fontFace entries pointing to files in your theme, so WordPress loads them without extra PHP. Since 6.5, users can also manage fonts through the Font Library, and 7.0 added a dedicated font management page.
• Controls: turn off options you do not want users to touch (for example custom colors) to keep designs consistent.
• Template registration: the customTemplates and templateParts top-level keys give custom templates and parts human-readable titles, assign post types and set template part areas.

Our theme.json explained guide covers presets, the var:preset|color|contrast syntax and common mistakes in detail. WordPress 7.1 added responsive styling per screen size from Global Styles and block settings, along with configurable viewports, so check the 7.1 reference before writing breakpoint CSS by hand.

Templates: block markup for each page type

Templates follow the standard template hierarchy (index, home, front-page, single, page, archive, category, search, 404 and so on), but each is an HTML file of block markup. A minimal single.html might be: <!-- wp:template-part {"slug":"header","tagName":"header"} /--> then a main Group block containing Post Title, Post Featured Image and Post Content blocks, then <!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->.

Although the files are .html, the blocks inside are dynamic: Post Title, Query Loop and similar blocks read data from the database when the page renders. The handbook explains the other important behavior: when a user edits a template in the Site Editor, the change is saved to the database and overrides the file in your theme. That is why theme updates do not appear on templates a client has customized, and why "Clear customizations" (or Create Block Theme's save-to-theme feature) matters in development.

The practical way to write templates is to build them in the Site Editor, switch to the Code editor view and copy the block markup into the theme file, or let Create Block Theme do the copying.

Template parts

Template parts are reusable sections stored in /parts and included with the Template Part block. Each file must sit directly in the parts folder (subfolders are not supported). By default users can assign parts to the General (uncategorized), Header and Footer areas, and you can register more parts and titles under templateParts in theme.json, for example { "area": "header", "name": "header-minimal", "title": "Header (minimal)" }.

Good candidates are headers, footers, sidebars, a post meta row and the comments section. Keep each part focused, give it a clear title and avoid hard-coding content that clients will want to change; patterns are a better home for starter content.

Patterns: the building blocks users actually see

Patterns are predefined arrangements of blocks that users insert from the inserter or that templates include. In a block theme, any PHP file in /patterns with a valid file header is registered automatically, as described in the registering patterns handbook page. The header uses keys such as Title, Slug (themeslug/hero), Categories, Keywords, Description, Viewport Width, Inserter (set to no to hide utility patterns), Block Types, Post Types and Template Types.

Because pattern files are PHP, you can make text translatable and safe, for example <!-- wp:heading --><h2 class="wp-block-heading"><?php echo esc_html__( 'Our services', 'themeslug' ); ?></h2><!-- /wp:heading -->, and output image URLs with esc_url( get_theme_file_uri( 'assets/images/hero.webp' ) ).

Templates can include a pattern with the Pattern block, <!-- wp:pattern {"slug":"themeslug/hero"} /-->, which keeps complex layouts in one translatable file instead of repeating markup across templates. Template Types tell WordPress which templates a pattern suits (for example home or single), and listing core/post-content under Block Types, optionally limited with Post Types, associates a pattern with the post content area, which WordPress uses to offer starter layouts for new pages. Our guide to block bindings shows how synced patterns gain per-instance overrides.

Style variations and block styles

Style variations are alternative versions of theme.json stored in /styles with unique filenames, such as styles/latte.json and styles/midnight.json. The style variations handbook page describes them as "skins" for your theme. Any setting or style allowed in theme.json can appear in a variation, and when a user picks one in the Site Editor, its data is saved to the database as a user customization layered over the theme's theme.json.

• Use variations for genuinely different looks (color schemes, typography pairings), not small tweaks.
• Use block styles for per-block options. register_block_style() in PHP (on init) adds choices such as an outlined button or a framed image, and theme.json can style core block style variations under styles.blocks.core/button.variations.
• Use a child theme for structural changes. The handbook distinguishes variations (design data) from child themes (different templates or code).

Tooling and workflow

The Create Block Theme listing includes an honest disclaimer: think of it "as a Development Mode for WordPress," because "changes made through this plugin could change your site and/or theme permanently." Use it on a local or staging site, commit the exported files to version control, and keep it off production. Install counts and versions above are from the WordPress.org plugin directory as of October 2026.

A workflow that suits agency projects: start from a blank theme with Create Block Theme, define theme.json presets first, build parts and templates in the Site Editor, save them to the theme, move repeated layouts into patterns, then review the exported markup by hand before each commit.

Best practices for production block themes

1. Design tokens first. Every color, font size and spacing value should come from presets, so patterns and user choices stay consistent.
2. Thin templates, rich patterns. Templates should mostly compose parts and patterns.
3. Translate and escape pattern output with esc_html__(), esc_attr__() and esc_url(), following the WordPress coding standards.
4. Keep functionality out of the theme. Custom post types, fields and blocks belong in plugins; see our guide to custom block development.
5. Test accessibility and performance. Check color contrast for every variation, keyboard navigation in the navigation overlay, and font loading weight. Our post on improving Core Web Vitals on WordPress covers the measurement side.
6. Plan for user customizations. Document which templates clients are expected to edit, since database overrides block future theme updates to those templates.
7. Version your theme.json. Renaming preset slugs breaks content that references them; add new slugs instead.

Conclusion

Block theme development replaces PHP templates with three layers: theme.json for the design system, HTML templates and parts for structure, and patterns and style variations for content and choice. Start with the two required files, define presets before markup, compose templates from parts and patterns, and use Create Block Theme in development to move Site Editor work into version-controlled files. For more theme and editor guides, visit our WordPress hub. eSEOspace also designs and builds custom block themes as part of its WordPress website development work.

Frequently asked questions