We’ve been experimenting with a new WordPress theme scaffold that’s extremely block-centric. It’s not a full-on “block theme”, but it’s trying to be as close to one as you can get while still maintaining access to PHP templating for things like archive pages and the website header (sorry, navigation menu block but you need to go home).

We’re putting a lot of attention into making theme.json the one source of truth for all of our styles and design tokens. Then we’re pulling values into our SASS from theme.json using some fancy trickery. (To see a similar but different approach, check out Blackbird Digital’s theme scaffold.).

Working with theme.json is just… weird. CSS opinions inside of JSON objects? Eh, not my favorite. (And adding any arbitrary CSS into JSON? Sort of ruins the point.) I’ll take a big fat .scss file full of $sass_variables any day. That said, I totally see the vision here. Seeing your predefined colors, spacing, and more inside the block editor is fantastic.

That said, what happens when you’re styling content that was built outside the block editor?

Note that theme.json is essentially built for styling “blocks”- which is an important distinction. It’s great if your entire website is made of blocks. It’s not great if your website includes things that aren’t blocks, like, you know regular ol’ HTML.

According to the docs, you can generate styles for HTML elements with theme.json. But it’s not what you think it is.

The elements key on theme.json supposedly lets you define default styles. You can add default font and color choices to your heading elements, for example. It also lets you add default styles for links and buttons.

For buttons, though, it’s not actually styling the button element or even an input[type=submit], it’s just throwing the styles on a custom class: .wp-element-button. This means you have have the ability to add the class to the element in your HTML.

I’m using Automattic’s LMS plugin with an FSE theme, and it loads the wp_login_form() on the front of my website. The FSE theme I’m using has a great design for buttons and even for the search input field, but none of this translates to my login form:

The inputs and buttons don’t match the rest of the site. And you can’t use theme.json to add global styles for any generic HTML, like input or table elements. It only supports a few specific elements.

What does this mean? Its still up to plugin developers to include their own styles for things, or use fancy tooling to try to pull from theme.json where appropriate- neither being an optimal solution. This also becomes a documentation problem.

Quick aside: the only good documentation I’ve been able to find is Carolina Nymark’s fullsiteediting.com. I find myself coming back to this resource constantly, especially the chapters on theme.json.

When you read any docs about theme.json, it’s usually in the context of full site editing, which means that almost all of the documentation for it assumes you’re styling blocks and build a block theme. Even parsing what features work in block themes and which ones work in hybrid themes is difficult.

When theme.json works out- it’s fantastic! It’s machine-readable styling that turns the block editor into a very controlled design tool.

But even if you are using the site editor to build your site, the plugins you’re working with might not be. It makes me wonder what this will look like in a few years. There’s so much talk around theme developers embracing the block editor, but that’s only half the picture.