Mastering theme.json: You might not need CSS

I think I’m getting lazy. And I don’t think the WordPress Global Styles system is helping. I can just throw a few values in theme.json or a variation’s JSON file, and they’re automatically scoped, only targeting the necessary elements or blocks in the generated CSS. It’s a pretty neat system.

We’re very much in the early days of this era of block theming, which will be a long one. And I still, certainly, write my fair share of CSS—WordPress doesn’t do all the things just yet. But with each new major WordPress release, I find myself writing less and less actual CSS and using JSON to handle styles.

Personally, I’d rather just write CSS. Mostly, because I have spent years crafting solid styling systems. I can use and reuse to get what I want. But also because I’m a developer. And that’s what developers do.

But this isn’t about me. It’s about the millions of people who use WordPress and don’t know a bit of code. It’s about empowering them to style their own sites, taking us from democratizing publishing to democratizing design.

The real winners of the Global Styles Engine in WordPress are the users. So it doesn’t matter as much where I think styles should live as it does making a user’s life easier.

In this article, let’s go over some tricks and shortcuts I use to build block themes—you might think of it as a sort of an in-case-you-didn’t-know-it post. 

I’ll also tell you when you absolutely have to fall back on that ol’ reliable CSS.

Leveraging JSON to add global settings and styles

The on-ramp to styling themes is the Global Styles system. You’ll often see this called theme.json. In the early days of the Block Editor, theme.json was the only place you could add style rules with JSON, so that became the shorthand for the engine itself. But today, things have changed.

Now, just weeks ahead of WordPress 6.7, styling can go into several types of JSON files, and we’ll dive into each of those below.

For more information on how this system works, refer to the Global Settings and Styles documentation in the Theme Handbook.

A quick theme.json overview

The primary styles for a WordPress theme should live in a file named theme.json in the theme’s root folder. Think of this as the theme’s foundational set of styles. Whenever a situation calls for a more specific set of styles (e.g., user styles, block style variations), they are merged with and outrank those in theme.json.

The theme.json file in your theme can be broken down into these top-level keys:

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"settings": {},
	"styles": {},
	"customTemplates": {},
	"templateParts": {},
	"patterns": []
}

For the purposes of this tutorial, we’ll focus on two of these:

• settings: An object for defining what design tools are available to the user in the UI, but you can also use it to add presets (i.e., CSS custom properties).
• styles: An object for defining root, element, and block styles, with each option mapping to CSS properties.

You probably know the basics of using theme.json, so let’s get right to adding some of that power and finesse that doesn’t need custom CSS.

Fun with style variations

Right now, the Block Editor will let you use four types of style variations in your theme:

• Theme (or “Global”): Can overwrite every aspect of the theme.json file, including settings, styles, and other top-level keys.
• Color: Can overwrite color settings or styles.
• Typography: Can overwrite typography settings or styles.
• Block: Can overwrite styles for a specific block and its nested blocks and elements.

You must place any custom style variation JSON file under your theme’s /styles  folder. There is no required naming or organizational convention, but I recommend a nested folder structure that looks similar to this:

/styles
	/block
		/variation-filename.json
	/color
		/variation-filename.json
	/theme
		/variation-filename.json
	/typography
		/variation-filename.json

Theme style variations

Theme—often called “Global”—variations have been the most common type of style variations for themes. Essentially, they are alternative versions of the primary theme.json file and can do everything theme.json can do.

Here’s a page in the Site Editor that uses the default theme.json file (no variation selected):