WordPress Block Theme Development: Starter Guide

TL;DR: WordPress Block Theme Starter Setup

A WordPress block theme needs at minimum a theme folder, style.css, and a block template such as templates/index.html. In real projects, you should also add theme.json, reusable template parts in /parts, templates in /templates, patterns in /patterns, optional custom CSS in /assets, and a clean functions.php only when needed. Use theme.json for global colors, typography, spacing, layout widths, and block settings before writing custom CSS.

What Is a WordPress Block Theme?

A WordPress block theme is a theme built mainly from blocks, HTML templates, template parts, patterns, and global style configuration. Instead of editing only post content with blocks, block themes allow headers, footers, archives, single posts, pages, and other layout areas to be edited through the Site Editor.

In a classic theme, the structure usually depends on PHP files. In a block theme, the structure usually depends on block markup saved inside HTML template files.

Simple difference:

Official reference: WordPress Theme Handbook.

When Should Developers Use a Block Theme?

Block themes are a good fit when you want a modern WordPress editing experience, strong Site Editor control, reusable patterns, global design presets, and less reliance on custom PHP templates for layout.

Use a block theme when:

• You want clients to edit headers, footers, templates, and patterns visually.
• You are building a modern content site, business website, or magazine layout.
• You want to define design tokens through theme.json.
• You want reusable patterns for sections like hero, pricing, CTA, FAQs, and cards.
• You are building future-ready WordPress themes.
• You want tighter integration with the Site Editor and Global Styles.

Be careful with block themes when:

• The client needs highly locked-down layouts with minimal editor freedom.
• The project depends heavily on legacy PHP template logic.
• The site has complex WooCommerce or membership templates that need custom handling.
• The editor team is not trained on the Site Editor.
• You need strict design control and do not want users editing templates.

Block themes are powerful, but they require a different development mindset. You are not only building templates. You are also designing an editable system.

Minimum Files Required for a Block Theme

A basic block theme can be very small. For a real project, you will add more structure, but the minimum starter theme is simple.

Minimum structure:

my-block-theme/
├── style.css
└── templates/
    └── index.html

WordPress uses the presence of templates/index.html to identify a theme as a block theme.

Basic style.css:

/*
Theme Name: My Block Theme
Theme URI: https://example.com/
Author: Your Name
Author URI: https://example.com/
Description: A starter WordPress block theme.
Requires at least: 6.6
Tested up to: 7.0
Requires PHP: 7.4
Version: 1.0.0
License: GNU General Public License v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-block-theme
*/

Basic templates/index.html:

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">

    <!-- wp:site-title /-->

    <!-- wp:query {"query":{"perPage":10,"postType":"post"}} -->
    <div class="wp-block-query">
        <!-- wp:post-template -->
            <!-- wp:post-title {"isLink":true} /-->
            <!-- wp:post-excerpt /-->
        <!-- /wp:post-template -->
    </div>
    <!-- /wp:query -->

</div>
<!-- /wp:group -->

This is enough to activate a basic block theme, but not enough for a polished production theme.

Official reference: Block Theme Templates.

Recommended Block Theme File Structure

For a real development project, use a clean file structure. This makes the theme easier to maintain, extend, and hand over to another developer.

my-block-theme/
├── assets/
│   ├── css/
│   │   └── custom.css
│   ├── js/
│   │   └── theme.js
│   └── images/
├── parts/
│   ├── header.html
│   └── footer.html
├── patterns/
│   ├── hero.php
│   ├── call-to-action.php
│   └── pricing-cards.php
├── styles/
│   ├── blue.json
│   └── dark.json
├── templates/
│   ├── 404.html
│   ├── archive.html
│   ├── home.html
│   ├── index.html
│   ├── page.html
│   ├── search.html
│   └── single.html
├── functions.php
├── screenshot.png
├── style.css
└── theme.json

What each folder does:

• templates/: top-level block templates such as index, single, page, archive, and 404.
• parts/: reusable template parts such as header, footer, sidebar, or newsletter sections.
• patterns/: reusable block patterns registered by the theme.
• styles/: optional style variations for different design presets.
• assets/: optional CSS, JavaScript, fonts, and images.
• theme.json: global settings, styles, design tokens, and block configuration.
• functions.php: optional PHP setup, enqueueing, supports, filters, and pattern categories.

Understanding theme.json

