WordPress block themes allow you to add fonts to a theme by adding the font file assets to the theme folder and referencing them in the theme.json. Editing a JSON file manually does not deliver the best user experience. The good news is you can use the plugin to make this task much simpler without technical trade-offs.

Disclaimer: The plugin is for development only and is not intended for live production websites because it modifies the currently active theme. It was conceived as a tool to create new production-ready themes.

Step by Step

1. Install the Create Block Theme plugin.
2. Activate the theme you want to manage.
3. Go to Appearance -> Manage Theme Fonts.
4. Add/Remove the font faces you want.

FAQS

How are the fonts bundled in my theme?

The plugin stores the font assets in a sub-folder of your theme ( <your-current-theme>/assets/fonts/ ) and adds font family definitions to your theme.json file. This is the case no matter if you upload a local font asset or use the Add Google Font option.

The plugin removes both the theme.json definition and the font assets if you remove a font face.

How are the fonts enqueued?

WordPress takes the font faces you added using the plugin, which are listed in your theme.json, and automatically converts them to CSS font face definitions which are included in the HTML page downloaded by the user browser.

Will adding many fonts make my theme too heavy?

Yes and no, or not necessarily. That can be counter-intuitive so let’s explore it in more detail. 

WordPress references all the font files needed in your site CSS to let the browser know what font assets may need to download.

Even though WordPress references many fonts, modern browsers are optimized to only download the fonts that are used in the page being loaded. It is important to note that browsers calculate this considering just the current page loaded and not on a site-wide basis.

For example, if you include an ultra-thin variant of the Inter font family, but there is not a single element (ex: paragraphs, links, etc.) using Inter ultra-thin variant, the browser will not download this font asset. In this case, the performance penalty for including this font is nearly zero.

Should I add a massive quantity of font faces to my theme “just in case”?

No, both from a performance and design perspective, having a good font pair is always advisable over a proliferation of too many different fonts. Also, if the font is not in use, what’s the point of including it?

There is no magical number of font faces you can or should include. But usually, less is more. Sticking to the minimal quantity required to implement the aesthetics you are looking for is always a good idea.

Can I include variable fonts in my theme?

As with any other font file, you can add variable font assets using the “Add Local Font” option. The plugin will add the font definition and asset just like any other type of font. You can use it just like that or adjust more options related to variable fonts by editing the theme.json file.

Is this solution GDPR compliant?

Yes, because the plugin bundles the font files in your theme, and your WordPress instance will serve them. No third-party servers or tracking technologies are involved in serving the fonts to your users. You don’t need to request extra permissions from your users to include the fonts.

More info

Do you need a more detailed step-by-step guide? No worries! Check out this great video tutorial about how to use the plugin.

Follow up

Have any questions about fonts and themes? Ask in the comments!

1. Avoid using CSS

As much as possible, block themes should avoid providing CSS. Gutenberg increasingly offers design tools which allow theme builder to control the design of the theme without using CSS. If it is not possible to achieve a particular design without CSS please create an issue for it on Gutenberg so we can consider adding a design tool to achieve the design.

2. Reuse patterns rather than implementing custom templates

As the number of block themes we build grows we will have an ever increasing number of templates and template parts in each theme. In practice there are a small number of patterns which can be reused on many themes. We should be aiming to reuse existing patterns rather than implementing new templates. This means we need clever patterns which are able to reuse settings from theme.json.

3. Prefer theme.json to block settings

Connected to the point above, when we want to change the appearance of a block in a template or a pattern it is usually better to do so in the theme.json file than in the block template. This means that the design will be used for all instances of the block, not just the edited instance. It also keeps templates design agnostic, so that they be reused (see above).

What other tips do you have for building block themes?

I tried to create a new theme called “Typewriter” using these tools.

Step 1 – Setup

Install and activate Blockbase , and the Create Blockbase Theme plugin.

Step 2 – Global Styles

