Phase 2 of Gutenberg introduces Full Site Editing to WordPress; to make this possible, we need a new way of building themes – using blocks.

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.

Block Patterns, or simply patterns, enable theme developers to create custom blocks that are compositions of blocks provided by the standard block library, and if desired, with additional design flourishes. For example, Twenty Twenty One includes support for blocks designed with overlapping images and text, among others. In the blocks version of Twenty Twenty One, these will be registered as patterns within the theme.

Repeatable design patterns

Unlike templates, patterns are defined in PHP in a way that might be more familiar to experienced theme developers. We can define them in the functions.php file of our theme, or a file that is included there.

First up, as a matter of good practice, we register a category for our patterns using the register_block_pattern_category function. By categorising our patterns, we can separate them from other patterns such as those registered by WordPress core, and other third-party plugins:

register_block_pattern_category(
    'theme_blocks',
        array( 'label' => esc_html__( 'Theme Blocks', 'theme-blocks' ) )
);

Now we can start adding our patterns with the `register_block_pattern` function. The parameters for this function are the pattern name as a string, and an array of properties to be associated with the pattern. This array comprises a title, content, description, categories, keywords and viewport width. Putting this together, a simple pattern can be registered like this:

register_block_pattern(
    'theme-blocks/pattern-name',
        array(
            'title'         => esc_html__( 'Pattern Title', 'theme-blocks' ),
                'categories'    => array( 'theme-blocks' ),
                'viewportWidth' => 1024,
                'description'   => esc_html_x( 'A description of what is in the pattern', 'Block pattern description', 'theme-blocks' ),
                'content'       => '<!-- wp:columns ... -->'
        )
);

Most of what we’re doing here is self-explanatory, however the content property may look less familiar. This property contains the raw HTML content for the pattern. What we add here follows the same convention as template parts.

Getting real

It’s easier to think about what this contains if we work with a real pattern, so let’s take Twenty Twenty One’s Overlapping Images pattern. The content looks like this:

