Feedback on adoption approach for exposing editable UI for the Style Book for Classic themes

[annezazu]

Context:

As of Gutenberg 19.9, the Style Book is now exposed to Classic themes. As it stands, support is available for Classic themes that either support editor styles via add_theme_support( 'editor-styles' ) or have a theme.json file. Without either, the Style Book doesn't display anything useful. Here's a quick demo using Twenty Twenty-One:

tt1.style.book.mov

In particular, the current thinking is that by having a theme.json file in a Classic theme that this marks an explicit opt in and, to quote @jasmussen, "edibility is progressive, insofar as if your theme.json is empty, or virtually empty, little to nothing would be editable. But for each array you add, whether that array is empty or not, would unlock part of the interface." For example, if you add settings.typography options, this would then give a user access to the UI for Typography and, potentially in the future, the font library.

With all of this in mind, another PR is open to enable the Style Book regardless of whether a classic theme has theme.json or supports editor styles! All of this begs the question and points to needing to get right the opt in and opt out approach to provide the most value when it comes to exposing editable UI to users of classic themes. This issue seeks to gather that feedback to ensure we can come to the best decision possible.

Feedback needed

From what I can see we have two main tension points:

• Do we rely on the presence of editor styles or theme.json to opt in OR expose to all and provide a way to opt out?
• Is there value in showing a non editable Style Book and is that an experience users will understand? In the comments on this issue, the desire for this is clear but I am noting this for comprehensiveness as there's a concern that this could be confusing for users in situations where nothing is editable.
• Does the presence of a theme.json with settings automatically opt a theme into exposing parts of the global styles UI related to those settings or is an explicit opt in necessary to expose any of the global styles UI, in addition to a theme.json?

Please share feedback on the current approach and the desired approach you'd like to see. cc @WordPress/outreach & @WordPress/block-themers for good measure.

[ironprogrammer]

Speaking from experience, in my agency days doing (now "classic") custom themes I typically created a private page as a style guide, which was quite similar to the Style Book. It wasn't intended for editing, but for visual reference and to ensure we had all the major elements covered. There may or may not have been liberal use of Save+Refresh while dialing in the stylesheet 🫣.

I like the idea of having this as a utility for any classic theme. It shows off some coolness that block themes get, but also reveals what elements/blocks you might have missed in your styles. It could be a subtle hint to upgrade to theme.json or a block-based theme to get all the benefits.

For those used to working with classic themes, I don't think there's much of an expectation of being able to live-edit with a design "preview" feature like this.

[tellthemachines]

the current thinking is that by having a theme.json file in a Classic theme that this marks an explicit opt in and, #66851 (comment) @jasmussen, "edibility is progressive, insofar as if your theme.json is empty, or virtually empty, little to nothing would be editable. But for each array you add, whether that array is empty or not, would unlock part of the interface." For example, if you add settings.typography options, this would then give a user access to the UI for Typography

I think it needs to be very clear that, in its current iteration, the style book doesn't include any editing UI.

What is being discussed for future iterations is how to expose parts of the global styles UI for hybrid themes that have a theme.json. There are a couple possibilities:

• The presence of a theme.json with settings should automatically expose parts of the global styles UI related to those settings.
• An explicit opt in should be necessary to expose any of the global styles UI, in addition to a theme.json.

Based on the feedback in #41119, I'm more inclined towards the second option, as theme authors may want to leverage theme.json for styling purposes without necessarily exposing edit functionality. Having controlled editability is one of the reasons for creating a hybrid theme instead of a block theme in the first place.

I'm very curious to hear what other folks have to say on the topic!

[annezazu]

Ah yes! Let me update to make that far clearer. Thank you.

[t-hamano]

I think the important thing here is that theme.json is not taken into account to determine if the current theme is a block theme, i.e. if the global styles UI is available. If only the templates/index.html and style.css files exist, the theme is treated as a block theme and can access the site editor and global styles.

Considering that, relying on the existence of theme.json is at least a little confusing to me. Also, classic theme developers may develop themes based on theme.json but not want the global style UI to be available. In fact, I also develop many classic themes with theme.json for clients as a freelancer, but the purpose is to define block styles without adding CSS styles, and I do not want the global style UI to be automatically exposed.

Personally, I prefer the following approach:

• Expose Style Book for all classic themes. Explain with more detailed text that the Style Book cannot be edited.
• Add theme support for classic themes to be able to use the global style UI. For example, something like add_theme_support( 'global-sryles-ui' ).