The theme.json file is one of the most important files in a block theme. It lets you define design settings, style presets, layout widths, typography, colors, spacing, and block-level behavior in a structured way.

Basic theme.json example:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "layout": {
      "contentSize": "720px",
      "wideSize": "1200px"
    },
    "color": {
      "palette": [
        {
          "slug": "primary",
          "color": "#2563eb",
          "name": "Primary"
        },
        {
          "slug": "dark",
          "color": "#111827",
          "name": "Dark"
        },
        {
          "slug": "light",
          "color": "#f8fafc",
          "name": "Light"
        }
      ]
    },
    "typography": {
      "fontSizes": [
        {
          "slug": "small",
          "size": "14px",
          "name": "Small"
        },
        {
          "slug": "medium",
          "size": "18px",
          "name": "Medium"
        },
        {
          "slug": "large",
          "size": "32px",
          "name": "Large"
        }
      ]
    },
    "spacing": {
      "spacingScale": {
        "steps": 6
      }
    }
  },
  "styles": {
    "color": {
      "background": "#ffffff",
      "text": "#111827"
    },
    "typography": {
      "fontFamily": "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif"
    },
    "elements": {
      "link": {
        "color": {
          "text": "#2563eb"
        }
      }
    }
  }
}

Use theme.json for:

• Color palettes.
• Typography presets.
• Spacing scale.
• Content and wide layout widths.
• Default block styles.
• Button, link, heading, and element styles.
• Block-level settings.
• Editor controls and design restrictions.

Official reference: Global Settings and Styles.

Global Styles vs Custom CSS

In block theme development, start with theme.json first. It gives WordPress, the Site Editor, blocks, plugins, and users a shared design system. Custom CSS is still useful, but it should not be your first tool for every style.

Use theme.json when:

• You are defining global colors.
• You are setting typography presets.
• You are controlling spacing and layout widths.
• You are styling core blocks in a predictable way.
• You want the Site Editor to understand the design system.
• You want users to access approved design tokens.

Use custom CSS when:

• The design cannot be expressed cleanly in theme.json.
• You need complex responsive behavior.
• You are styling custom block markup.
• You need animation or advanced selectors.
• You are handling browser-specific or layout-specific details.

Official reference: Block Stylesheets.

Creating Header and Footer Template Parts

Template parts are reusable layout sections. In block themes, headers and footers usually live in the /parts directory and are included inside templates.

parts/header.html:

<!-- wp:group {"align":"full","layout":{"type":"constrained"}} -->
<div class="wp-block-group alignfull">
    <!-- wp:group {"align":"wide","layout":{"type":"flex","justifyContent":"space-between","flexWrap":"wrap"}} -->
    <div class="wp-block-group alignwide">
        <!-- wp:site-title {"level":0} /-->
        <!-- wp:navigation /-->
    </div>
    <!-- /wp:group -->
</div>
<!-- /wp:group -->

parts/footer.html:

<!-- wp:group {"align":"full","layout":{"type":"constrained"}} -->
<div class="wp-block-group alignfull">
    <!-- wp:paragraph {"align":"center"} -->
    <p class="has-text-align-center">© 2026 Your Website. All rights reserved.</p>
    <!-- /wp:paragraph -->
</div>
<!-- /wp:group -->

Include template parts in a template:

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

<!-- wp:group {"layout":{"type":"constrained"}} -->
<main class="wp-block-group">
    <!-- wp:post-title /-->
    <!-- wp:post-content /-->
</main>
<!-- /wp:group -->

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

Official reference: Template Parts.

Creating Basic Block Templates

Templates define the structure for different WordPress views. A block theme can include templates for posts, pages, archives, search results, 404 pages, and more.

Recommended starter templates:

• index.html: fallback template.
• home.html: blog index.
• single.html: single blog posts.
• page.html: pages.
• archive.html: category, tag, date, and custom archives.
• search.html: search results.
• 404.html: not found page.

templates/single.html example:

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

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">

    <!-- wp:post-title {"level":1} /-->

    <!-- wp:group {"layout":{"type":"flex","flexWrap":"wrap"}} -->
    <div class="wp-block-group">
        <!-- wp:post-date /-->
        <!-- wp:post-author-name /-->
    </div>
    <!-- /wp:group -->

    <!-- wp:post-featured-image {"align":"wide"} /-->

    <!-- wp:post-content {"layout":{"type":"constrained"}} /-->

    <!-- wp:post-terms {"term":"category"} /-->

