Using block style variations in WordPress to allow shared modifications later on

One of the major gripes which we “extenders” of WordPress have—those of us who build sites for ourselves or for clients and extend the core functionality—is the difficulty of what happens later down the road, when we (or a client) decide that we want to modify the design of all of the image captions, or of the titles, or of an HTML element used semantically. Such was the case in a multisite project I’ve developed, when the client asked for the “sublines” (a short piece of text placed above the title elements) to use a different font family.

As developers will know, there is no semantically-correct element which we can use here: many misuse one of the heading elements h1–h6, which leads to invalid HTML markup. (For example, an h3 should only be used to mark up a subtitle within a section which already has an h2 as its main title.) For this reason, we most commonly use a paragraph block with a custom style applied. If we use the WordPress Block Editor, then this has, until recently, meant a manual selection of a font family through the editor’s typography controls.

More experienced developers will often have used Block Styles for this purpose and added their own CSS to apply to elements with e.g. .is-style-subline. This has worked well for the past few years, but has caused problems occasionally when the custom CSS has overridden WordPress’ own CSS.

In order to better improve compatibility with the Block Editor, we can now add the preset styles for this subline element using JSON: either by adding the rules to the theme.json file, or (as I prefer) in a separate file within the styles folder of the Theme.

In this JSON file, I can define which specific styles should be applied to the block in the editor. The remaining rules fall back to the standards defined in the global Styles section of the Site Editor or by WordPress Core itself.

Here’s an example configuration.

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"title": "Subline (small)",
	"slug": "subline-small",
	"blockTypes": ["core/paragraph"],
	"styles": {
		"typography": {
			"textTransform": "uppercase",
			"fontSize": "var(--wp--preset--font-size--small)"
		}
	}
}

This adds a style variation to the editor, which allows a user to select the predefined typography for this element with a single click. The user can then override any of the more specific settings as appropriate: although the font size is usually “small”, the user can choose any font size manually if absolutely necessary.

I have built up a lot of block patterns in the parent theme for this installation and because many of them feature a paragraph with this subline style applied, I’ve created a block pattern file specifically for it.

<?php
/**
 * Title: Subline (small)
 * Slug: sht/subline-small
 * Inserter: no
 */
?>

<!-- wp:paragraph {"className":"is-style-subline-small"} -->
<p class="is-style-subline-small">Untertitel</p>
<!-- /wp:paragraph -->

This snippet cannot be inserted using the block pattern inserter because of the “Inserter” definition but can only be referenced within larger patterns by using the WP Pattern tag.

<!-- wp:pattern {"slug":"sht/subline-small"} /-->

So, what’s the point of all this? Simply put, I have created a predefined style rule for all of the sublines across the site and all of the elements will look the same. If the client then wants to change the style of all sublines later on—for example to colour them or change the text transformation—then this can be achieved by modifying the definition in the JSON file (which respects most of the definitions available in theme.json). Any specific changes the editor has made over and above the preset definitions will not be overridden by changes in the JSON file.

In this project, I can also add a different set of rules for the same element in a different site in this multisite installation by duplicating and modifying the JSON file in the child theme. All I have to do is ensure that the JSON slug (and file name) remain the same.