Make changes to your site using the Global Styles editor. First I chose some new colors:

You can also use the Global Styles editor to update Typography and Layout settings:

Then I changed the fonts, using the Customizer:

I made all my changes using the Global Styles editor and the Customizer, but you might want to make more changes directly to the theme.json file after the theme is created.

Step 3 – Templates

Edit your templates using the Site Editor:

I managed to achieve everything I needed to in this theme using the Site Editor, but for some things you might need to edit the template files directly once the theme is created.

Step 4 – Export

Under Appearance there will be a new page called “Create Blockbase Theme”:

You can add the details for the theme here. These will be used in the style.css file. When you click the “Create Blockbase Theme” button, a zip file will be downloaded, which contains all the files for your theme. Here’s mine:

Step 5 – Test

At this point you should have a zip file containing a working theme. You can upload this to your WordPress and activate it.

The theme contains an screenshot file, which you will need to update manually.

Now when you look at the frontend of your site it should look the same as it did before you activated the new theme. Here’s my new theme:

Further changes

Once the theme has been created you can unzip the theme zip file and make further changes to the theme files. This might be necessary to make more advanced changes to the theme. You can:

• Modify and add configuration in the theme.json file.
• Update the html template files in block-templates and block-template-parts
• Add custom CSS to the file in assets/theme.css

Feedback

We’d love you to try this new tool and let us know how you get on in the comments!

The Problem

WordPress is introducing the Full Site Editor and with it new ways to build themes.  These themes are called “Block” themes and integrate deeply with Gutenberg Blocks. These types of themes require the use of the new (and still in development) Full Site Editor. 

The Site Editor is still being built, and block themes are in a nascent stage; they don’t yet offer the full gamut of features that will be available in the future. Block themes also require a very recent version of WordPress. How can we build themes which work with the classic dashboard to today and will continue to work with the Site Editor when it is more fully featured? This is the problem Universal themes are seeking to solve.

What is a Universal Theme?

Universal themes are an attempt to bridge the gap between the classic themes and block themes, by adding some layers to a block theme to make it work.

A Universal theme is a block theme that can use the Full Site Editor but can also be configured in a more classic way.  That means that you can use classic WordPress tools, like the Customizer, Menus and Widgets dashboards as well as the Site Editor.

Templates

Block themes load templates from the block-templates directory. However classic themes load them from the root. To ensure that we don’t end up duplicating code and that users can move between the Classic Dashboard and the Site Editor, we use the function gutenberg_block_template_part inside our classic templates. For example header.php:

<header class="wp-block-template-part">
	<?php echo gutenberg_block_template_part( 'header' ); ?>
</header>

Internationalization

Because block themes use html templates, its not possible to translate any copy inside them. In most cases we can avoid putting copy inside our templates, but there are some cases where it is impossible, for example the 404 page.

In these cases we are simply providing a classic template instead of a block template so that the strings can be translated. We can avoid any issues of code duplication by using the approach described above for templates. Here’s the 404.php from Blockbase:

<?php
/**
 * The template for displaying 404 pages (not found)
 *
 * @package Blockbase
 * @since 1.1.1
 */
get_header();
?>
	<main class="container-404">
		<h1 class="has-text-align-center has-medium-font-size"><?php _e( 'Oops! That page can&rsquo;t be found.', 'blockbase' ); ?></h1>

		<p><?php _e( 'It looks like nothing was found at this location. Maybe try a search?', 'blockbase' ); ?></p>

		<?php echo do_blocks('<!-- wp:search {"label":""} /-->'); ?>
	</main>
<?php
get_footer();

Fonts & Colors

Global Styles allows themes to customize their font and color options via theme.json. This gives universal themes a way to modify the fonts and colors in a theme, by modifying theme.json. In Blockbase we have attached some hooks to the font and color controls in the Customizer so that when you modify them the changes are made in theme.json. This gives us a single source of truth for these settings.

Blockbase

