On July 30th, I shared a survey to gather insights around how theme authors are exploring theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. today in order to shape what’s possible in the future with theme design. Thank you to the 31 people who took the time to share their feedback! By having concentrated feedback like this, better decisions can be made around what makes sense to include in CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.. What follows is a high level summary of the results. 

As always, GitHub issues are welcomed for anything not covered here or that comes up in the future. Please keep sharing your feedback there and know it’s appreciated as the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. theme design system continues to evolve. 

High level takeaways

Most folks who responded to the survey have experimented with building block themes either by starting from scratch or by forking an existing theme. Of note, TT1 Blocks didn’t stand out as a base that folks relied upon with many choosing to fork their own theme or working to move a classic theme they made to a block. While most folks used color presets, there was a variety of approaches included a few mixed naming strategies showing that this is still an open ended area of exploration. Along with colors and typography, the ability to customize layout and spacing options proved to be favorites. There was a near 50/50 split in terms of those who had explored per block settings or styles, with the Button block being the most commonly referenced by those who had. From the wide variety of feedback gathered, a few suggestions emerged for how best to improve the experience going forward including expanding theme.json documentation, adding commenting and improving the structure of theme.json, and more. 

Full Results

If you want to read the full reports, I have included an option below. Keep in mind that I intentionally removed any personal identifying questions that listed the contact information for folks (name, email address, country, etc). 

Overview of participants

31 people participated from 17 countries with the longest time spent responding clocking in around 60 minutes and the shortest time just under 2 minutes (removed a 2d response assuming it was left open in their browser).  

Q1: Please select which best fits your experience

1. I have built and launched block themes (16 responses). 
2. Other Option (6 responses).
3. I have explored using theme.json with a classic theme (5 responses).
4. I have experimented with building block themes (4 responses).
5. I have used a block theme, but I have not built one yet (0 responses).

52% of participants said that they have built and launched block themes, which was exciting to see! For those who answered with Other Option, the responses were, for the most part, combining different responses into one:

I tried using theme.json in a classic theme and also experimented with TT1-Blocks theme and FSE. But haven’t dig in too deep to create a fully custom FSE solution.

I’ve built 5 experimental block themes and explored theme.json with classic themes.

I’m currently building a hybrid theme for a fairly large SaaS client that relies on theme.json and Block Patterns.

I have explored using theme.json with a classic theme and I have experimented with building block themes.

I have experimented with block themes and fse. I am currently building a custom block theme for a client site.

Q2: Please select what most closely matches how you got started with block themes + theme.json.

1. I started from scratch (14 responses).
2. I forked an existing theme (9 responses).
3. Other Option (5 responses).
4. I used the empty theme from theme experiments (3 responses). 

This question was intended to help get insight into what resources folks are relying on and what the process to get started looks like. The results showed that more could be done to improve this part of block theme development, whether through amplifying available resources or improving those resources themselves. For the Other Option selection, there were some insightful responses:

I converted an existing theme to a block theme.

All of the above.

Using my Genesis base child themeChild theme A Child Theme is a customized theme based upon a Parent Theme. It’s considered best practice to create a child theme if you want to modify the CSS of your theme. https://developer.wordpress.org/themes/advanced-topics/child-themes/. and implementing/testing what I have come across over several resources online.

The comment section was particularly lively for this question as it asked those who forked an existing theme to share which theme/what approach they took. All the responses aren’t included here, but here is a representative sampling:

I have used all three. I no longer use empty theme because it is too basic for me. When I fork, I copy one of my earlier themes.

I extended an existing custom theme from our agency.

We started from a classic theme, created a blocks pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party (Nova Blocks) around it, and step-by-step evolve towards a block theme (Rosa2). It’s not a fully block-based theme, but the goal is to get there soon.

I have done most of my experimenting with tt1. I have been referencing and digging into the code many block themes, trying to come up with the best methodology for my custom theme which will need to be production ready at end of month. Blockbase, seedlet-blocks, astra-blocks, genesis block theme.

Across the board in the comments, these four patterns emerged: starting with an existing theme they know well, following tutorials like fullsiteediting.com, forking an existing block theme, or some combination of each option. It feels important to note that TT1 Blocks, the block version of the Twenty Twenty-One default theme, was only mentioned three times. 

Q3: What templates and template parts do you always include in your block-based themes?

On the whole, most folks mentioned the following:

• Templates: Index, Archive, 404, Page, Search, and Single with mentions of customized templates like a News page. 
• Template Parts: HeaderHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. and Footer with LoopLoop The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. https://codex.wordpress.org/The_Loop. and SidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme. mentioned a few times. 

To get a broader sense of responses, here is a sampling:

​​This is an ecommerce theme using WooCommerce blocks and our custom block library. Templates: Front Page Single Post Archive Search 404 Page Several Post templates and Page templates with sidebars 

Template parts: Header Footer Shop Archive-product (categories, tags, attributes) Loop and a few other templates (e.g., loop with sidebar) depending on the setup

We primarily use template parts for Header and Footer but evolving steadily to all other theme parts. Here is a list of all the templates: https://github.com/pixelgrade/rosa2/tree/main/template-parts

In particular, in that last comment, you can see a wide range of possible template parts mentioned from Pixelgrade, including site branding and meta social (shared with consent). 

Q4: How do you use colors within theme.json?

1. I add color presets with names like “Blue, Red, Green”, and refer to those directly to use them (13 responses).
2. I use semantic names for colors like “primary, secondary, foreground, background” (11 responses). 
3. Other Option (7 responses).

For the other options, the following themes emerged as a combination of feedback and approaches:

• Using a mixed naming strategy.
• Using an approach that closely resembles a semantic strategy.

This question resulted in some lively additional comments with a sampling shared below: 

Surely, this is a tricky question as there is no standard cross-theme compatible way of naming colors.

Nowadays I kind of use a mixed naming strategy:

– primary, secondary and tertiary (,…) for base theme color scheme,

– an black, white, gray, dark gray, light gray for standard grayscale colors.

All of these colors populate editor palette too. I do not set other colors if not required by the project as I feel a theme should adhere to some limited color palette (while still providing some options for basic colors of grayscale for possible tinting).

I have been adding the color names. But am keen to the idea of the primary, secondary, etc. The problem for me in doing so has always been that they are too limiting. The designs I work off of in client theming are usually pretty complex and my colors do not always neatly fall into those categories. 

I use semantic names with a Tailwind-like shading system. For example, my “primary” color gets split between different shades from 100 (lightest) to 900 (darkest). So, you get primary-100, primary-200, … primary-900. These can be reduced or added to on a per-project basis. The system is based on the popular Tailwind CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. framework, but it also closely models common systems of theme authors I have surveyed. They tend to have neutral, primary, and/or secondary colors across the average project.

The !important that is added to all theme colors is DRIVING ME CRAZY.

Q5: Beyond colors and typography, what other settings do you use most frequently in theme.json?

A few folks mentioned block-specific settings likely because this question came before the one about block settings. I removed those responses from this section. 

• Layout (11 mentions).
• Spacing (9 mentions).
• None/not applicable (7 mentions). 

For Layout, I counted the following mentions altogether: Layout, contentSize, wideSize. 

For Spacing, I counted the following mentions altogether: Spacing, Margin, Padding.

Mainly custom definitions: filling gaps that aren’t currently supported as presets, and duplicating layout definitions for contentSize and wideSize to expose these values.

Not much to date, but waiting on more to become available so I can use it more.

I think I’ve touched every piece of `{ settings: {} }`, configuring things to my liking. Some common `settings.custom` properties that I set are: – Spacing values, with the most-used being a `spacing.global` value. – Content and wide-layout values because these are not currently exposed as CSS properties via presets. – Google Fonts system. It’s a bit too early to say what I will use the most going forward though. It is still early. The biggest thing that is missing is a global spacing value as a preset. I have a feeling that will be a common use case for most theme authors.

Q6: Have you included per-block settings or styles in your theme.json files?

This question was nearly split, with 16 people responding “Yes” (52%) and 15 responding “No” (48%). Those who said they do include per-block settings or styles were then given an additional question covered in the next section. 

Which blocks do you tend to customize with per block settings or styles in theme.json and why?

Note that this question was only shown if someone indicated that they have included per-block settings or styles in their theme.json files. The responses were fairly split with folks either saying they tend to customize all of them or tending to mention specific blocks. The Button block was heavily mentioned with 11 out of 16 people noting it. The following specific blocks were mentioned:

• Button (11 mentions)
• Navigation (3 mentions)
• Columns (2 mentions)
• List (2 mentions)
• Paragraph (2 mentions)
• Quote (2 mentions)
• Code (2 mentions)
• Site Title (2 mentions)
• Post Author (2 mentions)
• Post Date (2 mentions)
• Post Title (2 mentions)
• Featured ImageFeatured image A featured image is the main image used on your blog archive page and is pulled when the post or page is shared on social media. The image can be used to display in widget areas on your site or in a summary list of posts. (2 mentions)
• Separator (1 mention)
• Table (1 mention)
• Cover (1 mention)
• Heading (1 mention)
• Preformatted  (1 mention)
• Post Terms (1 mention)
• Query Pagination (1 mention)