</main>
<!-- /wp:group -->

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

templates/archive.html example:

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

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">

    <!-- wp:query-title {"type":"archive"} /-->

    <!-- wp:query {"query":{"perPage":10,"postType":"post"}} -->
    <div class="wp-block-query">

        <!-- wp:post-template -->
            <!-- wp:post-title {"isLink":true} /-->
            <!-- wp:post-excerpt /-->
            <!-- wp:post-date /-->
        <!-- /wp:post-template -->

        <!-- wp:query-pagination -->
            <!-- wp:query-pagination-previous /-->
            <!-- wp:query-pagination-numbers /-->
            <!-- wp:query-pagination-next /-->
        <!-- /wp:query-pagination -->

    </div>
    <!-- /wp:query -->

</main>
<!-- /wp:group -->

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

Patterns: The Secret to Better Block Themes

Patterns are reusable groups of blocks. They are extremely useful for block themes because they let you ship ready-made sections that users can insert and customize.

Good pattern ideas:

• Hero section.
• Pricing cards.
• Feature grid.
• CTA banner.
• FAQ section.
• Team cards.
• Testimonial section.
• Blog post grid.
• Newsletter signup.
• Comparison table.

patterns/hero.php example:

<?php
/**
 * Title: Hero with CTA
 * Slug: my-block-theme/hero-with-cta
 * Categories: featured
 * Description: A simple hero section with heading, text, and call-to-action buttons.
 */
?>

<!-- wp:group {"align":"wide","style":{"spacing":{"padding":{"top":"80px","bottom":"80px"}}},"layout":{"type":"constrained"}} -->
<div class="wp-block-group alignwide" style="padding-top:80px;padding-bottom:80px">

    <!-- wp:heading {"level":1,"textAlign":"center"} -->
    <h1 class="has-text-align-center">Build Faster WordPress Websites</h1>
    <!-- /wp:heading -->

    <!-- wp:paragraph {"align":"center"} -->
    <p class="has-text-align-center">A clean block theme starter section for modern WordPress projects.</p>
    <!-- /wp:paragraph -->

    <!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
    <div class="wp-block-buttons">
        <!-- wp:button -->
        <div class="wp-block-button"><a class="wp-block-button__link wp-element-button">Get Started</a></div>
        <!-- /wp:button -->
    </div>
    <!-- /wp:buttons -->

</div>
<!-- /wp:group -->

Official reference: Patterns in Block Themes.

Style Variations in Block Themes

Style variations let you ship multiple visual styles for the same block theme. For example, you can provide a default style, dark style, blue style, minimal style, or high-contrast style.

styles/dark.json example:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "title": "Dark",
  "styles": {
    "color": {
      "background": "#111827",
      "text": "#f9fafb"
    },
    "elements": {
      "link": {
        "color": {
          "text": "#93c5fd"
        }
      }
    }
  }
}

Use style variations for:

• Dark mode-style presets.
• Brand color alternatives.
• Minimal vs bold layouts.
• Client-specific design options.
• Starter theme packages.

Keep variations simple. If every variation changes too much, the theme becomes harder to test and maintain.

functions.php in Block Themes: Keep It Light

Block themes still support functions.php, but you should not use it as a dumping ground. Many things that classic themes handled in PHP can now be handled through theme.json, templates, parts, and patterns.

Good uses for functions.php:

• Enqueueing custom scripts or styles.
• Registering pattern categories.
• Adding custom block styles.
• Adding theme setup support when needed.
• Registering custom image sizes.
• Adding filters for advanced behavior.

Example functions.php:

<?php
/**
 * My Block Theme functions.
 */

add_action( 'wp_enqueue_scripts', function () {
    wp_enqueue_style(
        'my-block-theme-custom',
        get_theme_file_uri( 'assets/css/custom.css' ),
        array(),
        wp_get_theme()->get( 'Version' )
    );
} );

add_action( 'init', function () {
    register_block_pattern_category(
        'my-block-theme-sections',
        array(
            'label' => __( 'My Theme Sections', 'my-block-theme' ),
        )
    );
} );

If a setting can be handled in theme.json, prefer theme.json. Use PHP only when it adds real value.

Block Theme Development Workflow

A clean workflow prevents messy block markup, duplicated styles, and template confusion.

Recommended workflow:

1. Create the theme folder and starter files.
2. Define global layout, colors, typography, and spacing in theme.json.
3. Create header and footer template parts.
4. Create base templates: index.html, single.html, page.html, and archive.html.
5. Build reusable patterns for common sections.
6. Use the Site Editor to test real editing behavior.
7. Move repeated sections into patterns or template parts.
8. Add custom CSS only where theme.json cannot handle the design cleanly.
9. Test responsive behavior, keyboard navigation, and accessibility.
10. Test with real content, not only perfect demo content.

Block themes are not only coded. They are also edited. Always test how the theme feels inside the Site Editor.

How to Build a Starter Block Theme Step by Step

Step 1: Create the theme folder

wp-content/themes/fyre-starter/

Step 2: Add style.css

/*
Theme Name: Fyre Starter
Author: FyrePress
Description: A starter block theme for WordPress development.
Version: 1.0.0
Requires at least: 6.6
Requires PHP: 7.4
Text Domain: fyre-starter
*/

Step 3: Add theme.json

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "layout": {
      "contentSize": "760px",
      "wideSize": "1200px"
    }
  },
  "styles": {
    "spacing": {
      "blockGap": "1.5rem"
    }
  }
}

Step 4: Add templates/index.html

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

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
    <!-- wp:query {"query":{"perPage":10,"postType":"post"}} -->
    <div class="wp-block-query">
        <!-- wp:post-template -->
            <!-- wp:post-title {"isLink":true} /-->
            <!-- wp:post-excerpt /-->
        <!-- /wp:post-template -->
    </div>
    <!-- /wp:query -->
</main>
<!-- /wp:group -->

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

Step 5: Add parts/header.html and parts/footer.html

Use reusable template parts so every template can share the same header and footer.

Step 6: Activate and test

1. Go to Appearance → Themes.
2. Activate your block theme.
3. Open Appearance → Editor.
4. Edit templates and verify the structure works.
5. Create sample posts and pages to test real layouts.

Classic Theme vs Block Theme vs Hybrid Theme

Developers do not always need to jump straight from classic themes to full block themes. Hybrid themes can be useful during migration.

If you already maintain a large classic theme, a hybrid approach may be safer. If you are building a new modern WordPress theme, start with a block theme unless the project requires heavy PHP template control.

Official reference: Hybrid Themes.

Common Block Theme Development Mistakes

Block themes are flexible, but beginners often make the same mistakes.

• Writing too much CSS before configuring theme.json.
• Hardcoding layout values instead of using global settings.
• Creating every section as a template instead of using patterns.
• Ignoring how templates behave inside the Site Editor.
• Forgetting responsive testing.
• Using too many nested groups and containers.
• Letting clients edit critical templates without training or guardrails.
• Not testing with long titles, missing featured images, and real content.
• Not checking accessibility and keyboard navigation.
• Mixing too many styling systems: inline styles, CSS, theme.json, and plugin styles without control.

Block Theme Performance Tips

A block theme can be fast or slow depending on how it is built. The Site Editor does not automatically guarantee performance.

Performance checklist:

• Use clean block structure with minimal nesting.
• Avoid unnecessary wrapper groups.
• Do not load large CSS files for small styling needs.
• Use theme.json to reduce duplicated CSS where possible.
• Load custom CSS only when needed.
• Avoid heavy sliders and animation libraries.
• Use optimized images in patterns.
• Test LCP on templates with hero images.
• Test CLS when using headers, banners, and template parts.
• Use proper caching and object cache on dynamic sites.

Block Theme Accessibility Checklist

Accessibility should be part of the theme system from the start, not added after launch.

• Use semantic template part tags such as header, main, and footer.
• Keep heading levels logical.
• Ensure navigation is keyboard usable.
• Use sufficient color contrast in theme.json palettes.
• Do not remove visible focus styles.
• Test buttons, links, forms, and menus by keyboard.
• Use meaningful alt text for content images.
• Avoid using images of text where real text is better.
• Check template parts on mobile and zoomed views.

Accessibility is easier when your design tokens, color palette, typography, and spacing system are planned before building templates.

Best Tools for Block Theme Development

You can build block themes with a code editor and WordPress alone, but the right tools make development smoother.

Useful tools:

