A hybrid WordPress theme combines theme.json-driven styling and block editor customizations with traditional PHP template files. This approach uses the block editor for managing content while still relying on PHP templates for the theme structure. In contrast, block themes use the Site Editor to build and customize the entire theme directly in the block editor.
BE Starter is a free starter theme designed to simplify building hybrid WordPress themes.
At CultivateWP we’ve created hybrid themes since before the block editor arrived in WordPress 5.0 and have delivered hundreds of hybrid themes for clients. We maintain an internal starter theme that we update continuously with new features and fixes for each major WordPress release. BE Starter is a pared-down copy of our Cultivate Starter theme, removing food-blog-specific features so it’s useful for a wider range of projects.
We’re growing our development team, so if you enjoy working on hybrid WordPress themes, we’d love to hear from you.
Starter theme features
Define colors and styles with theme.json
We follow a tokenized design process where each key in theme.json maps to a Figma design token. Designers adjust these tokens to build a site’s style guide—changing brand colors, box shadows, and font sizes—so the entire design is consistent and editable from one place.
During development the theme.json file is customized based on the Figma tokens. Styling elements then becomes a matter of applying the appropriate tokens; for example, h1 might use a “Colossal” font size while h2 uses “Huge.”
When custom font families are needed we use neutral slugs like “primary” and “secondary” to avoid tying styles to overly specific names. This keeps class names and tokens flexible for future redesigns.
We use contrast-checking tools to determine whether brand colors need a dark foreground or white text. Make sure to include any colors that require white text in the blocks core styles so editor rendering matches the front-end.
Use the settings.custom.layout section of theme.json to configure:
content— content area width used for Content and Content Sidebar layouts and for group block content widthswide— site max width used in header, footer, and full-width content areassidebar— sidebar widthpadding— left/right padding for the content areablock-gap— spacing between blocks (e.g., paragraphs and headings)block-gap-large— larger top/bottom padding used for full-width groups with backgrounds, separators, and site-inner spacing
Build custom blocks using ACF and block.json
The starter theme streamlines creating ACF-powered blocks that use block.json for registration. It will automatically register every block inside the /blocks folder, add a style class block-{block name} if a style.css exists in the block folder, and include an init.php file if present.
Typical block structure includes a block.json file, a render.php for output markup, and a style.css for styling. If additional initialization is required, an init.php file will be loaded during the init hook.
Blocks built this way are self-contained: you can move the entire /blocks directory to another theme and they will continue to work. Blocks are styled with plain CSS that uses CSS variables generated from theme.json, for example: background: var(--wp--preset--color--primary);
Note: block CSS files do not automatically receive the .editor-styles-wrapper prefix, so add that class to your editor styles when necessary.
Block Areas for additional editable content
To bring block editing to global areas such as the sidebar or after-post sections, the theme uses “block areas.” Instead of block-based widget areas, a custom post type (CPT) for Block Areas is provided. This allows an admin body class like .block-area-{name} and the editor content width to match the front-end rendering, for example setting the Sidebar block area to the sidebar width defined in theme.json.
The Block Areas CPT appears under Appearance and includes an ACF field group to assign a block area post to a theme-registered area (sidebar, after-post, before-footer, 404). To create a sidebar block area, go to Appearance > Block Areas, add a new Block Area, choose “Sidebar” under Assigned To, publish, and the editor content width will match the site sidebar.
You can manage registered block areas in the theme’s block-areas.php file and display a block area in templates using the provided function, for example: Block_Areas\show( $block_area_name ).
SASS compiled using Node.js
The theme uses Node.js to compile SASS. After setting up the theme locally, run npm install to install dependencies and npm run sass-dev to compile expanded CSS automatically while you work. When you’re ready to deploy, run npm run sass-prod to generate minified CSS for production.
Use be_icon() for loading inline SVGs
Store SVG icons in assets/icons/utility or category-specific icon folders. Optimize SVGs with a tool like SVGO or SVGOMG, and ensure SVGs use viewBox without explicit width/height attributes and are created on a square artboard, for example: .
Use the theme helper be_icon() to output icons efficiently. For example: be_icon( [ 'icon' => 'facebook', 'size' => 24 ] ); The function implements smart caching so icons are referenced with and the icon markup is loaded once in the footer. If an SVG requires its full markup inline, the function supports a 'force' => true option.
Full Site Editing blocks have been removed
The theme unregisters several core blocks related to Full Site Editing in the editor.js file to keep the editing experience focused on content and the hybrid approach.
Login Logo
The login-logo.php file includes variables to customize the admin login logo path and dimensions. Adjust $logo_path, $logo_width, and $logo_height to update the WordPress login page logo.
Summary
The hybrid theme workflow has significantly improved our design and development speed. Using theme.json, Figma design tokens, and self-contained ACF blocks allows us to deliver highly integrated, editable themes much faster than before. We can build a fully custom theme in a fraction of the time it previously took, while keeping the block editor central to content editing—site content, sidebars, and homepages are all editable with familiar block tools.
While Full Site Editing continues to evolve, our team will continue using hybrid WordPress themes for client projects for the foreseeable future because they offer a balanced mix of flexibility, performance, and developer control.