Skip to main content
wordpress supportwordpress support services

Designing Block-Based WordPress Child Themes With a Single JSON File

From the moment I opened my first theme shop back in 2008 to the present day as someone who merely tinkers, my plan has always been to build a single theme in the mold of CSS Zen Garden. This was a project that Dave Shea launched in the early 2000s to show how designers could manipulate a site through CSS alone. The HTML would stay the same, but the design could be anything.

I have achieved that goal multiple times with several projects. Technically, all I ever needed was architecturally sound markup in a WordPress theme and custom CSS in a child theme.

The concept was simple, but over time, my vision changed. I wanted to create something that made designing these types of child themes even easier. Therefore, I built custom systems to work around WordPress’s lack of tools in the theme design realm. Not to boast too much, but I felt like I had created some handy methods. They allowed child theme designers to plug values into config files, such as font-family names and color codes. Most of these could also be overwritten by end-users via the customizer.

By 2018, I was already hard at work on what would be my magnum opus, the best WordPress theme I had ever built. I had also planned on it being my last. I had been considering getting out of the game for a while. But, this was a project that I had to see through.

Then, the new block editor blew everything up. I had worked with it for months before it launched, but I knew theme development would never be the same. The Gutenberg project would continue maturing and reshape WordPress’s future.

I eventually launched my theme. It was one of the earliest commercial products that supported the new block system. However, I was also deflated.

These were the early block editor days. No one really knew what we would be looking at in three or more years, but if you were paying even a modicum of attention, you could see that theming would evolve into something far different than it was at the time. I spent over a year building a theming system that would become irrelevant in short order — granted, I thought we would have arrived at this destination much sooner.

WordPress 5.9 will ship the final sub-components of Full Site Editing. This will include support for block themes under the hood. Users who install them can customize them through the site editor and the global styles interface.

What excites me the most is still the thing that woke me up every morning 13 years ago: child themes.

Block child themes have partially worked in the Gutenberg plugin for months. However, the feature that I was looking forward to the most was not ready until a week ago. A new patch allows a child theme to overwrite single values of its parent’s theme.json file. Essentially, the two files are merged, with the child taking precedence.

Why was I so excited about this feature? Because it was the same system I had built in years past — but better.

After seeing this land in the development version of Gutenberg, the first thing I did was load up a custom theme I have been dabbling with. It is a project that I have been building for fun and my own edification.

Single demo post showcasing black text on a white background.
Single post view of parent theme.

Then, I created a new project in my code editor. I added the required style.css file and plugged in the appropriate header fields. I would not need it beyond that. My child theme’s design would rely on another feature altogether.

I added a theme.json at the child theme’s root level and began having more fun than I have had with theming in a long while.

I picked out a couple of autumn colors and a fun heading font. Within a few minutes, I had a new coat of paint splashed across my test install. The design was not revolutionary or anything of the sort. I was just amazed at how easy it was to transform my design by plugging in a few values.

Autumn-styled child theme of browns and oranges displaying a single post.
Single post view of child theme.

This is the type of child theming I have always longed for. I want the power to switch my theme’s design elements around for various seasons and holidays. And I want to be able to share these child themes with others.

As I said, I had built such methods of child theming before (I used PHP instead of JSON). However, this is much more powerful because it relies on the standard block system and not something custom that only a handful of people would ever use.

Some of you may ask why I did not make these changes via the site editor instead of creating a child theme. Rich Tabor posed, essentially, the same question on Twitter earlier today. “If a theme consists of JSON and block templates that can both be modified via Global Styles, then what are child themes for?”

Let us say that I have installed a block theme and made a few color adjustments. Now, pretend that I want to mix this up when Christmas rolls around — throw in a few colors and find a festive holiday font. When I make these changes, my old design will no longer be there when the season ends because user customizations are stored based on the active theme. I could, of course, make a note of all my old settings and change them all back later. However, doing it via a child theme means that I can merely switch themes at any time. My old settings would remain intact.

Perhaps this is very much an edge case. Who is making seasonal changes to their design these days, right?

The exciting part is that I can share child themes built with a single JSON file with others.

Child theming has been a passion of mine since the feature landed in WordPress. In some respects, it has not changed much. Themers can still overwrite templates from the parent. They can continue adding custom CSS if they want to. But now, they can configure any part of the design from a single standardized file. That is something worth putting my developer’s cap back on for and building one more theme.

I also see a child-theme-less future that still has the same benefits of sharing design elements.

The block pattern directory already provides layouts that should work with any well-built WordPress theme. However, there are other components of design that we could break apart in the future.

I imagine a future where WordPress could have installable color palettes like what Colour Lovers offers. Just browse a directory, install, and change your color scheme without finding a new theme. Something similar to the recent Adrian plugin could serve the same purpose for fonts. These are things the community may want to consider down the road. No ideas should be off the table at this point.

For now, I am happy to have the full power of child theming at my disposal. The change should land in Gutenberg 11.8 this week and WordPress 5.9 later this year.