We have created a universal theme called Blockbase, which can be used as a parent theme; any child themes created with Blockbase will automatically be universal themes. You can learn more about Blockbase at blockbasetheme.com.

Coda

Universal themes are a temporary measure. As the Site Editor continues to improve and more features are added, the need for universal themes will diminish. These wrappers will be made obsolete and in time universal themes will become block themes.

• Review the Make Themes summary of theme features in 5.8.
• Read the Dev Notes on introducing theme.json and layout and content width for more specifics about block theme updates. 
• Check out an updated scope of remaining site editing projects to get a sense of what’s to come beyond 5.8. 

Curate your information

Since block themes are currently evolving along with the features to support them, it’s helpful to start by figuring out what will help you stay up to date with the latest happenings, as that makes sense for you. Here are a few options:

• Check out a summary of ways to keep up with full site editing to choose your own adventure.  
• Read the Gutenberg + Themes Roundups to get the latest & greatest information for anything cutting edge.
• Join the monthly Block theme meeting to discuss block themes, ask questions, give feedback, etc. 

Dive into resources

Outside of knowing the latest, it helps to know what the best practices are to follow. The following should give you great places to start: 

• Block Theme Documentation is currently outlined with a Learn WordPress course planned and a discussion underway about future documentation.
• Carolina Nymark created fullsiteediting.com that walks you through how to set up a block theme. 
• Review the current posts on this very site focused on all things block theme building. 

Learn from and with others

Since this is an area that folks across the WordPress community are diving into, there are some fantastic ways to keep in touch with what others are experimenting with, how they are solving problems, how they are getting started, and more. Especially during a time where we can’t meet up and look over someone’s shoulder at a WordCamp, hopefully these resources help bridge that divide even a tiny bit. 

• Check out the Theme Experiments Repo to see what others are building/doing to get started. You can even quickly create a blank theme to get started using resources within that repo. 
• Review previous demos/walk throughs: Marcus has some great block theme videos to check out that show him learning as he goes & Helen has a 3-hour long video of her doing the same. 
• There was a recent hallway hangout around the concept of Universal themes that might be of interest to view, especially if you’re a theme shop. Here’s a write up about the concept as well.
• If you’re keen to help explore and give feedback on theme.json, there’s a call for testing with the FSE Outreach Program that you can follow along with a recording of a great hallway hangout about theme.json and the test itself. 

While these are the resources we found most useful, we’d love to hear from you too. What resources have been helpful for you to explore block themes and the various pathways leading up to full site editing? Share in the comments so we can all learn together. 

Global Styles Everywhere

Block themes use a theme.json file to define many aspects of the theme, e.g. color palettes and typography. Gutenberg provides a tool to edit these settings (called Global Styles). When a user changes these values in the Global Styles UI, the changes are not saved back into the theme.json file but instead are saved to a Custom Post Type (CPT) in WordPress. Because this CPT can be modified using WordPress APIs, this gives us the power to make changes to Global Styles without relying on the interface in Gutenberg.

This simple idea is the basis for the color and typography customization options we have added to our universal theme Blockbase. The rest is just implementation details…

Implementation details!

When the Customizer loads, we create two new sections:

1. Colors
2. Fonts

$wp_customize->add_section(
	'customize-global-styles-colors',
	array(
		'capability'  => 'edit_theme_options',
		'description' => sprintf( __( 'Color Customization for %1$s', 'blockbase' ), $theme->name ),
		'title'       => __( 'Colors', 'blockbase' ),
	)
);

$wp_customize->add_section(
	'customize-global-styles-fonts',
	array(
		'capability'  => 'edit_theme_options',
		'description' => sprintf( __( 'Font Customization for %1$s', 'blockbase' ), $theme->name ),
		'title'       => __( 'Fonts', 'blockbase' ),
	)
);

In each of these sections we create new settings and controls – each setting and control relates to a color/font option in Global Styles. We read the content of the theme.json file and use this to populate the settings in the Customizer. There is a helpful function in Gutenberg which merges together the theme.json settings with any user settings:

WP_Theme_JSON_Resolver_Gutenberg::get_merged_data()->get_raw_data();

We read in an array of color palettes from the theme.json file and display these inside the “Colors” section:

Previews

One of the powers of Global Styles is that it relies on CSS variables. This makes it very easy for us to update the Customizer preview when the controls are changed. Some simple javascript injects new values for these CSS variables into the page, meaning that the preview updates instantly.

First we bind a listener to the control:

// For each of the palette items add a listener
userColorPalette.forEach( ( paletteItem ) => {
	const settingName = userColorSectionKey + paletteItem.slug;
	wp.customize( settingName, ( value ) => {
		value.bind( ( newValue ) => {
			paletteItem.color = newValue;
			blockBaseUpdateColorsPreview( userColorPalette );
		} );
	} );
} );

This updates the global variable userColorPalette, which we then use to create our CSS variables:

function blockBaseUpdateColorsPreview( palette ) {
	// build the CSS variables to inject
	let innerHTML = ':root,body{';
	palette.forEach( ( paletteItem ) => {
		innerHTML += `--wp--preset--color--${ paletteItem.slug }:${ paletteItem.color };`;
	} );
	innerHTML += ';}';

	// inject them into the body
	const styleElement = document.getElementById(
		'global-styles-colors-customizations-inline-css'
	);
	styleElement.innerHTML = innerHTML;
}

Saving

Customizer settings are usually saved in a site option or a theme mod. Since we are building a universal theme, we need to save these changes into Global Styles so that they are reflected in the Site Editor. The easiest way we found to achieve this was to hook into the customize_save_after action, read the settings from the controls, and then update the Global Styles CPT with the new settings. This code is used to get and read the CPT:

WP_Theme_JSON_Resolver_Gutenberg::get_user_custom_post_type_id();
get_post( $user_custom_post_type_id );
json_decode( $user_theme_json_post->post_content );

Once you have the CPT in JSON form it’s simply a case of adding the new settings to it, and saving them back into the CPT:

$user_theme_json_post_content->settings->color->palette = $this->user_color_palette;

wp_update_post( json_encode( $user_theme_json_post_content ) );

Color Palettes

Color palettes are simply combination of color settings. When a user selects a palette we simply change all of the associated colors at once. This can be done with the Javascript API:

wp.customize.control( userColorSectionKey ).setting.set( color );

How can I use this?

The code above is just pseudo code, to explain the concepts. For a fully working example see Blockbase freely available in our free themes repository. This code has a GPL license and can therefore be copied and distributed freely.

However, if you are interested in building a universal theme I would encourage you to use Blockbase as a parent theme. This will mean you get all future improvements to your theme for free!

Ephitah

The Customizer gets a bad rap, and it’s true that it is clunky when compared to the direct manipulation that is possible with Gutenberg. Nevertheless, building these kinds of tools to update Global Styles without the framework of the Customizer would have been much more involved. There is some satisfaction in being able to take advantage of all the hard work that has gone into the Customizer in its final years!

Both blocks can now display a carousel of block patterns in their setup state, allowing users to choose between a menu of pre-designed versions of these blocks. These patterns can be bundled with your theme, so that users have a wide range of pre-designed header, query, and footer options available to choose from in the Site Editor:

The only difference between these and other patterns you’d build is that they include a special blockTypes property to let Gutenberg know which block to associate them with. Here’s a simplified example:

register_block_pattern(
	'theme/pattern-slug',
	array(
		'title'       => _x( 'Pattern Title' 'theme-slug' ),
		'blockTypes'  => array( 'core/template-part/header' ),
		'content'     => '<!-- Your Pattern Markup -->'
	)
);

The markup above specifies that this pattern should be surfaced for a Header template part block. The value there would core/template-part/footer or core/query if you were designing a pattern for those blocks instead. (This property also powers pattern transforms, but that’s a topic for another time).