Or, to show/hide some UI, we might be able to consider the following approach in theme.json:

{
	"version": 3,
	"settings": {
		"typography": {
			"showGlobalStylesUI": false
		},
		"color": {
			"showGlobalStylesUI": true
		}
	}
}

[jasmussen]

I've prefixed most of my feedback on this issue that I do not feel strongly about this, and think that folks who feel more strongly about this, should decide. So I'm happy to support either direction. I did want to respond to this:

Considering that, relying on the existence of theme.json is at least a little confusing to me.

The motivation for relying on the existance of theme.json comes down to a few aspects:

1. Followup updates to the Style Book are meant to progressively unlock features for classic themes. Add a palette array, and you get edit access to color palettes. Add a font sizes array and you get access to editing typography, and get access to the font library. Etc.
2. Having the initial opt-in be about the presence of the theme.json file leans into the fact that this is the same file that you will need to edit, to make the style book editable.
3. It avoids another theme support property to keep track on.
4. It has this opt-in, as opposed to an opt-out, because I still think having Style Book as an interace that vaguely resembles the customizer, but isn't editable at all, is going to be more confusing than not having it.

Ultimately, I do feel strongly about letting users opt into editable aspects of the style book. But whether the style book itself is opted into our out of, I'll defer despite the stated not-so-strong opinion.

[carolinan]

In my opinion, the correct way would be for the new feature to be opt-in, because the majority of older classic themes have not been tested with block styles.
It should be explicitly enabled with add_theme_support.

By not having it opt-in there is a big potential to introduce a broken feature and a confusing feature on many live websites.
Please remember that editor style for classic themes was introduced in WordPress 3.0. I think that makes it inappropriate to use for progressively unlocking new features.

(By the way, testing the feature today, with Gutenberg trunk it does not even work, there is no preview and there is a JS error on the color palette.) This has since been resolved

[carolinan]

I think the important thing here is that theme.json is not taken into account to determine if the current theme is a block theme, i.e. if the global styles UI is available. If only the templates/index.html and style.css files exist, the theme is treated as a block theme and can access the site editor and global styles.

Correct, theme.json is not a required file for block themes.

[Mamaduka]

We could also make it opt-in using extra arguments for editor-styles.

Example:

add_theme_support( 'editor-styles', array(
    'style-book' => true,
) );

[BowFarmer]

What happens if the parent classic theme does not have templates/index.html and style.css files but a child theme does?

[carolinan]

After re-reading the discussion in #67782,
My opinion remains that the basic stylebook that only has the preview should be enabled when:

• A classic theme has a theme.json
• When there is no theme.json and the theme enables a new dedicated theme support.

But not when the classic theme only has the editor style theme support, because of how long this has been available and because in my opinion, it is unlreated.

All classic themes should be able to opt-out, even if it has a theme.json. For example if the theme developer has already added their own style guide.

But the theme support as well as the check for it needs to be added in way that allows the theme developer to extend the functionality once it is implemented.

I mean as discussed above, if the theme.json file includes typography settings, the typography should be available.
If the developer used the theme support, they need to be able to add the typography as a parameter.

Because we don't want to have to change the formatting of the theme support later because all planned features were not implemented yet.

[Mamaduka]

I haven't checked in a while, but we already enabled some theme support flags based on theme.json. The same can be done for style-book.

It would be nice to avoid some implicit logic based on what theme.json declares. The options are always hard to keep track of and can be confusing.

A classic theme with a theme.json file

The editor-styles theme support is augmented with style-book set to true. Themes can opt out of Style Book support.

A classic theme without a theme.json file

The style-book isn't set (considered false). Themes can opt-in the Style Book support.

[t-hamano]

I agree with the approach of being explicitly enabled or disabled via theme support.

By the way, I remember seeing an issue somewhere considering exposing the global styles to the classic theme. Taking this into consideration, I think one of the following approaches might be the best:

add_theme_support( 'editor-styles', array(
	'style-book'    => true,
	'gloabl-styles' => true,
) );

add_theme_support( 'site-editor', array(
	'style-book'    => true,
	'gloabl-styles' => true,
) );

[carolinan]

yeah using "site-editor" to plan for future changes sounds like a good idea

[Mamaduka]

Using the site-editor keyword for non-block themes could be confusing. What are the cons of re-using existing editor-styles theme supports?