<!-- wp:columns {"verticalAlignment":"center","align":"wide","className":"is-style-twentytwentyone-columns-overlap"} -->
    <div class="wp-block-columns alignwide are-vertically-aligned-center is-style-twentytwentyone-columns-overlap">
            <!-- wp:column {"verticalAlignment":"center"} -->
                <div class="wp-block-column is-vertically-aligned-center">
                            <!-- wp:image {"align":"full","sizeSlug":"full"} -->
                                    <figure class="wp-block-image alignfull size-full">
                                            <img src="' . esc_url( get_template_directory_uri() ) . '/assets/images/roses-tremieres-hollyhocks-1884.jpg" alt="' . esc_attr__( '“Roses Tremieres” by Berthe Morisot', 'tt1-blocks' ) . '"/>
                                        </figure>
                                <!-- /wp:image -->
                                <!-- wp:spacer -->
                                    <div style="height:100px" aria-hidden="true" class="wp-block-spacer"></div>
                                <!-- /wp:spacer -->
                                <!-- wp:image {"align":"full","sizeSlug":"full"} -->
                                    <figure class="wp-block-image alignfull size-full">
                                            <img src="' . esc_url( get_template_directory_uri() ) . '/assets/images/in-the-bois-de-boulogne.jpg" alt="' . esc_attr__( '“In the Bois de Boulogne” by Berthe Morisot', 'tt1-blocks' ) . '"/>
                                        </figure>
                                <!-- /wp:image -->
                        </div>
                <!-- /wp:column -->
                <!-- wp:column {"verticalAlignment":"center"} -->
                    <div class="wp-block-column is-vertically-aligned-center">
                            <!-- wp:spacer -->
                            <div style="height:100px" aria-hidden="true" class="wp-block-spacer"></div>
                            <!-- /wp:spacer -->
                            <!-- wp:image {"align":"full",sizeSlug":"full"} -->
                                <figure class="wp-block-image alignfull size-full">
                                        <img src="' . esc_url( get_template_directory_uri() ) . '/assets/images/young-woman-in-mauve.jpg" alt="' . esc_attr__( '“Young Woman in Mauve” by Berthe Morisot', 'tt1-blocks' ) . '"/>
                                    </figure>
                            <!-- /wp:image -->
                    </div>
            <!-- /wp:column -->
    </div>
<!-- /wp:columns -->

To ease readability, we have added line breaks and indentation, but it’s worth noting that as this is ultimately just a string, when we come to registering our pattern, we can paste it in as a long line of text.

What we can see in this block is a mix of regular HTML, with the Block Editor’s pseudo HTML expressed as comments. Boiling it down, this markup contains two columns, with each one containing an image and some stylistic spacing. The images used here are just placeholders that can be modified by users in the editor, but it’s worth noting that any placeholder images used in a pattern must also be included in the theme assets.

You may note that in the markup above, it’s not entirely clear where the magic that makes these columns overlap occurs. This is achieved via a block style, and applied using the is-style-twentytwentyone-columns-overlap class.

Putting it all together

With all of this in place, here’s how we can now interact with our pattern in the site editor.

As you can see, we can find it by searching for “overlap” in the block editor. We can also browse all of our patterns in the block browser which is accessed by clicking “browse all” when selecting a block in the inline editor.

Why should I use patterns?

Hopefully this has helped you gain some understanding of what patterns are and how they work. Don’t worry if you’re still a little confused. There’s a lot to take in here and it’s something that makes more sense once you start making patterns. However, you may still be wondering why we’re talking about this and what the advantages are of using patterns.

Patterns are very helpful when users are trying to create more advanced layouts that have a greater sense of art direction than WordPress has traditionally provided. They’re a great way of breaking the monotony that can set in with long-form content, as well as helping users break the sense of creative block that is often felt when confronted with a blank page. As you can see in the patterns included with Twenty Twenty One, users have easy access to more versatile and visually interesting ways of presenting their content.

Next steps

To help consolidate your understanding, check out the full implementation of Twenty Twenty One’s patterns in the experimental block-based version of the theme.

Global Styles is a new mechanism for a theme to define a site’s styles. An important goal of Global Styles is to make it easier for users to change how their site looks without having to know or write any CSS.  These theme styles are defined via a json configuration file.  Importantly, it opens the way for users to modify those settings themselves in the Global Style Editor. 

Here you can find an empty theme JSON file to check out.  There’s a “Global” object with a “settings” block and a “styles” block.  You’ll find plenty of details about this JSON file here in the Gutenberg docs. Remember, work is ongoing so those details will change and grow. Q has built this very handy tool to get started with some generated JSON and get a head start on building your own theme.

Let’s take a look at some of those settings.

Global Settings

An important thing that we define at the global level is the palette of a theme. These are the colors that will be used throughout.
This will be in our settings portion of the JSON in the global.settings.color.palette collection and looks like this.

{“global”: { “settings”: {
	"color": {
		"palette": [
			{
				"slug": "blue",
				"color": "#0000FF",
				"name": "Blue"
			}
			…

With that defined there’s now a CSS variable –wp–preset–color–blue to be used throughout the theme.  And since it’s defined at the :root level you can use it throughout your theme’s JSON and CSS.  

This portion of the docs outlines the details of how that gets translated from JSON objects to CSS variable names. It follows the –wp-preset–{category}–{slug} pattern. 

And all of the colors in that palette are now at the disposal of users to apply across any block that supports colors.

Global Styles

With this palette in hand you can associate those colors to your site at the global level or per-block to get the theme styled right.  Looking toward the styles portion of the configuration we can adjust what colors we use for things like the background.  This setting for global.styles.color.background shows us how to leverage the color value we just created:

{“global”:{
	"styles": {
	    	"color": {
			"background": "var(--wp--preset--color--blue)"
		}
	}
	…

There are a lot more important things like typography that we can use these global styles and settings for (and even some custom values) and I’ll mention more below. But for now let’s go a little deeper…

Block Styles

Now we can get extra fancy.  The above showed us settings at a global level.  But using JSON we can now also assign these styles to blocks, simply by targeting the block’s ‘context’ instead of ‘global’ context:

…
“core/heading/h1”:{
	"styles": {
	    	"color": {
			"background": "var(--wp--preset--color--blue)"
		}
	}
	…

These values are rendered into CSS which applies that style to every h1 element.

h1 {
	background-color: var(--wp--preset--color--blue);
}

Though for some blocks these values are rendered into a class which is applied to blocks of that type.  For instance, Gutenberg turns the configuration for a “core/site-title” into:

.wp-block-site-title {
	background-color: var(--wp--preset--color--blue);
}

And should a user want to customize that further…

User Block Styles with the Global Style Editor

And finally the Global Style Editor in the Full Site Editor can be used to customize aspects of a block at the site level.  These values will supersede whatever is set in the theme’s JSON. 

Here a user is changing the Site Title’s background style via the Global Styles Editor.

Typography

Just like colors, defining typography for a theme has moved from the realm of PHP to some simple configuration.

Adding some objects to global.settings.typography.fontSizes looks like this:

{“global”: { “settings”: { “typography”: {
	"fontSizes": [
		{
			"slug": "small",
			"size": "15px",
			"name": "Small"
		},
	]
	…

And just like colors, defining the font sizes for the theme in this way will give users access to these same values in the editor. This makes it easier for them to reuse the sizes the theme designer defines. 

Font families can be defined in the same way:

{“global”: { “settings”: { “typography”: {
	"fontFamilies": [
		{
			"fontFamily": "sans-serif",
			"slug": "noserifsplease",
			"name": "Sans"
		}
	]
	…

Of course for non-system fonts you’ll also need to load the fonts.  This can still be done in the function.php file with wp_enqueue_style and should seem familiar.

…
wp_enqueue_style( 'mytheme-fonts', 'https://url/for/font-face/definitions' , array(), null );
…

Or include the font face in your style.css

@font-face {
  font-family: 'Epilogue';
  font-style: normal;
  font-weight: 300;
  src: url(https://url/for/font-file.woff) format('woff');
}

Now that the font is loaded it can be used in the theme.json file:

{“global”: { “settings”: { “typography”: {
	"fontFamilies": [
		{
			"fontFamily": "\”Epilogue\”, sans-serif",
			"slug": "epilogue",
			"name": "Epilogue"
		}
	]
	…

And now these font values can be leveraged either at the global level or at the block level in your configuration, crafting the look and style of the theme:

{“global”:{ 
	"styles": { 
		"typography": {
			"fontSize": "var(--wp--preset--font-size--normal)"
			“fontFamily”: “Epilogue”
			…

…
“core/site-title”:{ 
	"styles": {
		"typography": {
			"fontSize": "var(--wp--preset--font-size--normal)"
			“fontFamily”: “Epilogue”
			…

CSS

Not all styles can be expressed in the theme JSON. In time we hope that all common styles will be available, but there will always be some things that will only live in CSS (like animations). 

The theme’s style.css file will continue to be available as a way to express the style of a block-based theme.  Blocks can continue to be styled in CSS with classes.  But now you can use all of the swatches defined in your theme JSON throughout.  You can even define custom values like a global vertical spacer value.

Theme JSON
{“global”: { “settings”: { “custom”: {
	“spacing”: {
		“vertical”: “20px”
		…

Theme CSS
.wp-block-of-some-kind {
	padding-top: var(--wp--custom--spacing--vertical);
	…

Buy Why?

Defining styles in this way has some important advantages.  

JSON configuration is more accessible than writing PHP code and CSS.  There’s less to understand, less to type and less to potentially mess up.  This doesn’t “re-invent CSS as JSON” and the concepts of CSS certainly don’t go away because of this new tooling.  Nor will PHP.  But key concepts present in every WordPress theme can be expressed simply and in ways that can be leveraged in more ways than CSS alone.  This will make Theme development a simpler and faster process.

But perhaps one of the most important aspects of this new Global Styles system is the power it puts in the hands of people USING a Theme.  By using a Theme as a starting place and providing the tools to tweak things to suit their needs, without custom CSS and in a visually clear way is incredibly powerful.  This makes ALL themes leveraging these tools immediately more powerful.

Full Site Editing provides a new and exciting way to build themes, compared to how we created themes in the past. If you are new to this, there’s nothing to worry about, it’s simply a different way to create themes, leveraging the existing template hierarchy we all know and love.

A block-based theme can be customized from the Site Editor by making use of templates and template parts. A template is analogous to a template file in WordPress, following the same naming convention from the template hierarchy. You can edit templates from the Site Editor, or in the Block Editor under Appearance » Templates.

A template can contain individual blocks, or it can use reusable structural template parts, such as header, footer, and sidebar, for example. Template parts are not limited to the common reusable areas of a site, they can be virtually anything: a contact form, a call to action banner, or anything you want it to be.

When you update a template part from within a template, the template part is automatically updated everywhere (on all templates that use it). This works in the same way as reusable blocks, streamlining the process of working with templates.

The complexity of your theme will determine how many templates you need to create. You have freedom to use the Site Editor in any way you like, but for most themes you’ll want to create some template parts. 

Templates live in the theme code, inside the block-templates/ directory, as individual HTML files. Template Parts are stored in the block-template-parts/ directory.  Both templates and template parts are automatically loaded when WordPress loads, and are readily available in the Site Editor and Block Editor.

Templates and template parts can be stored as data, just like posts or pages. You can save a template and design your site’s behavior directly from the Site Editor, without having to provide the template HTML file in the first place.

Block templates

In the classic way of theming, we usually have functions that give us the different parts that make up a post, such as the_title(), the_content(), and so on. Block themes give us the same features using blocks directly!

For this purpose, some blocks have been made to be used with block-based themes. For example, you’ll most likely use the Site Title block in your site’s header while your single post template will most likely include a Post Title and a Post Content block.

As we’re still early in the process, the number of blocks is relatively small, but more will be added as the project evolves. For more information on this, you can refer to the official block themes reference.

When you build your template there are some important blocks you’ll want to use, which are covered in the sections below.

Site Level blocks

These blocks will be the same on every page – they get their content from the database. If you change the Site Title in this block, it updates everywhere on the site:

Navigation

Navigation is one of the most important parts of a website. The navigation block allows you to select menus you have previously created, or create new ones directly from the Site Editor.

If you have a header template part, this is a good place to add the Navigation block.

Query block

The Query Block is different from other blocks; its content changes depending on the context in which it’s used. 

On the front page, the Query block will show your latest posts (by default). On an archive / category / tag page, the block will show the relevant content for that page. 

There are several blocks you can add inside the Query Block:

You can combine these dynamic blocks with other blocks, for example columns, to change the layout of your posts and pages to your liking.

Dynamic blocks are blocks that use placeholders in the Site Editor, but will actually read information from the database when the blocks are rendered into the page. Therefore, it’s completely normal to not see the actual content when you are editing or inserting the block,  it will appear when the block is properly rendered.

Saving templates

After you have created all the templates and template parts in the Site Editor, you can save your templates to their corresponding HTML files. These can then be included in the theme.

Templates can be exported from the Site Editor, by clicking on the three dots button on the top-right hand side, and then clicking on Export.

After exporting, you get a ZIP file downloaded to your computer, with all templates and template parts. You can extract the ZIP archive and copy the block-templates/ and block-template-parts/ directories into your theme and you’re good to go!

When the template files are bundled with the theme, they will automatically be loaded when WordPress starts. There is no need to import or create the templates, they are loaded directly!

Template loading order

As mentioned above, if a template is saved into the theme code, it will be automatically loaded on startup. You can make edits to the template from the Site Editor. 

Once the template is saved in the Site Editor, the template file will no longer be used. This means that changes saved from the Site Editor take precedence over the content stored in the template HTML files.

Have in mind, that if you make edits to any of the templates provided by the theme, the template you saved with your changes will be used instead of the template on disk. This means, if the theme ships an updated version of the template, you will not be able to see the changes unless you delete the templates from Appearance » Templates.

Up next, we’ll be talking about Global Styles, stay tuned!

The rationale

With Full Site Editing on the horizon for WordPress, Theme creators need to start to learn how to make themes in a different way. Full Site Editing is sea change in the way that themes work.

When Themes were first added to WordPress, they were simple; just a few template files and some CSS. Over time, as users demanded more from WordPress, themes have grown to contain much of the visual functionality of the site. This has enabled WordPress to be extended as far as your dreams allow, and has contributed to the popularity of WordPress today.

This approach for themes has brought some challenges with it. With so much functionality baked into a theme, changing themes becomes a difficult thing to do. Not only will you lose some of the functionality of your site, you probably have to learn a new UI, since every theme works differently.

The Full Site Editing project aims to address these concerns by moving a lot of this functionality into the Block Editor. This will simplify Themes again so that they will become more like the initial implementation; a presentation layer over the top of the content.

One major benefit of this approach is that users will be able to edit parts of their site that before were only editable with code.

Full Site Editing is several projects combining to create fundamental changes to the way WordPress works.

The Block Editor

Fundamental to Block Themes is the Block Editor. Allowing users to express all their content as a Block brings us several benefits:

• A consistent UI for creating/editing content
• A reliable API for manipulating content
• A transferable way to move content around

With this foundation Themes can lean much more heavily on the user’s content than they have before. For example, themes can provide a ready-made collection of blocks that users can insert (Block Patterns).

The Site Editor

The Site Editor allows users to edit templates in the same way that they already edit content blocks. Templates are blocks, so all the things that users are comfortable and familiar with in the Block Editor work the same way in the Site Editor. This allows users to manipulate their site content and layout in the same way as the Post and Page content. No longer will users have to learn different interfaces for different themes.

Global Styles

Global Styles lets Themes express their design in a way which can be edited via the Block Editor and Site Editor. Rather than the design living in a CSS file, the most common settings will be defined in the editor itself, which gives the user the power to change them. This will enable users to modify the presentation of their site without writing any custom CSS.

Creating a Block Theme

The easiest way to start creating a new Block Theme is to use the empty theme template:

1. Clone the theme-experiments repo:
   git clone https://github.com/WordPress/theme-experiments.git
2. Run this php script to create a new Block Theme:
   php new-empty-theme.php

This provides the bare minimum needed to get started – in time, the amount of boilerplate code needed will shrink.

Next, install and activate the Gutenberg plugin – this will give you access to the features you’ll need for Full Site Editing.

Now when you enable your newly created Block Theme, the Side Editor will appear in the Dashboard sidebar, and the Customizer, Widgets and Menus will disappear.

Next Steps

To create your theme there are three areas to focus on:

1. Templates
2. Patterns
3. Global Styles

We’ll be expanding on each of these in our upcoming posts. Stay tuned!