Once you register a pattern that way, it will show up in the carousel for the specified block. It’s as simple as that!

There are already a few Query Loop patterns bundled with Core today that use this method, and the header patterns shown in the video above are actually from a Gutenberg PR I’m working on as well. I’ve prepared a quick code example using our in-progress Quadrat theme to show how they could be bundled — we definitely plan on including a handful of these sorts of patterns in our block themes moving forward.

https://github.com/Automattic/themes/pull/4104

When combined together, Header, Query Loop, and Footer patterns allow you to mix-and-match pre-designed sections to create your entire website. I’m truly excited to see not only how themes use this feature, but how the Pattern Directory might provide hundreds more options for these blocks. This feels groundbreaking for WordPress, and I can’t wait to see how it turns out.

Why block themes?

To take advantage of the Site Editor, themes need to be built out of blocks – this is why we need block themes. Block themes are an entirely new way of creating themes. Classic themes bundle all of the code needed to control the presentation and functionality of the site, with the theme itself. This often means that themes contain extra code to add features (e.g. a slideshow) as well CSS to control the layout.

With block themes, much of the theme’s functionality and presentation is provided by Gutenberg. This means that themes have a shared set of features and style rules, which brings several benefits for users:

1. The user experience for customising themes is more consistent.
2. When users switch themes, they won’t lose features, as Gutenberg provides the same features to all themes.
3. Users can mix and match aspects of different themes – e.g. the header of one theme with the footer of another.

There are also some benefits for developers:

1. Less code is needed to build a highly functioning theme.
2. Features that are used by many themes are now provided by the community, so that everyone benefits from the work done to maintain and improve them.

Can I use block themes today?

Block themes are the future and they will provide users great tools when Full Site Editing launches. For now, only those who are running the latest Gutenberg plugin and are willing to use experimental features like the Site Editor are able to use block themes.

Although the Site Editor is not yet ready, many aspects Full Site Editing will be available in WordPress 5.8. There is an opportunity to start building some form of block themes before Site Editor is ready.

Two editing modes

Full Site Editing brings a new editing mode for themes. For the sake of this article we’ll call the current editing mode, “classic” (Site Editor disabled) and the Full Site Editing mode, “FSE” mode (Site Editor enabled).

Users with classic themes will (probably) need to switch themes if they want to start using the Full Site Editing features. However if we can build block themes in a way that works in “classic” mode, then users will be able to take advantage of Full Site Editing once the tools are available. We have been calling themes like this “universal” themes.

Universal themes

The vision for universal themes is that a user could create a site using WordPress without the Site Editor enabled. Then, when the Site Editor is more mature, users could switch to using that, with all the extra tools that Full Site Editing will bring. 

A universal theme would work in both editing modes.  A user should be able to build a site in classic mode and switch to FSE mode when the Site Editor is more mature or when they are ready to try all the extra tools that Full Site Editing will bring. Changes to a theme in classic mode should be reflected when I enable the Site Editor.

Side note: It is not expected that users would toggle between these two modes. The plan will be for everyone to migrate to the Site Editor at some point. The intention of universal themes is to allow people to easily migrate from classic to FSE, not to encourage switching between them.

Future-proof

We that know that the Site Editor is coming. Building themes in this way will allow users to transition from classic themes to block themes when they are ready without requiring them to switch themes.

To achieve this we need to consider several aspects of themes:

• Templates
• Navigation
• Customization

Templates

In classic themes, templates live in the root directory and, by convention, `template-parts`. In block themes they live in `block-templates` and, by convention, `block-template-parts`. We could build templates for both classic and block themes and put them in the respective directories but the problem with this approach is that if users make changes to their templates when in classic mode they will not be reflected if they switch to the Site Editor.

To use the same templates when in classic and FSE mode we can put our templates in the `block-template-parts` directory. We can include them in our block templates in our template file like this:

block-templates/page.html:

<!-- wp:template-part {"slug":"page"} -->

For classic templates we can include the same file using `gutenberg_block_template_part`, which will execute `do_blocks` on this template:

/page.php:

echo gutenberg_block_template_part( 'page' );

This approach means that users can switch from classic to FSE mode without losing their changes.

Navigation

Classic themes use `wp_nav_menu` to render theme navigation elements, which can be customised in the Dashboard, or in the Customizer. On the other hand, Block themes rely on the Navigation block to display their navigation. A recent change to the Navigation block means that we can connect these interfaces together:

By passing the navigation block an `__unstableLocation` attribute with the location of the classic menu, we can display classic menus inside the Navigation block:

<!-- wp:navigation {"__unstableLocation":"primary"} --><!-- /wp:navigation -->

This allows us to edit menus in the Customizer and the Dashboard when in classic mode, and in the Navigation block when in FSE mode.

Sidenote: A short-coming of this approach is that once the navigation has been edited in FSE mode, it will not be possible to edit it in classic mode.

Customization

In classic mode, the Customizer is the main tool for editing theme settings. Aside from Menus (see above), by default the Customizer allows users to edit Site Identity and Homepage Settings. These are WordPress settings that are editable elsewhere in the Dashboard, and are also available to block themes. The exception to this is “Additional CSS” which is not editable when the Site Editor is enabled. The hope is that the Site Editor will allow users to edit their site directly so that they won’t need to use additional CSS.

Often themes add more customisation options – for example colors and fonts. Global Styles offers some of the same customisations. Using the Global Styles API it is possible to make changes to Global Styles in the Customizer. This would allow users to customise their site using both the Customizer and Global Styles. We’ve been playing with this idea in this PR: Quadrat: Add color customization.

Opting in and out of the Site Editor

One unresolved challenge for universal themes is how to opt-in users to the Site Editor. At present the Site Editor is enabled for all block themes, which includes universal themes (if your theme has a file in the location `block-templates/index.html` it will be treated as block theme).

To be able to launch universal themes before the Site Editor is ready, we will need a mechanism to temporarily disable it. There is more discussion on this issue.

What’s next?

At the moment universal themes are just an idea; there are still many unresolved questions about how we could achieve this vision. For an example of a theme that tries to take a universal approach see Quadrat.

Look out for more posts about this idea as we keep experimenting with it.

In the past when I’ve done a theme experiment like this, I’ve generally started with something like the emptytheme generator in the WordPress theme-experiments repository. This provides you with just the required files for building a block theme, so it’s a good minimal way to get started.

This time around, I used Blockbase. While it doesn’t yet include a quick generator script like emptytheme does, there is one in the works. In lieu of that, I just created a child theme like I normally would: by adding style.css, functions.php, and index.php files. I also copied over the child-theme.json file from the in-progress Quadrat theme, since I knew that would get me started.

My work in child-theme.json was very brief — I just changed a few variables and used Blockbase’s compiler script once. Then I copied and pasted over the block style effects from the plugin mentioned above.

Once that was all in place, I jumped into custom templating. I created just two templates, plus a custom header that featured a video loop of me waving at the camera (but filtered into oblivion using the tools at photomosh.com). I used a “Warped and Stretched Photocopy” block style on the header’s text, and “Photocopy” style on the featured images. Combined together, this created a highly stylized look and feel, reminiscent of (for better or for worse) the old days of Flash animations:

This all worked pretty well in the editor too! Due to a combination of Gutenberg limitations and browser bugs, I ran into an issue getting my SVG filters loaded into the Site Editor’s iFrame, but aside from that, things looked just like the frontend:

The filters did work great in the post editor though, so I can show you how that’s supposed to work by loading the header there:

In the end, the filters bug is not really a fault of the theme, and something I’m sure I could resolve if I choose to devote some more time to this exploration.