[carolinan]

With the additional parameters, the fact that editor-styles has been used for many years is not a hindrance anymore 👍 .

But they are not editor styles. The default block styles and the global styles are applied to blocks both in the editor and front.
What other things could be considered, the font library? Also not editor styles.

[carolinan]

Current:
https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/

Also:
remove_theme_support( 'block-templates');

[carolinan]

I found that with Gutenberg trunk active, the stylebook is now always accessible through wp-admin/site-editor.php?p=stylebook for all classic themes.
Now, the check for the theme type, editor-style etc only changes the menu item under Appearance.

So what should happen when this paged is accessed?

[carolinan]

OK, it is not only the stylebook, but also wp-admin/site-editor.php?p=%2Ftemplate including the add new template button, I don't think this is intended.

[t-hamano]

I found that with Gutenberg trunk active, the stylebook is now always accessible through wp-admin/site-editor.php?p=stylebook for all classic themes.
but also wp-admin/site-editor.php?p=%2Ftemplate including the add new template button

This is certainly not intended.

The Gutenberg plugin hooks wp_die itself for backwards compatibility, and avoids wp_die based on a condition. This function will need to be updated:

gutenberg/lib/compat/wordpress-6.8/site-editor.php

Lines 118 to 124 in 80348e7

	function gutenberg_styles_wp_die_handler( $default_handler ) {
	if ( ! wp_is_block_theme() && str_contains( $_SERVER['REQUEST_URI'], 'site-editor.php' ) && current_user_can( 'edit_theme_options' ) ) {
	return '__return_false';
	}
	return $default_handler;
	}
	add_filter( 'wp_die_handler', 'gutenberg_styles_wp_die_handler' );

[carolinan]

Yes as the problem kept growing I opened a separate issue for it #68950

[carolinan]

I know this is not helping but I am more and more torn about this.
I feel like I needed to go the full circle to arrive at where others started 😬

If the end goal is to unify the editors, and make the styles, patterns, parts, templates, available no matter what the theme type is, -especially user created templates: then the opt-in is going to be a hindrance.

I still think that the stylebook will be problematic for some classic themes because what you see is not what you get. But long term, having it be opt-out may be better for the majority.

[getsource]

I was ping'd by @Mamaduka about this and did a read-through.

Thanks so much for the follow-up @carolinan!

Is the current consensus that this can remain a default, without a way to opt-out manually?

Would it still be helpful to still add a theme support flag to be able to opt-out, rather than opt-in?

[carolinan]

I am not able to speak for everyone and say if there is consensus.

So to opt-out using a theme support:
-The theme support needs to be registered and enabled by default, so that developers can use remove_theme_support.
-The Site Editor menu and styles screen needs to use getThemeSupports and check if the stylebook is enabled, and show it conditionally.

[carolinan]

remove_theme_support currently does not check nested arrays, so adding a "complex" support like add_theme_support( 'editor', 'stylebook' ); will not work unless this function is updated too.

Maybe there are other uses cases for expanding remove_theme_support.
If not, maybe use add_theme_support( 'stylebook' ) anyway, even if it means it wont be as easily extendable.

function remove_theme_support( $feature ) {
	// Do not remove internal registrations that are not used directly by themes.
	if ( in_array( $feature, array( 'editor-style', 'widgets', 'menus' ), true ) ) {
		return false;
	}

	return _remove_theme_support( $feature );
}

[t-hamano]

remove_theme_support currently does not check nested arrays, so adding a "complex" support like add_theme_support( 'editor', 'stylebook' ); will not work unless this function is updated too.

To achieve this, I think we need to update the internal function _remove_theme_support(). For example, the uploads support, which is part of the custom-header support, has a special custom-header-uploads key to control it.

I don't have a strong opinion on what key to use for theme support, but I prefer to expose the StyleBook by default to all classic themes and add a theme support flag to opt-out.

[t-hamano]

I'm wondering if the new theme support should be applied to block themes as well as classic themes. In other words, when code like remove_theme_support( 'stylebook' ) is executed, should all of the following UI be disabled in the block theme?

[carolinan]

I don't feel strongly for or against adding an opt out for block themes. I have not seen any requests for it.

Are there options other than using remove_theme_support, that would make sense for both classic and block themes?

Because registering and enabling a theme support by default only so that you can remove it feels backwards.

[carolinan]

