Open survey for WordPress theme authors on JSON files and block themes – WP Tavern

WordPress 5.8 introduced a theme activation system to configure block settings, styles, templates, etc. This is done through a new theme.json file that authors can put at the root of their thematic files. Anne McCarthy, head of the FSE outreach program, announced a poll earlier today to get developer feedback on the feature.

“Since this new mechanism is a first step towards a comprehensive styling system for the future of WordPress, it’s important to hear from everyone who is currently using theme.json to learn more about how people are using this tool and what it might make sense to include in Core in the future, ”she wrote in the announcement.

The survey is open to all thematic authors who have used theme.json, giving them a chance to give their first comments and help steer the ship in the future.

Because I have worked a lot with this system over the past few months, I had a few things to say. Plus, I just like to take surveys related to WordPress. I also decided that this would be an opportunity to share some of my unfiltered thoughts from a development perspective on the current state of theme.json.

The following are my answers to the survey questions – well, the tidy version.

To note: This is a developer-centric article that might not be universally appealing to all of our readers. I have tried explaining some things in user-friendly terminology, but some prior knowledge of theme development may be required.


The first question in the survey is fairly straightforward. It asks you what is your experience with building block themes or using theme.json. It offers four choices (and an “other” option):

  • I built and launched block themes.
  • I have experimented with building block themes.
  • I explored using theme.json with a classic theme.
  • I used a block theme, but haven’t built one yet.

I chose the first option because I have already built two block themes for family and friends. These were simple personal sites that I already maintain for free – Honestly, I have to start charging. I am also working on a theme that I hope to publish publicly.

How it started and how it goes

The second question asks how we started with block themes and theme.json. The choices are between forking an existing theme, using the empty theme or starting from scratch.

Again, this is one of those things where I experienced every direction, but can’t remember the exact starting point. Most of my work came from forging a theme that I last worked on in 2019.

I plan to release this new theme for free at some point. I mainly expect the following:

  • Development of navigation blocks for settling in
  • The Post Author block to be divided into smaller blocks
  • A robust set of blocks linked to comments
  • Post Featured Image block to have a size option

I think I could realistically release a beta at your own risk of my theme today if these items were resolved.

Models and model parts

The survey asked which models and model parts the themes always include in their block-based themes. There was a free-form comment field – step on the soapbox …

I have a love / hate relationship with the block models right now. The static nature of HTML templates reminds me of a simpler time when theme development was less complicated. However, this is also a problem in a dynamic system.

I can’t remember the last time I built a traditional PHP based theme with more than one top level template: index.php. Dynamic parts have always been the guts of the thing, which are jig parts. With PHP, it’s easy to set a variable or use a function call to contextually load the parts of templates needed for the page a visitor is currently viewing on a site.

The block model system does not work like this. This essentially forces developers to break the Don’t Repeat Yourself (DRY) principle.

For example, if a designer wanted to display a different header template part for pages and posts, they would just have to create a header-page.php or header-post.php pattern in traditional themes. However, since the block model system is different, they now need to create two top-level models, single.html (post) and page.html, to accomplish the same.

This is a “bad thing” because theme authors have to duplicate all the rest of the code in each of the top-level templates. There is no way to contextually load different model parts.

To answer the question: I use almost every top model possible out of necessity.

I also answered the second part of the question and listed my most commonly used model parts (broken down by hierarchy):

  • On your mind
  • Contents
    – Buckle
    – Lateral bar
  • Footer

the content-*.html and loop-*.html the parts of the model show the most variations.

Color definition

The next section of the survey asks how theme authors define their color palette slugs in theme.json. Believe it or not, naming colors can be the most controversial topic in the theme world for years. The only two things that are generally agreed upon are the “background” and “foreground” colors.

Morten Rand-Hendriksen opened a ticket in 2018 to standardize a theme color naming scheme. It was not the first discussion and was not the last. The problem it was supposed to solve was the slugs for colors in the system, which is how themes define their palettes. Once a user uses a predefined color, the slug is hard-coded into its content. Switch to another theme with different slugs, and the old colors disappear and don’t automatically switch to the new theme’s colors.

I’m using semantic names that follow something that closely resembles the CSS Tailwind framework’s shading system. In the place of red-medium (descriptive), I would use primary-500 (semantics), for example. A semantic approach would allow theme authors to define a set of colors that are updated each time a user changes themes.

Of course, there are other schools of thought, and even everyone who prefers the semantic naming will not agree on the same system. I described my approach in more detail in a more recent GitHub ticket and have a theme.json Gist for others who might want to try it out.

Other theme JSON settings

Aside from colors and typography, the survey asks what other settings the theme authors used. This is another scenario where I usually use everything – if there is an option for it, I set it.

One use case that WordPress currently doesn’t have a preset is Global Spacing. Most theme authors use a single value for most vertical margins (white spaces between boxes and elements). It is also often used for vertical and horizontal fill by default.

I’m not sure if I want a preset because I’m not sure how WordPress will use it. This is something others have requested, and its use is almost ubiquitous. Defining an entire system around this might cause some headaches down the road, but I’d still like to see a discussion of implementing at least one standard global spacing preset.

Parameters and styles per block

This survey section was a yes / no question, simply asking if theme authors included any parameters or block styles in their theme.json files. Of course, I left a few more comments later in the optional comments section.

I’m happy with the system when it comes to settings, which allow users to define which features are enabled globally or per block. However, I am not convinced by adding styles via theme.json.

Writing CSS in JSON, basically what we’re talking about, seems wrong in many ways. Currently, it’s limited to a few configurable styles, so anything beyond that requires diving into an actual CSS file anyway. This is problematic because half of the theme’s CSS code is split between theme.json and a separate CSS file. From a development perspective, this makes the code base more difficult to maintain.

Initially I started setting up styles per block and per item from theme.json. However, I have since moved my styling to CSS files. It feels more natural and I have the added benefit of all the tools I’m used to. Right now, I can’t imagine a scenario where I would back down.

Besides saving a few bytes of code, I didn’t see much benefit from adding styles for most things via JSON. Maybe that will change in the future, and I’ll be a convert. For now, I’m mainly sticking to CSS.

Other comments: a PHP layer

I’ve said it before, but it bears repeating. We need a PHP layer for this theme.json configuration system. There is currently a ticket open to resolve this issue.

There are two main advantages of such a system. Having a PHP API to piece together the configuration will feel a lot more natural to traditional theme developers. I see it as a bit of an olive branch, good faith proof that core / Gutenberg developers recognize that many theme authors will have an easier time integrating FSE functionality through a familiar programming language.

The second benefit is that there are countless number of plugin ideas to extend overall styles, site editing, etc. A simple filter hook would make this painless.

Comments are closed.