Because this was an open-ended question, here is a sampling of longer form responses to help get a sense of what folks shared: 

For per-block settings, I have not done much outside of enabling an option or two if it was disabled by default. However, for per-block (and per-element) styles, I am not sold on the system. Writing CSS in JSON, which is essentially what we are talking about, feels wrong on so many levels. There is the obvious issue that it is limited to merely a few styles that are actually configurable, so anything beyond that requires diving into an actual CSS file anyway. And, that is problematic. Why would I want half my CSS code in a JSON file and the other half elsewhere? From a development standpoint, it makes the codebase harder to maintain. Initially, I started down the path of configuring per-block and element styles from `theme.json`. However, I have since moved my styling back to CSS files. It feels more natural, and I have the added benefit of all the tooling I am accustomed to. Right now, I cannot imagine a scenario where I would move back.  

I do customize pretty much all of them, as the default block styles rarely fit. I also remove every and all default block variations, and a lot of the patterns. Overall I’m not a fan of Core having “opinionated” styles, because that should be the theme’s job.

Individually styling a lot of blocks leads to a lot of customization when done explicitly in raw css – and potentially unnecessary bloat. Most of my customizations are set on the most used core blocks for layouting / synchronizing design aspects. 

I’ve mostly enabled border support for the Button block in the past (not sure if that is enabled by default now). Adding default spacing to various blocks is another thing I’ve done. But, the biggest use case has been settings some default styles for the root/body (colors, typography, and spacing) and for other elements rather than specifically individual blocks. I’m more interested in configuring per-block settings in the long-term than per-block styles though.

Q7: Any other feedback you’d like to provide around what would be helpful to include in Core long term when it comes to theme.json?

This open-ended question resulted in an awesome abundance of feedback, ideas, and more help request style questions! If you’re keen to read more, I’d recommend downloading the full results. For now, here are the major themes that relate to more specific ideas than more general feedback/help requests:

• Commenting options within theme.json to make it easier to review code. 
• Import function to pass settings between themes. This is being explored in this open issue on Exporting Block Themes & Styles. 
• Add more structure to the overall theme.json file, especially as more options are added.
• Overall improved options for responsiveness settings, including responsive font sizes. This is being explored in this PR. 
• PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php. layer for overwriting `theme.json` values
• Improved documentation for theme.json (showing how to define elements, explaining how theme.json overrides settings in block.json, and how to run internationalisation routines to create language files).
• Offering a way to generate theme.json using the WordPress editor or a tool (ie an official https://gutenberg-theme.xyz/). 
• Offering more complexity in the empty theme creation tool. 
• Explore the ability to have dynamic template parts. 

Once more, since this is an open ended question, here are some of the responses:

We plan to use theme.json to *disable* all low-level controls like color pickers, padding controls, and even custom font sizes. We want to introduce some system-level controls similar to the Global Styles but couldn’t wait until that part of the project is finished. 

I have to think more – but definitely have thoughts on this. MultisiteMultisite Multisite is a WordPress feature which allows users to create a network of sites on a single WordPress installation. Available since WordPress version 3.0, Multisite is a continuation of WPMU or WordPress Multiuser project. WordPress MultiUser project was discontinued and its features were included into WordPress core.https://codex.wordpress.org/Create_A_Network. functionality with theme.json in particular is a quite powerful use case. An “import” function, similar to wordpress importer to pass settings from one theme to another or one install to another or main theme to child theme – and consequently an exporter, would be super fantastic.

The theme.json file can get super big and a bit hard to peruse. My current project’s theme.json is 350+ lines long. I’ve seen two solutions already surface to try and address this a bit: Justin Tadlock shared a webpack tool that merges multiple json files in to one, which is probably the most suitable for my needs. I’m just mentioning this as I think it’ll quickly become a common gripe for engineers that use theme.json heavily and especially in a team/agency setting.

I love, love, love using the json file! It made customizing so easy. I’m looking forward to working more with FSE and building more themes.

We need as many tools as possible in theme.json but an ability to use as few of them as we need.

#block-themes, #fse-outreach-program, #fse-outreach-survey, #full-site-editing, #themes