I am also concerned about the time, since it needs to be solved before beta 1. If it is not solved, or not agreed upon, it may need to be paused and not included in 6.8.
Beta 1 is on March 4, 2025, and no enhancements should be added after that.

[t-hamano]

First of all, I would be happy to see a consensus on which approach we should take: should the StyleBook rely on the theme support, or on the presence of theme.json and editor styles?

Based on the discussion so far, it seems like most contributors would prefer opt-in/opt-out theming support.

Once this is decided, I think we can move forward with preparing to ship the StyleBook for 6.8, whether it should be enabled by default or not.

[carolinan]

I am not sure how to say this without making it sound like a complaint or rant, but how do we as contributors know when consensus have been reached?
If people only speak up on Slack and do not engage in the issues or pull requests, their opinions will not be recorded and it makes it difficult to take those opinions into account.

At the moment this is just going in circles, and it is partially my fault.
But there is a PR that registers the theme support. As far as I see it, the code will be the same wether it is opt-in or opt-out, the only difference would be that if it is opt-in, core should not enable it by default. So its maybe a 3 line code change.

[joemcgill]

@carolinan and @t-hamano, thanks for continuing to push this effort forward. Here's my current understanding of the state of this feature, so please correct me if I've gotten anything wrong.

Current status (I think 😄)

Currently in GB trunk, the Style Book is shown to all classic themes that either declare theme support for 'editor-styles' or has a theme.json file (reference).

There is currently an open PR that proposes modifying support for showing the Style Book to an explicit theme_supports feature. Once the approach for support is decided, the relevant update needs to be made to WordPress trunk as well, e.g., this open PR.

Observations

In terms of the PHP side of things, I'm happy with the proposed theme support approach for an initial WP commit with a few observations:

There are issues in the UI that still need to be addressed, even after the approach from #69043 (or an alternative) is committed. The current PR changes the name and path of the menu item in the admin sidebar so it opens either the Design panel (with the style book) or the Patterns page directly (when theme support is removed). Even so, the Stylebook is still available when linking directly to the Patterns screen because of the logic used here to display the Stylebook navigation item in the MainSidebarNavigationContent. See video of current behavior:

Screen.Recording.2025-02-22.at.6.00.34.PM.mov

A separate detail is that these pages are still accessible if someone directly visits those URLs even if we aren't showing the navigation (see: #69005). In my opinion, this is a nice to have but not a blocker. Fixing the navigation flows in the UI, however, do seem like a blocker for keeping this feature for 6.8, but can be iterated on during beta if needed.

Should we apply current_theme_supports( 'stylebook' ) consistently for classic and block themes? In other words, if the site is running a block theme and theme support for the stylebook is removed, should we also hide the Stylebook from the site editor for block themes as well. Ideally, I think we want to have a consistent API for theme_supports, but this may not be easily possible to achieve. An alternative would be to keep the current approach as is and provide a filter to allow folks to opt-out of the feature, but I'm not confident that this is any better than the current approach. Happy for you all to make suggestions on a preferred approach.

[t-hamano]

@joemcgill Thank you for the detailed summary!

Currently in GB trunk, the Style Book is shown to all classic themes that either declare theme support for 'editor-styles' or has a theme.json file (reference).

There is currently an open PR that proposes modifying support for showing the Style Book to an explicit theme_supports feature. Once the approach for support is decided, the relevant update needs to be made to WordPress trunk as well, e.g., this open PR.

Yes, all of these are correct.

Originally, the reason why it was proposed to provide a way to opt out or opt in to the StyleBook in classic themes was, as I understand it, for two reasons:

• Whether an inoperable StyleBook (i.e., not being able to change block styles via the global styles) would provide value
• There may be old classic themes that have not been tested with block styles

I think these two points should not apply to block themes. Therefore, in my opinion, the StyleBook theme support is only for classic themes, and block themes should always display StyleBook regardless of their theme support. Personally, I have not heard of any request to be able to disable StyleBook in block themes.

[stokesman]

A separate detail is that these pages are still accessible if someone directly visits those URLs even if we aren't showing the navigation (see: #69005). In my opinion, this is a nice to have but not a blocker.

Yes, this is a separate and broader issue. It also seems it would qualify as a regression since 6.7 and therefore be eligible to fix after the beta.

---

I also agree that the Stylebook theme support doesn’t need to work for block themes. I don’t think shipping it that way prevents making it work in the future.

[karmatosed]

