Configuring Theme Design with theme.json

Starting in WordPress 5.8, a new tool — “theme.json” — is available to use in your theme. Maybe you’re hearing about it for the first time, or maybe you’re testing and developing themes with it already. Either way, I’m glad you’re here because it’s an exciting time for WordPress themes.

This post provides a quick introduction to this new framework, and describes what’s possible by sharing a few practical tips and examples.

What’s theme.json?

Technically, theme.json is just a file that lives at the top-level of a theme’s directory. 

Conceptually, it’s a major shift in how themes can be developed. Theme authors now have a centralized mechanism to tailor the WordPress experience for site authors and visitors. Theme.json provides theme authors fine-grained control over global styles, block styles, and the block editor settings.

By providing these settings and controls in a single file, theme.json provides a powerful framework that brings together many aspects of theme design and development. And as the block editor matures and adds more features, theme.json will shine as the backbone for themes and the editor to work together . 

Why Use it?

It’s the future! But if you’re like me, you might need something more tangible to be convinced. Here are a few reasons why you might use theme.json today:

• Control editor settings like color, typography, spacing, and layout, and consolidate where these settings are managed.
• Guarantee that styles apply correctly to blocks and elements across your site.
• Reduce the amount of boilerplate CSS a theme used to provide. Theme.json won’t replace your stylesheet completely — there will be instances where CSS is needed to give your theme that extra flare (transitions, animations, etc.). But it can greatly reduce the base CSS needed from the theme.

How do I use it?

The rest of this post demonstrates a few theme.json configurations you can try out. The examples use the tt1-blocks theme.json — the block-based version of this year’s default theme. 

If you’re starting with an existing theme, you might try copying a theme.json from the WordPress/theme-experiments repository (for example, the fse-tutorial theme by @poena) and adding it to the root of your theme’s directory.

Change the typography settings of your site globally

"settings": {
	"typography": {
		"fontSize": "30px",
		...

Making the change above in theme.json would result in the following updates to your theme’s body typography styles (before and after):

Changing the base color settings of your site globally

"styles": {
	"color": {
		"background": "#ffc0cb",
		"text": "#6A1515"
	},
	...
}

Changing spacing / padding settings on specific blocks

"styles": {
	"blocks": {
		"core/code": {
			"spacing": {
				"padding": {
					"top": "3em",
					"bottom": "3em",
					"left": "3em",
					"right": "3em"
				}
			}
		}
	}
}

Set a custom color palette in the editor for specific blocks like a button

"settings": {
    "blocks": {
		"core/button": {
			"color": {
				"palette": [ 
					{
						"name": "Maroon",
						"color": "#6A1515",
						"slug": "maroon"
					},
					{
						"name": "Strawberry Ice Cream",
						"color": "#FFC0CB",
						"slug": "strawberry-ice-cream"
					}
				]
			}
		}
	}
}

Enable and disable typography controls

In the following example, the ability to supply a custom font size and line height for all heading blocks is disabled:

	"settings": {
		"blocks": {
			"core/heading": {
				"typography": {
					"customFontSize": false,
					"customLineHeight": false
				}
			}
		}
	}

What’s Next?

I hope this gives you a sense of what’s possible and where themes are going. The above examples just scratch the surface of what kinds of theme design configurations are possible, and I’m very excited to see what theme authors create.

If you’re interested in learning more, here’s the developer note on theme.json, and here’s the documentation for theme.json in the handbook.

Thanks to @kjellr, @chanthaboune, @priethor, @annezazu for helping with and peer-reviewing this post.