• Local development: LocalWP, Docker, DDEV, or your preferred local stack.
• Code editor: VS Code or another editor with HTML, JSON, PHP, and CSS support.
• Browser DevTools: For CSS, layout, performance, and responsive testing.
• Site Editor: For testing real template editing behavior.
• Create Block Theme plugin: Useful for exporting and experimenting with block theme changes.
• WP-CLI: Useful for theme activation, testing, cache flushing, and scripted workflows.
• Theme Check: Useful before distribution or marketplace submission.

Do not rely only on visual editing. Always inspect the generated block markup and template files.

Testing Checklist Before Shipping a Block Theme

Before using a block theme on a client site or releasing it publicly, test more than the homepage.

• Homepage template.
• Single post template.
• Page template.
• Archive template.
• Search results template.
• 404 template.
• Header and footer template parts.
• Navigation block behavior.
• Patterns with real content.
• Global Styles editing.
• Style variations.
• Mobile and tablet layouts.
• Long titles and long menus.
• Posts without featured images.
• Images with different aspect ratios.
• Comments if the site uses them.
• WooCommerce templates if relevant.
• Accessibility and keyboard navigation.
• Performance and Core Web Vitals.

Best Method by Developer Type

For classic theme developers

Start by building a small block theme from scratch. Do not try to convert a complex classic theme immediately. Learn templates, parts, patterns, and theme.json first.

For agency developers

Create a reusable agency starter theme with approved colors, typography, spacing, patterns, and template structure. Train clients on which areas they should and should not edit.

For freelancers

Use block themes to speed up small business sites, blogs, landing pages, and content-driven builds. Keep the structure simple so clients can maintain it.

For WooCommerce developers

Test carefully. WooCommerce block compatibility, product templates, cart, checkout, and account pages may need deeper review than a normal blog theme.

For theme sellers

Invest in patterns, style variations, documentation, accessibility, and clean theme.json settings. Buyers need a system, not just a visual design.

Final Recommendation

WordPress block theme development is not just classic theme development with different files. It changes how developers think about templates, design systems, reusable sections, client editing, and global styles.

Start simple: create style.css, theme.json, templates/index.html, header and footer template parts, and a few reusable patterns. Then test everything inside the Site Editor with real content.

Use theme.json for global design decisions, use patterns for reusable sections, use template parts for repeated layout areas, and use custom CSS or PHP only when they solve a real problem. A good block theme should be clean in code, predictable in the editor, fast on the frontend, and easy for site owners to customize safely.

Frequently Asked Questions

What is a WordPress block theme?

A WordPress block theme is a theme built mainly from block-based HTML templates, template parts, patterns, and global style configuration. It allows headers, footers, templates, and other site areas to be edited in the Site Editor.

What files are required for a WordPress block theme?

At minimum, a block theme needs a style.css file and a block template such as templates/index.html. Most real block themes also use theme.json, template parts, patterns, and optional assets.

Is theme.json required for block themes?

A block theme can technically exist without theme.json, but most practical block themes should use it because it defines global settings, styles, layout widths, colors, typography, spacing, and block behavior.

What is the difference between templates and template parts?

Templates define full page views such as single posts, pages, archives, search results, and 404 pages. Template parts are reusable sections such as headers, footers, sidebars, or repeated layout areas.

Should block themes use CSS or theme.json?

Use theme.json first for global design settings, colors, typography, spacing, and block styles. Use CSS when the design requires advanced selectors, custom behavior, animations, or styles that are not practical in theme.json.

Are block themes faster than classic themes?

Not automatically. A block theme can be fast if it has clean markup, minimal nesting, optimized assets, and good caching. It can also be slow if it uses heavy patterns, too many wrappers, large images, and unnecessary scripts.

Can I convert a classic theme to a block theme?

Yes, but it is often better to plan the conversion carefully. Start by identifying templates, reusable sections, global styles, and custom PHP logic. Some projects may be better as hybrid themes before becoming full block themes.

Do block themes support PHP?

Yes. Block themes can still use functions.php for enqueueing assets, registering pattern categories, adding filters, and supporting advanced behavior. However, layout templates are usually HTML block templates instead of PHP files.

What are patterns in block themes?

Patterns are reusable groups of blocks, such as hero sections, pricing cards, CTAs, feature grids, testimonials, and FAQ sections. They help users build pages quickly while staying within the theme’s design system.

Should developers build block themes for client sites?

Yes, when the client needs modern editing flexibility and the project fits the Site Editor workflow. Developers should provide clear patterns, sensible Global Styles, documentation, and guardrails so clients do not accidentally break important layouts.