The Style Book: a one-stop shop for styling block themes

If you’ve looked at even a single block theme since the concept landed in WordPress 5.9, you have likely noticed that almost none of the styling of these new themes happens in CSS files. Instead, block themes use the machine-readable theme.json format. 

And theme.json has been growing, too. It supports more styles with every release of WordPress (at this writing, 6.3 is heading for beta in a matter of weeks), and it integrates with the editor interface more tightly. 

You can see the myriad improvements most clearly in the evolution of the Global Styles interface of the site editor, which got a one-stop styling shop on WordPress 6.2. 

Say hello to the Style Book

A key feature of 6.2, the Style Book is one place where you can set all the styles for a site, at minimum, or build out a whole theme, if you want, and add a set of variations that your users can change with a single click.

A quick look at  block styling

As you probably gathered above, in block themes, you define settings and styles in theme.json. Because json files are machine-readable, as you set your block theme settings and styles, they show up in the Site Editor UI. Then, your users can change the site’s look and feel without having to write any CSS.

You can find a lot more details in this core blog post.

Styling with theme JSON

You can do a lot in theme.json. Beyond configuring styles and settings, you can also enable, disable or define features from color palettes and typography to completely custom widths of every container on your website.

{
  "version": 2,
  "settings": {
	// presets definitions
	{"appearanceTools": true,
    "color": {
   	 "palette": [
   		 {
   		 "color": "#ffffff",
   		 "name": "Base",
   		 "slug": "base"
   	     	},
   		 {
   		 "color": "#000000",
   		 "name": "Contrast",
   		 "slug": "contrast"
   		 },
        	{ ... },
        	{ ... }
        	}
  },
  "styles":{
	// styles definitions
    	"color":{
        	"background":"var(--wp--preset--color--contrast)",
        	"text":"var(--wp--preset--color--base)"
     	},
   	"typography": { ... },
   	"layout": {... },
   	{ ... },
   	{ ... }
  	// block-level style definitions
    	"blocks": {
   	   . "core/group": {
   	    	"color": { ... },
        	},
        	{ ... },
        	{ ... }
    	}
	},
  // elements definitions
  "elements": {
    	"button": { ... },
    	"h1": { ...},
    	"heading": {
           	"color": "var(--wp--preset--color--base)"
    	},
    	{ ... },
    	{ ... }
	}
}

You use the settings section values to configure Site Editor’s global/block-level styles and define style presets. In the style section, you use the setting presets as CSS custom properties to style specific elements and blocks, especially in cases where you want to override global style.

In a fight, who wins?

You can save yourself a lot of time and repeated effort if you remember these next two sentences.

The theme.json overrides the default WordPress styles. 

User  values—the ones they put in the settings fields—override both to reign supreme. 

The WordPress style engine API consolidates styles definitions from multiple sources (core, themes, and user) and generates the theme’s CSS classes and custom properties.

This theme.json documentation and learn video give more information about settings, styles, and global styles.

Going global: making templates and more with the Global Styles UI

You can save yourself and your users even more time, and wind up with a design whose parts and pieces all go together, with templates and template parts. You can build templates for posts and pages, and vary your designs for archives and even custom post types. Template parts let you design the header, footer, and blocks, and then use them in your templates so you don’t have to rebuild them again. You’ll find template parts and reusable blocks in the new Library section.

Here’s a screenshot of the latest Editor > Design navigation panel. Notice that you can see the items on the left, then select and work on them in the main window.

In the screenshot below, I used the Global Styles to change the background and text color of the Pages templates. You can get there via Pages > Sample page.

Pulling it all together in the Style Book

A Style Book is the one tool in your design toolbox that lets you see how your settings work when they’re all together. This GitHub ticket explains how the feature was born:

It’s not uncommon to find yourself styling a block in Global Styles without that block being present on the canvas. Consequently, you’re left unsure whether the desired outcome is achieved. One solution to this could be providing a dedicated document containing all blocks, that users can observe on demand.

That was the beginning of the “Story Book”. Introduced in Gutenberg 14.8, it merged into WordPress 6.2. And lets you see  all the blocks on your site on a single page. What’s more, you can change any element, right there and on the fly, with a live preview.

This Learn WordPress video will show you how to use Style Book and its most useful features.

And now there’s a stylebook navigation button in the left-hand Styles navigation panel in the site editor Browse mode, so you can compare different styles fast against the Style Book.

Using the Style Book in the real world 

You can get to the Style Book from the admin dashboard, under Appearance → Editor. Then open the (Global) Styles panel which will bring up the new style panel, called Style Book (Illuminati eye icon). If you click the Style Book button, you will see a block preview window.

The Style Book preview window contains six tabs: text, media, design, widgets and theme. Under each tab you’ll find blocks you can style at both the global and per-block level. Here are some examples:

• Text: headings, paragraph, list, quote, code, pull quote, table, others.
• Media: image, gallery, audio, cover, file, media & text, video,
• Design: button(s), columns, group, more, page break, separator, and others.
• Widgets: archives, calendar, categories list, custom HTML, comments, latest posts, page list, RSS, search, social icons, tag cloud
• Theme: Navigation, site logo, site title, site tagline

Again, you can change the site-wide (left panel) or block-level (right panel) style, and a live preview shows you exactly how everything looks.

Changing Global styles to change your whole site

You can change the whole site style, like the typography (font type, size, etc.), color scheme, and page layout, and see the changes take effect live.

Below, the site’s background color changes from white to luminous vivid amber (left panel). You’ll see the changes live in the preview window and then make other changes, maybe to other colors or typography, globally, to go along with the new background.

Above, you can see that the text fonts in the right panel have changed from the default to Open Sans (right panel).

Global custom CSS

Though the editor gets more comprehensive with every release, there are some things you just can’t do in theme.json and the Site Editor Styles UI, even in a block theme. (Ed. note: Think about the most modern or edge-case CSS: it will be a while before you can wrap text around an irregular shape in theme.json.)

For cases like those, WordPress 6.2 added custom CSS for block styles. (It’s a global feature, so that text wrapping around the picture probably needs to be on a recurring site element.)

It’s called  ‘Additional CSS‘, and it’s under the ‘Styles actions‘ (three dots) menu, next to the style book eye icon (left panel).

In the right panel, the bisque color (#FFE4C4), added with custom CSS, overrides the default white background of the entire site.

Styling at the block level for attention to details

You will mostly use per-block styling to make certain block styles stand out from the rest of the site. 

Below, a Quote block gets a bigger font size and italic font style to stand out from the rest of the site’s text. The change only affects each quote block instance, but not any other blocks.

If you’d like to explore these styling rules in more depth, a great way to do it is to download some block themes from the theme directory that use block-level styles, and play with changing the styles in a local environment. Twenty Twenty-Three is a great one, and you can go back and forth between theme.jason and the settings to see what gets saved where.

I also recommend checking out customizing core block variations and an ongoing conversation around multiple styles per block. 

Per-Block Custom CSS

Beyond the global custom CSS feature, you can also add custom per-block CSS in the Style Book. Each block has an “additional CSS” box at the bottom of the style book panel. (You may have to scroll to see it.)

Below, a pull quote block gets custom CSS that changes  border color and font size appearance (size, weight, style).

Now, as much fun as it is to customize absolutely everything, it’s a better practice to define block styles in theme.json. (This Dev Blog article explains how to apply per-block CSS with theme.json.) 

Then, use custom CSS only where you really need it.

---

A few random notes:

To me, the Style Book feels a lot like doing design with the live preview extension in VSC editor or your favorite browser DevTools.

And like making changes in the Dev tools, your changes to the styles are temporary until you save them with the  “Apply globally” feature (#46965) to make the changes permanent. Then you have the option to export your theme, with its changes, with the export feature or Create Block Theme plugin.

Want to keep some blocks out of sight, in the inserter and the preview? This core blog post tells you how. 

Finally, it’s worth checking out this 2021 US WordCamp talk on Creative Use of Block Styles by Kjell Reigstad (starts 6:35:46 and ends 7:30:17). I hope you can unleash your own weird block styling creativity by trying out the new Style Book feature.

Props to @bph, @greenshady, @marybaum for feedback and review.