For years a WordPress theme was a folder of PHP templates, a large stylesheet and a list of customizer options. Block themes changed that. Templates are now made of blocks, global styles live in a single theme.json file, and editors can adjust headers, footers and templates in the Site Editor without touching code. For enterprise teams, that shift is a chance to replace a fragile theme with a real design system.
We build new AlphaWeb projects as block themes, including this site. Here is what we have learned about doing it well.
What theme.json actually controls
theme.json is the contract between your design system and the editor. It defines color palettes, gradients, font families, a fluid type scale, spacing presets, layout widths and per block settings. It also decides what editors are allowed to change. You can turn off custom colors, lock font sizes to your scale and hide controls that invite inconsistency.
That last part matters most for large organizations. When fifty people publish content, the theme should make the right choice the easy choice. A curated palette of brand colors beats a color picker every time.
Structure your templates and parts
A block theme stores templates in a templates folder and reusable pieces such as headers and footers in a parts folder. We keep templates thin. A single post template might be a header part, a post title, featured image, content and a footer part. Anything more complex usually becomes a pattern or a custom block.
Typical templates we ship:
- index, home and archive for listings, with a shared query layout
- single and page for content, plus specialized templates like single case study
- search and 404, which are often forgotten and seen by more visitors than you think
- custom templates that editors can assign to specific pages
Patterns are your component library
Block patterns let you package a layout, such as a hero, a feature grid or a call to action, and give editors one click insertion. Synced patterns let you reuse a block group across many pages and update it once. We register patterns from PHP files in the theme so they are versioned in Git, reviewed and deployed like any other code.
Good patterns are opinionated. They include real headings, sensible spacing and placeholder copy that explains what belongs there. A pattern that looks perfect only with lorem ipsum will fall apart when real content arrives.
Lock what should not move
Block locking and template locking keep important structure intact. We lock the outer layout of a landing page pattern so editors can change words and images but cannot accidentally delete the call to action. For truly fixed regions, we use template parts that only administrators can edit.
Mind performance
Block themes can load only the CSS for blocks that appear on a page, which is a big improvement over monolithic stylesheets. You can help further by:
- Keeping custom CSS small and scoped, ideally per block
- Using system fonts or self hosted variable fonts with font-display swap
- Avoiding heavy page builder plugins on top of a block theme
- Letting core blocks do the work before writing custom ones
Our WordPress performance service covers how this ties into Core Web Vitals.
Migrating from a classic or page builder theme
Most clients come to us with a classic theme or a page builder. The move to a block theme is a good time to clean up. We inventory every template and shortcode, map them to blocks or patterns, and convert content in bulk with scripts rather than by hand. Shortcodes that cannot be converted cleanly are wrapped in small custom blocks so editors see a proper preview instead of bracket text.
Style variations for families of sites
theme.json also supports style variations: alternate JSON files that swap colors, fonts and spacing while keeping the same templates and patterns. We use them heavily for organizations that run several related sites. A district can give every school its own colors and logo while sharing one theme. A brand can launch a campaign site with a distinct palette in an afternoon. Because the variations are just data, the code stays the same and every site benefits from the same fixes and improvements. Combined with Multisite, this is one of the most efficient ways we know to run a family of sites that look related without looking identical. We document each variation alongside the core design tokens, so designers and developers speak the same language when a new site or campaign is requested, and nobody has to reverse engineer a stylesheet to understand the brand.
Block theme checklist
- Design tokens defined in theme.json: colors, fonts, sizes and spacing
- Custom colors and arbitrary font sizes disabled where brand rules require it
- Templates for every view, including search, 404 and archives
- Patterns registered from version controlled PHP files
- Locking on critical layout regions
- Editor styles that match the front end closely
- A short editor guide with screenshots of each pattern
Frequently asked questions
Is the Site Editor safe for large teams?
Yes, with the right roles. We usually limit template editing to administrators and give editors patterns and locked layouts instead.
Do block themes work with custom post types?
Absolutely. You can add templates such as single-event.html and use the Query Loop block with custom post types and taxonomies.
Should we wait for the editor to mature?
The block editor has been the default since WordPress 5.0 in 2018, and block themes have been stable for several major releases. For new builds, we recommend them today.
Ready to modernize your theme? Our WordPress development team can plan the move, or start with a site audit.