Thank you so much for the summary on this @joemcgill, that was very helpful to come to when asked for feedback.

Whist I do have an issue with the navigation flows from a usability perspective I am not against us working on them during beta 1. However, for me it is a bit of a ‘moved my cheese’ moment for any user in its current form. This feels compounded by the fact it goes to the top for ’Styles’

An alternative would be to keep the current approach as is and provide a filter to allow folks to opt-out of the feature, but I'm not confident that this is any better than the current approach.

I am not convinced in that either.

I wanted to as we work on this surface a the comment back in December from @jasmussen # so we can use the also in decisions here.

The motivation for relying on the existance of theme.json comes down to a few aspects:

1. Followup updates to the Style Book are meant to progressively unlock features for classic themes. Add a palette array, and you get edit access to color palettes. Add a font sizes array and you get access to editing typography, and get access to the font library. Etc.
2. Having the initial opt-in be about the presence of the theme.json file leans into the fact that this is the same file that you will need to edit, to make the style book editable.
3. It avoids another theme support property to keep track on.
4. It has this opt-in, as opposed to an opt-out, because I still think having Style Book as an interace that vaguely resembles the customizer, but isn't editable at all, is going to be more confusing than not having it.

Ultimately, I do feel strongly about letting users opt into editable aspects of the style book. But whether the style book itself is opted into our out of, I'll defer despite the stated not-so-strong opinion.

What I am doing by sharing this is focusing us on whatever approach we go with making sure it serves those purposes that I agree with wholeheartedly.

[carolinan]

I am very confused because when this was discussed on Slack in January @karmatosed you wrote:

Most would likely want that feature on by default which is why I am suggesting that.
On means it can be removed.

Which is one of the reasons why I changed my own opinion about having it be opt-in and instead, have it enabled by default.

[carolinan]

After having discussed this for over two months, we are back at square one again, a few hours before the punting deadline?
Then lets remove the feature from the JavaScript package and not have it in 6.8 at all, since it is not ready.

[carolinan]

I am now going to step away from this task because its not a healthy environment for me.

[t-hamano]

I came across a core PR that updates the submenu based on the current Gutenberg plugin specs: WordPress/wordpress-develop#8429

In other words, the availability of StyleBook is determined based on the following condition:

! wp_is_block_theme() && ( current_theme_supports( 'editor-styles' ) || wp_theme_has_theme_json()

In other words, classic themes that meet the above conditions will have the "Design" submenu, and classic themes that do not will have the "Patterns" submenu.

However, there is currently a UI issue with Gutenberg where even if a theme does not support StyleBook, you can still navigate from the Patterns screen to the higher-level Design screen and access StyleBook from there. Regardless of how we expose StyleBook, this problem needs to be resolved.

To solve this, we need to restrict access based on conditions that are equal to the PHP code in the site editor:

• wp_is_block_theme(): wp.data.select('core').getCurrentTheme()?.is_block_theme
• current_theme_supports( 'editor-styles' ): wp.data.select('core').getCurrentTheme()?.theme_supports['editor-styles']
• wp_theme_has_theme_json(): 🤔

As you can see, as far as I know, there's no way to tell with the Gutenberg API if the currently active theme has a theme.json file or not.

In fact, supportsLayout is equal to wp_theme_has_theme_json(), as you can check with the code below, but supportsLayout is probably intended to be used for a different purpose:

wp.data.select('core/block-editor').getSettings()?.supportsLayout

Any ideas on this?

[joemcgill]

Hi @t-hamano! I opened that Core PR mostly so we had the potential to commit and test what is currently implemented in this repo while continuing to work out the details about how we determine "support" for this feature and ensure that the UI flows still account for when a theme does not support the stylebook. Making sure these flows still work regardless of what logic we end up using to determine "support" is important, or else we'll need to revert all of the stylebook changes

One way to test these flows currently in the GB plugin is to comment out this line with a classic theme, like Twenty Ten activated.

I think using supportsLayout for now to work out the flows is ok, rather than adding a separate setting that we may not end up needing.

[t-hamano]

Regardless of how we ultimately publish the StyleBook, I have submitted two PRs to properly publish the StyleBook based on the current Gutenberg spec.

• #69299: Depending on the type of theme and whether or not it supports StyleBook, mechanisms will be introduced to prevent unnecessary rendering or display warnings.
• #69377: Control the site editor sidebar navigation and check direct URL access to prevent unintentional exposure of StyleBook.