The introduction of Full Site Editing (FSE) and Block Theme Development has fundamentally changed WordPress theme development. Unlike classic themes, which rely on PHP templates and manual CSS, block themes empower developers to build entire sites using modular blocks, global styles, and a visual interface.
In this guide, you’ll learn:
- How to structure a block theme from scratch
- Advanced theme.json configuration techniques
- Creating reusable block patterns and templates
- Performance optimization strategies
- Productivity hacks for developers
Setting Up Your Block Theme Development Environment
1. Folder Structure Essentials
A minimal block theme requires:
your-theme/
├── templates/ # Page templates (e.g., home, single-post)
│ ├── index.html # Fallback template
│ └── single.html # Single post template
├── parts/ # Reusable template parts
│ ├── header.html
│ └── footer.html
├── patterns/ # Custom block patterns
│ └── hero-section.php
├── theme.json # Global styles & settings
├── functions.php # Enqueue scripts/styles
└── style.css # Theme metadata 2. Local Development Tools
- LocalWP or DevKinsta for local hosting
- VS Code with WordPress Snippets extension
- Gutenberg Plugin (optional for experimental features)
Deep Dive into theme.json: The Heart of FSE
Basic Configuration
theme.json controls your theme’s design system. Here’s a foundational setup:
{
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 2,
"settings": {
"appearanceTools": true, // Enables spacing, borders, etc.
"color": {
"palette": [
{ "slug": "primary", "color": "#2B5F87", "name": "Primary Blue" },
{ "slug": "secondary", "color": "#E74C3C", "name": "Accent Red" }
],
"defaultPalette": false // Disables default WordPress colors
},
"typography": {
"fontFamilies": [
{
"slug": "sans-serif",
"fontFamily": "Roboto, Arial, sans-serif",
"name": "Body Font"
}
],
"fontSizes": [
{ "slug": "medium", "size": "18px", "name": "Medium" }
]
}
},
"styles": {
"typography": {
"fontFamily": "var(--wp--preset--font-family--sans-serif)",
"fontSize": "var(--wp--preset--font-size--medium)"
},
"elements": {
"button": {
"color": { "background": "var(--wp--preset--color--primary)" },
"spacing": { "padding": { "top": "12px", "bottom": "12px" } }
}
}
}
}Key Takeaways:
- appearanceTools unlocks UI controls for margins/padding in the editor.
- CSS variables like –wp–preset–color–primary are auto-generated.
Building Templates & Template Parts
1. Header Template (parts/header.html)
<!-- wp:group {"layout":{"type":"constrained"},"tagName":"header"} -->
<header class="wp-block-group">
<!-- wp:site-logo /-->
<!-- wp:navigation -->
<!-- /wp:navigation -->
</header>
<!-- /wp:group -->- Uses Group and Navigation blocks.
- tagName:”header” ensures semantic HTML.
2. Homepage Template (templates/index.html)
<!-- wp:template-part {"slug":"header"} /-->
<!-- wp:pattern {"slug":"your-theme/hero"} /-->
<!-- wp:query {"queryId":1,"query":{"perPage":3}} -->
<div class="wp-block-query">
<!-- wp:post-template -->
<!-- wp:post-title /-->
<!-- wp:post-excerpt /-->
<!-- /wp:post-template -->
</div>
<!-- /wp:query -->
<!-- wp:template-part {"slug":"footer"} /-->- Query Block pulls latest posts.
- Pattern inserts a pre-designed hero section.
Creating Custom Block Patterns
1. Hero Section Pattern (patterns/hero-section.php)
<?php
register_block_pattern(
'your-theme/hero',
array(
'title' => 'Hero Section',
'content' => '
<!-- wp:cover {"url":"/wp-content/uploads/hero-bg.jpg"} -->
<div class="wp-block-cover">
<div class="wp-block-cover__inner-container">
<!-- wp:heading {"level":1,"className":"hero-title"} -->
<h1 class="hero-title">Welcome to My Site</h1>
<!-- /wp:heading -->
<!-- wp:buttons -->
<div class="wp-block-buttons">
<!-- wp:button {"className":"hero-cta"} -->
<div class="wp-block-button hero-cta"><a class="wp-block-button__link">Get Started</a></div>
<!-- /wp:button -->
</div>
<!-- /wp:buttons -->
</div>
</div>
<!-- /wp:cover -->
'
)
);Advanced: Custom Block Styles & Variations
1. Add a Custom Button Style
In theme.json:
{
"styles": {
"blocks": {
"core/button": {
"variations": {
"custom-cta": {
"name": "CTA Button",
"styles": {
"color": { "text": "#ffffff" },
"border": { "radius": "50px" }
}
}
}
}
}
}
}Users can now select “CTA Button” style in the block toolbar.
Performance Optimization Tips
Conditional Asset Loading
In functions.php, load CSS/JS only where needed:
function your_theme_enqueue_scripts() {
// Load only on front page
if (is_front_page()) {
wp_enqueue_style('homepage-styles', get_template_directory_uri() . '/css/homepage.css');
}
}
add_action('wp_enqueue_scripts', 'your_theme_enqueue_scripts');Lazy Load Images
Add to theme.json:
{
"settings": {
"content": {
"lazyLoading": true
}
}
}Developer Productivity Hacks
1. Use WP-CLI for Rapid Setup
# Scaffold a new block theme
wp scaffold _s my-theme --theme_type=block2. Leverage CSS Custom Properties
Override default block styles via theme.json:
{
"styles": {
"core/post-title": {
"typography": {
"fontSize": "var(--wp--custom--title--size, 2.5rem)"
}
}
}
}3. Debug with Browser Tools
Inspect auto-generated CSS variables in the browser’s DevTools:
body {
--wp--preset--color--primary: #2B5F87;
--wp--preset--font-family--sans-serif: Roboto, Arial, sans-serif;
}FAQs: Block Theme Development
Can I migrate a classic theme to a block theme?
Yes, but it requires restructuring templates into HTML block markup and moving styles to theme.json.
How do block themes handle plugin compatibility?
Most plugins work, but check for FSE-compatible alternatives (e.g., WooCommerce Blocks).
Are block themes slower than classic themes?
No—properly optimized block themes load only necessary CSS/JS, improving performance.
Do block themes support child themes?
Yes, you can create child themes for block themes, but they inherit styles from theme.json instead of a traditional style.css.
Can I use custom fonts in a block theme?
Yes, custom fonts can be added via theme.json without needing custom CSS or third-party plugins.
How do I customize a block theme without coding?
The Site Editor allows full customization, including templates, typography, and colors, without writing any code.
