Setting the stage
In Part 2, we explored the architecture of block themes using a house analogy. Now it’s time to actually build one! Whether you’re a developer or someone who prefers working visually, WordPress gives you options. Let’s explore both paths.
I’m not a developer (but I want my own block theme!)
The easiest option? Use an existing block theme.
WordPress has been shipping block themes since WordPress 5.9 (December 2021). You’ll find dozens of quality block themes in the official WordPress Theme Directory – just filter by “Block Themes” or “Full Site Editing” when searching.
But what if I want to create my own block theme from scratch?
You absolutely can – and you don’t need to write a single line of code. Enter the Create Block Theme plugin.
Think of this plugin as your visual theme construction kit.
It lets you:
• Create a blank theme from scratch
• Clone the active theme (make a copy with your customisations)
• Create a child theme (build on top of an existing theme)
• Create style variations (different layouts/color schemes and style presets for the core blocks of your theme)
• Export your theme as a zip file
• Save changes you make in the Site Editor directly to your theme files
Important note: This plugin is powerful! Think of it as “Developer Mode” for WordPress. It makes permanent changes to your site and theme, so make sure you understand what each option does before clicking “Save.”
What This Plugin CAN’T Do:
The Create Block Theme plugin is powerful, but it has limits:
❌ It can’t create custom Gutenberg blocks
If you need a special block with unique functionality (like a custom slider, interactive pricing table, or dynamic team member grid), you’ll need to develop that separately or use a plugin.
❌ It can’t add complex frontend interactivity
Beyond what core blocks provide (like the Query Loop or interactive blocks), you’ll need custom development for things like:
• Interactive filtering and sorting
• Real-time form validation
• Dynamic content loading
• Complex animations
For these needs, you’ll want to work with a developer or use specialised plugins.
Side note (for both non-developers and developers): What are block variations?
You probably haven’t heard me talk about them before, since only recently did I discover how cool and powerful they are! So, you might be wondering: what’s a block variation?
Block Variations are modifications of existing core blocks. They add new options to the block inserter.
Example: WordPress has a Media & Text block that shows one image and text side-by-side. You could create a “Double Image & Text” variation that displays TWO images with text instead.
I’m a developer (and I want full control of what I’m creating!)
If you’re comfortable with code, you have even more flexibility. Let’s talk about building a block theme from scratch.
Understanding the File Structure
Every block theme needs a specific folder structure. Here’s the basic anatomy:
my-theme/
├── style.css (required – theme metadata)
├── functions.php (optional but common)
├── theme.json (required – theme configuration)
├── templates/
│ ├── index.html (required – fallback template)
│ ├── front-page.html
│ ├── single.html
│ ├── page.html
│ └── … (other templates)
├── parts/
│ ├── header.html
│ ├── footer.html
│ └── … (other template parts)
└── patterns/
├── hero.php
├── call-to-action.php
└── … (your patterns)
The only required files are:
• style.css (with proper theme headers)
• theme.json (theme settings and styles)
• templates/index.html (the fallback page template)
Everything else is optional but gives you more control.
Two Approaches to Development
Approach 1: Start with the Plugin, Then Code
You can use the Create Block Theme plugin as a starting point:
1. Create a theme with only the required files in your codebase
2. Create some basic templates in the Site Editor
3. Use “Save Changes” to generate the files
4. Then switch to your code editor and refine from there
This gives you a head start with properly formatted template files.
Approach 2: Pure Code
Personally, I prefer starting in my code editor. Here’s why: more control and less confusion once you get familiar with the process.
For templates and template parts (HTML files), here’s my preferred workflow:
1. Design in the Site Editor – Create your template/part visually
2. Switch to Code Editor – Click the three dots → “Code editor”
3. Copy the HTML – This shows you the block markup WordPress generates
4. Paste into your file – Save it in your theme’s templates/ or parts/ folder
⚠️ Important caveat: Once a template or template part exists in your codebase AND someone edits it in the Site Editor, you enter what can be thought of as “the revision dance”:
• CMS changes override code changes – If someone edits a template in the Site Editor, those changes take precedence
• To see your code changes again – You must “Reset” the template in the Site Editor (three dots → Reset)
• Resetting wipes CMS changes – Any Site Editor customizations will be lost
Think of it this way: The CMS creates “revisions” that layer on top of your code. Reset removes those revisions and goes back to what’s in your files.
Best practice: Establish early your own workflow on working on a template or template part, depending on your project’s needs. We’ll explore workflow strategies for different project types in a future article.
Styling Your Theme: Three Approaches
Option 1: theme.json + Block Styles
You can define your design system in theme.json:
• Colour palette
• Typography scale
• Spacing units
• Layout settings
And create block styles for the core blocks three ways:
• JSON: Block style variations in theme.json
• PHP: Register block styles in functions.php (or individual file imported to functions.php)
• JavaScript: Register block styles via a script
Option 2: CSS/SCSS
You can write traditional stylesheets for fine-tuned control:
• Create a style.css or assets/css/ folder
• Use SCSS for variables, mixins, styling functions and nesting
• Compile to CSS (if using SCSS)
• Make sure you enqueue your individual or built CSS files
Option 3: Hybrid
You can use both! Let theme.json handle your design tokens (colours, spacing, typography) and use CSS/SCSS for:
• Complex layouts
• Custom animations
• Component-specific styling
• Responsive adjustments
This gives you the best of both worlds: block editor integration + styling power.
Note: Custom Gutenburg blocks use SCSS by default. If you need to build custom blocks in your theme, I recommend using SCSS for the rest of the styling as well (combined with theme.json) for consistency.
Adding Frontend Interactivity:
Here’s a practical real-world example I recently built:
Query Block → Article Slider Variation
The core Query Loop block displays posts in a grid or list. I created a variation that:
• Displays posts as a slider instead
• Lets users select specific posts (not just show latest/all)
• Adds slide navigation controls
• Uses the Interactivity API for smooth transitions
This gives users a “Article Slider” option in the block inserter that’s preconfigured and ready to use.
You can have the same result if you build a custom block for this – you can add both to your codebase when building a block theme.
For Custom Blocks: JavaScript support is built in by default (using @wordpress/create-block scaffolds this for you).
For core blocks: you can add interactivity using the Interactivity API or custom JavaScript files.
How?
1. Create JavaSript files in your theme (e.g. assets/js/slider.js)
2. Set up a build process (Webpack, Vite etc.)
3. Enqueue scripts in functions.php
4. Use the Interactivity API for reactive behaviour
Additional complex functionality:
Sometimes you might need to add PHP for:
• WooCommerce integration
• Custom REST API endpoints
• Advanced database queries
• Server-side processing
Block themes support functions.php just like classic themes – use it when needed!
Conclusion: Which Path Is Right for You?
Choose the Plugin Path if:
• You want to build sites, not code
• You need a theme quickly
• You’re comfortable with visual editing tools
• Your needs fit within core block capabilities
• You have additional functionality needs and you are willing to use additional plugins for it
Choose the Developer Path if:
• You want full control over every detail
• You’re building custom functionality
• You need version control and team collaboration
• You’re comfortable with modern development tools
The good news? You can switch between both! Start with the plugin to understand how block themes work, then graduate to code when you need more power.
—
What’s Next?
In future articles, we’ll dive deeper into block styles vs style variation vs block variations: what is the difference between them, how do they work and where should they be used?
Is there anything you’d like to know more about next? Drop a comment and let me know what confuses you most about block theme development!