The theme is obviously a little over-the-top, but that was really the point of the experiment! I’m amazed I was able to fold my earlier block styles work into such a distinctive, full-featured theme with minimal effort.

Overall, I found that the benefit to using Blockbase was peace of mind. Compared to starting fresh or using emptytheme, Blockbase ensured that I had a fully-functional block theme immediately. It already contained extra templates for pages like 404 and search, and it was full of little CSS fixes for things that full-site editing just doesn’t quite support yet.

This eliminated a lot of extra busywork, and allowed me to dive right in and focus on the theme-building aspect that’s most exciting for me: the theme’s design and creativity.

The code for the theme is over here in case anyone would like to poke around:

https://github.com/Automattic/themes/tree/try/glitchy-theme-experiment/glitchy

I look forward to seeing Blockbase spark the creation of many more themes!

How do block themes work?

Block themes use templates made entirely of blocks. The layout is configured using a combination of theme.json and CSS. The settings in theme.json are used to generate CSS – this is part of the Global Styles feature. The theme CSS is added after the theme.json CSS and together these rules define the layout for a theme. If you’re just getting started with block themes, this guide should help.

Can I style my whole theme with Global Styles?

Global Style allows us to set styles for some aspects of the theme, but many common customisations are not yet available. We are actively helping to add more customisations to Global Styles, but in the meantime we have been working on a mechanism to define a lot more theme styles in a custom section of theme.json, until they are available in Global Styles.

The result of this work is a new theme called Blockbase, loosely based on the classic theme Blank Canvas. This block theme attempts to make all the common theme styles configurable in theme.json, and provides the CSS needed to make them work until the blocks themselves support these settings. As more of these configurations are added to Global Styles, we will remove the corresponding CSS from Blockbase.

Can Blockbase be used to build more block themes?

We are currently using Blockbase as a parent theme for all of our block themes; in time we hope that it won’t be needed. This means that child themes only need to define their settings in a theme.json file, and the parent theme CSS will adjust to these settings. This approach gives us an agreed standard when configuring block styles. It also will make it trivial to move to the Global Styles implementation when that becomes available in core.

Blockbase is intended to be a representation of all the theme style settings that we believe should eventually live in Global Styles and be configurable by users. Some themes need customizations beyond what would be possible with Global Styles. These more unique styles continue to be defined in the theme CSS file.

How it works

Style configurations live in the “styles” section of theme.json. Rules can be defined for both “blocks” and “elements”, and these will be interpreted by Global Styles and generate the appropriate CSS.

The theme.json file also contains a section for “custom” configurations, inside the “settings” property. Settings defined in “custom” are output by Global Styles as CSS variables. These variables are used by the theme CSS files to style blocks and other elements.

Child themes of Blockbase are able to redefine these CSS variables by setting different values in its theme.json. The child theme inherits the Blockbase CSS, but with the new CSS variables defined in theme.json.

To avoid a child theme needing to redefine every value in the theme.json file, child themes can create a child-theme.json file and a script will generate a theme.json file, taking the defaults from Blockbase and updating it with the new values from the child theme.

This mechanism will be particularly useful as more customizations are added to Global Styles; in many cases it will only be necessary to update Blockbase itself and rebuild each child theme, to update the theme.json files. You can find out more about this in the theme’s readme file.

Code size

Aside from the benefits outlined above, we have also found that this approach to building themes has resulted in a drastic reduction in the amount of code we need to write for both the parent theme and any child themes. As much as possible we rely on the styles that come with Gutenberg, and only add extra rules where necessary. Blockbase CSS is, at the time of writing about 1000 lines of code, whereas Seedlet CSS is over 4000.

As more of these customizations are added to Global Styles, we will be able to remove the corresponding CSS from Blockbase, so we anticipate the size of the theme CSS to reduce over time.

How Can I Use This?

Blockbase is available on the Automattic themes repo. If there is interest from others in using this approach to build themes we can investigate making it available as an npm package for others to use.