Consider exposing the Style Book for classic themes

[annezazu]

What problem does this address?

As part of gradual adoption, theme.json can be used with classic or hybrid themes to manage a theme's styles, control what's exposed, etc. However, the Styles interface itself is not exposed to users to change as they'd like. To pull from @daveloodts comment here: #32682 (comment)

Editing Global Style doesn't have to a "unique" benefit of FSE-themes, but Hybrid themes too. With Hybrid themes is mean: still using blocks all the way, but not the "structure" editor what FSE does. With the current Global Styles embedded in the site-editor.php; Hybrid Themes are left out and have only the theme.json to work in.

There's more context here: https://wordpress.org/support/topic/global-styles-ui-on-non-fse-themes/

What is your proposed solution?

Consider providing a way to expose the Styles UI separate from the Site Editor for non-block themes taking advantage of theme.json. This could be a part of the work to have a section for global items: #32682 or something else entirely. Either way, it's an interesting idea to consider for the gradual adoption piece of FSE.

@scruffian tagging you in case you have thoughts and in case there are some technical considerations here that I'm not thinking of :)

[mtias]

This was brought up before and it stalled by not having clarity on where you should be editing these values. Adding support for the customizer, for example, would be non trivial. Adding a site editor instance just to modify global styles would possibly be confusing to users if they see both Customizer and Site Editor. It'd be interesting to see a design exploration that can accommodate it.

[carlomanf]

Related: #37943

[daveloodts]

Hi @mtias, the question is: should there really be a live preview while changing the block settings (for non-FSE themes)?
I don't think so. I am already happy there is a UI instead of doing it all in the theme.json file.

Most classic themes also don't have style settings without the live preview. I also understand that WP Core contributors don't have to put extra energy in a "new way" of live preview modes for non-FSE themes; cause maybe within a year of 3/5 the FSE-themes are common then. And maybe, i will be a fan too.
So i will be happy if the block UI is loaded in an admin page.

So please this don't overthink this.
Non-FSE themes users will (hopefully) understand that this UI-feature is mainly build for FSE.

But the chosen path right right now is -in my opinion- a very sad one. Since probably the first time in WP history as i remember, WordPress Core has decided that a nifty feature can only be used depending on the type of theme that you use.
And if you look at it neutrally, the block UI can be seen as a separate "aspect" then FSE(-templates). We are styling "blocks" with that UI.

I love blocks a lot, but styling those blocks (and every new block) during all these years was "not that easy".

But if there has to be a 'live preview', maybe a fixed template is also great.
That's a admin template where all blocks are fixed into code, no edits in content can be done via the admin. In the right sidebar, there's the block UI. Selecting the UI-part for buttons, then the admin-page will automatically scroll to the button anchor part.
Also for FSE-themes, this option can be very useful as it creates a styleguide template for you site. It even can have a frontend view if we no-index it. For previous projects, i created too a 'pattern'-page to have this kind of style guide page.

If you like the idea i can try to create a design for it.

[mtias]

@daveloodts thanks for chiming in! I think the idea of it being a UI without a preview is intriguing. Curious if you have some mockups on how it'd work. I was conceptualizing it living in the customizer, where it would be confusing if updating the color palette didn't reflect it on the preview. Also, for the subset of these global styles operations, it shouldn't be too difficult to make it work decently well with the customizer preview, at least in parts.

A styleguide template has also been mentioned as a general useful things that could be part of the roadmap, so that might also be a path forwards.

[daveloodts]

Hi @mtias, glad you like the idea.

i've made a mockup on how i see this Kitchen Sink example page:

kitchen-sink.pdf

Explanation of the design
At the left we have the regular block sidebar, patterns part is not needed. Every block in the left bar acts as anchor links, which makes the page scroll to the selected block.

The middle part is a template that can be set into core. If there is a guideline on how to deliver Kitchen Sink templates, then other plugins can hook in their own blocks. And we get to see -for example- WooCommerce Blocks- too.

The right sidebar is the global styles part; the same as it is now in the FSE-project.

There are many benefits of having this:

• users get to see an overview of blocks and what they 'really' look like. That will be an amazing thing to promote block. Right now, patterns do that promotion-part now too, but users don't really get to see (and understand) those individual parts. This Kitchen Sink page can be the "ingredients-page" of the Block editor. :-)
• the kitchen sink page can have a no-index page on the front, to use by the marketing as an example on how the company styles content
• extandable for plugins to show their blocks
• only the active blocks are shown
• maybe not all blocks need to show (like the youtube block for example), mostly the content blocks
• non-FSE users will get to know & use the global style options too. No splitting up anymore between FSE-theme users and not-FSE theme users.

The difficult part for extending it, is that Block Plugins has their own Global Style UI. The option here is to display a note and link to the global style page of that plugin. But extadability can come in the next phase. But annyway, i can deliver a Global Style UI basis for every WordPress plugin. Right now, every block plugin is reinventing their own wheel: Kadence, Astra, so on. They all have global styles options, all work different. It would certainly be awesome to have that extendability also for styling options in that right sidebar. For example: a shadow background, a hover-color, etc. Well, now i'm talking about the next next phase.

[carlomanf]

Adding a site editor instance just to modify global styles would possibly be confusing to users if they see both Customizer and Site Editor.

I won't comment on the confusion, but it would not be without precedent if #42729 is merged.

[cbirdsong]

The ability to easily generate a "kitchen sink" gallery of native blocks would be amazing resource for custom hybrid theme developers in addition to users editing global styles.

[daveloodts]

@mtias now that the Style Book is launched in Gutenberg under the FSE-umbrulla. How can non-FSE themes use that Style Book feature?

[annezazu]

@daveloodts there's not currently a way to do this right now as it's tied into the overall Styles system itself that this issue pertains to.

[daveloodts]

@annezazu i know it is not possible, and that is the saddest aspect to note here. That WordPress core builds something awesome that is very useful for "the block editor". Not specific FSE, but "the block editor". I know it's built in the "framework" of FSE, but then again... if "they" want the block editor to be more adopted, "they" need to build for inclusion.

The leadership and Foundation has it's mouth full of inclusion. This is a fine example of building something non-inclusive. In my experience, it's the first time that core builds something great, but it can only be used by the type of theme that you use. It is just not right. Like i said: the 'kitchen sink" style is a feature of the Block Editor, not the FSE-editor. Or do 'they' think that hybrid themes are gonna go away...

With all the resources that are pinned on FSE-development, this task is probably not big of a deal compared to other FSE-tasks. It could be built in a page template, like WordPress also creates privacy pages.
So, it's a clear choice here wether WordPress respects it's inclusiveness towards all types of themes that heavily rely on blocks. I'm pretty sure this will uplift the adoption for using more blocks in that hybrid theme; and resulting in more awereness about the power that block can do.

[fabiankaegy]

I really like the Style Book and would love to be able to expose it without having to opt into the site editor in hybrid themes. We already have the Block Template Parts available, which are actually loading the site editor in a special mode where it is locked into the template parts feature only.

I could see how something similar could be done for the global styles interface with the style book enabled.

It can be confusing when we have both the Customizer and "Global Styles" available as menu items. I for one would actually like a world where a hybrid theme could opt out of the customizer and the widgets and only rely on the block template parts and the global styles :)

The limiting factor to adopting the full on site editor and block-based themes is that the source of truth of the template is stored in the database. But exposing all the other features that aren't the actual template editing to hybrid themes would be very nice.

[fabiankaegy]

After exploring how feasible it would be to implement this similarly to block template parts, the first step needed is syncing the global styles interface and style book state with the URL. This would be similar to #47002

Once the selection of the global styles and the activation of the style book is accessible via the URL we could add a deep link and some conditional logic to "lock" the site editor to that state.

[mrwweb]

Like @cbirdsong and @fabiankaegy referenced, access to the style book would be really helpful for Hybrid theme developers and users learning about their site. Tons of developers will deliver client sites with a "Style Guide" page, and it would be awesome if that were standardized, private by default, and built into the admin.

"Appearance > Style Guide" 😍

After thinking about it for a moment, I suspect that exposing the Global Styles editing interface probably wouldn't be feasible for hybrid themes. There are simply too many variations on how styles are implemented, and I doubt almost any hybrid themes are implemented in a way where the Global Styles "contract" could be met. I think it's possible (the current theme I'm developing just might be able to work that way), but it's taking a lot of attention to detail and some tradeoffs that I don't love.

[mtias]

Access to style book and editing that purely focuses on block types (avoids elements entirely, which are the ones that wouldn't translate super well to classic themes) could be a good start.

[annezazu]

Access to style book and editing that purely focuses on block types (avoids elements entirely, which are the ones that wouldn't translate super well to classic themes) could be a good start.

Noting this issue on unlocking that as an option that could perhaps then be leveraged: #53432

[ltrihan]

Hi 👋🏻 Indeed, it could be great to have the style book also on hybrid themes.

Even if the FSE is starting to be very mature, in my humble experience in FSE, I still see many cases requiring more developments for which I am "forced" to use a hybrid theme.

Having the style book would be a huge time saver when setting up the graphic charter of a site.

I don't know how this could be envisaged but here are some ideas:

• Find a way to make it accessible on all pages, or via a link in the "Appearance > Style Book" menu.
• if the previous solution is technically impossible, it could be considered to load ALL the blocks in a pattern, given that they are available since version 5.3 including on classic themes.

[t-hamano]

@mrwweb Thanks for the feedback.

So does this mean that hybrid themes don't need global styles? Are these the two reasons why you need the static stylebook?

• To provide a style guide to users or clients
• To preview block-related CSS and styles defined in theme.json

[mrwweb]

@t-hamano I can only speak for myself, but yes, that is it. To clarify "to preview block-related CSS and styles defined in theme.json", I would hope that at least any styles from stylesheets enqueued via wp_enqueue_block_style would be included, if not all styles enqueued for the site editor. My hope is to provide a useful, clean, automatically generated site style guide for testing and editor reference.

[acketon]

@t-hamano I can only speak for myself, but yes, that is it. To clarify "to preview block-related CSS and styles defined in theme.json", I would hope that at least any styles from stylesheets enqueued via wp_enqueue_block_style would be included, if not all styles enqueued for the site editor. My hope is to provide a useful, clean, automatically generated site style guide for testing and editor reference.

I agree with @mrwweb, this would be very useful for us as theme developers and managers of a multi-site, multi-network WP environment with thousands of sites and hundreds of themes. Having a "style guide" inside each custom theme for the clients/admins and potentially for testing/QA type work would be very helpful.

[annezazu]

Updated the title to focus on the Style Book and wanted to flag this very related issue around iterating on the Style Book presentation and design: #53431 Another great area for all theme authors, classic/block/hybrid, to chime in.

[jasmussen]

Access to style book and editing that purely focuses on block types (avoids elements entirely, which are the ones that wouldn't translate super well to classic themes) could be a good start.

Here's a mockup that takes a stab at this:

Essentially it gives access to the style book, shown in the site editor by default. Potentially this would also show a path forward for #64409.

[jasmussen]

Following up on the above, here's another iteration that surfaces only the "Styles" section, rather than the full site editor. This might be the simplest place to start:

[jasmussen]

CC: @WordPress/gutenberg-design

[t-hamano]

Essentially it gives access to the style book, shown in the site editor by default.

I agree with this approach.

I understand that the current site editor will evolve into the new admin screen and will eventually be accessible to all themes and all users. Therefore, I believe that the ideal approach would be to provide access to the StyleBook within the site editor, rather than adding a new page such as "Appearance > StyleBook".

However, I think it is necessary to consider in advance what features of the site editor (other than templates) should be exposed to the classic theme, not just StyleBook, and whether it is possible to do so. If all of this is possible, I think the design presented in this comment is probably ideal.

Below is a summary of functions that could be exposed to the classic editor, including the StyleBook, whether they are possible to expose, and whether there are any concerns. Please let me know if my understanding is wrong.

---

Style Book

I think it's very likely that this feature can be exposed to classic themes.

However, in the current stylebook, clicking on a block switches the sidebar content and displays the global styles block screen. If we don't expose the global styles to classic themes, we'll need to prevent clicking on the block.

Navigation

Navigation for classic themes and navigation for block themes (block navigation) are completely different.

If the navigation functionality was exposed to classic themes, there would be two navigation functionalities, which might cause confusion. Some theme developers might expect to be able to expose the entire header or footer as a template part in classic themes and insert block navigation there. However, I think that would be almost the same as block themes.

Styles

At the very least, I don't see any reason to expose this functionality to classic themes that don't have a theme.json.
It's unlikely that a classic theme without a theme.json would provide a JSON file for variations.

Global Styles

As I understand it, styles changed in the global styles UI overwrite the theme's theme.json.

If the global styles UI was to be exposed even though a classic theme does not have a theme.json, it might break the styles and layout that the theme originally intended.

Therefore, I think the global styles UI should not be exposed to a classic theme that does not have a theme.json itself.

Font Library

I think the Font Library should technically be part of the global styles. Therefore, I think it's highly likely that it can't be exposed to a classic theme, which doesn't have a theme.json.

Typography, Colors, Background, Shadows, Layout

These would all be part of global styles, so we probably wouldn't be able to expose them to a classic theme, which doesn't have at least a theme.json.

As for the Layout, I think we couldn't expose it to a classic theme, because the global styles wouldn't know which parts of a PHP template are "content".

Blocks

I expect many classic theme users will want to use this feature to override block styles defined in theme.json to their liking.

If we could expose this functionality, it would allow interactions with StyleBooks to become more dynamic and useful.

---

Considering these things, I think a realistic first step would be to only expose the Style Book.

Below is a simple mockup.

Classic themes have access to the Patterns screen in the site editor via Appearance > Patterns. This is the same as before.

We're adding a button to the sidebar of this screen to open the Style Book. Clicking this button will switch the Patterns screen, currently displayed as the DataViews, to the Style Book.

In a pattern or template part editor canvas, instead of the global styles button, it provides a button to toggle the Style Book.

Clicking the Style Book button will switch to the Style Book which is exactly the same as block themes. However, we won’t see the Global Styles sidebar and won’t have access to its features.

---

My understanding and approach may not be appropriate, so I will send a ping to those who are knowledgeable about stylebooks and global styles in particular 🙏

@youknowriad @andrewserong @ramonjd

[youknowriad]

@t-hamano I'm not sure I understand why you make a distinction between "style book" and "global styles", these are the same things: same UI, same underlying technology.

From my perspective, we can start by exposing all of that to classic themes with theme.json (but I can also see it being useful to classic themes without theme.json, could be opt-in/out)

[youknowriad]

I would add here is that I think this UI to edit global styles is also better than the one we currently have for block themes (buried within the template editor), So I would consider the same solution/design for all themes personally.

[ramonjd]

Thanks for the ping. I wanted to start understanding this and other style book issues, e.g.,

• Style Book: Iterate on presentation and design #53431

And maybe come up with a few tasks to get it moving, so very timely!

I'm not sure I understand why you make a distinction between "style book" and "global styles", these are the same things: same UI, same underlying technology.

I don't want to speak for @t-hamano but, the technology aside, the style book also is a preview of how a theme's styles apply to each block.

One of the advantages is that you can see how styles will apply to blocks that are not featured currently on the editor canvas.

Could that be the motivation between the distinction?

But yes, under the hood, they share a lot.

I would add here is that I think this UI to edit global styles is also better than the one we currently have for block themes (buried within the template editor),

Just checking, do you mean the UI that @jasmussen shared above?

As for these statements:

If we don't expose the global styles to classic themes, we'll need to prevent clicking on the block.
Therefore, I think the global styles UI should not be exposed to a classic theme that does not have a theme.json itself.
These [Typography, Colors, Background, Shadows, Layout] would all be part of global styles, so we probably wouldn't be able to expose them to a classic theme, which doesn't have at least a theme.json.
As for the Layout, I think we couldn't expose it to a classic theme, because the global styles wouldn't know which parts of a PHP template are "content".

as far as know I think they're valid.

[youknowriad]

Just checking, do you mean the UI that @jasmussen shared #41119 (comment)?

yes

[t-hamano]

why you make a distinction between "style book" and "global styles", these are the same things: same UI, same underlying technology.

I understand this.

However, there are also opinions that the Style Book does not necessarily need the global styles in non-block themes, and would like to use them as a kind of "Style Guide" (see this comment).

Of course, if it were possible to expose the global styles (or other site editor features) to non-block themes, I think the design proposed in this comment would be ideal.

I proposed exposing only the Style Book as a first step to exposing site editor features to non-block themes.

[youknowriad]

I proposed exposing only the Style Book as a first step to exposing site editor features to non-block themes.

Are you saying we should expose the Style Book without the Global Styles sidebar? Just trying to understand. Because from my perspective, if you allow users to change styles for blocks, you're actually exposing global styles. there's no clear cut there.

[t-hamano]

Are you saying we should expose the Style Book without the Global Styles sidebar?

Yes. Personally, I think exposing the global styles and the Style Book at the same time for classic themes has a big impact.

In addition, classic themes that don't have theme.json can now access the Patterns screen of the site editor.

As I understand it, classic themes that don't have theme.json shouldn't be able to use the global styles. In this case, I think it makes sense to expose only the Style Book. Or is it possible to make global styles available to classic themes that don't have theme.json?

[youknowriad]

I'm missing something I think, So you want to expose a "read only" UI?

[youknowriad]

Or is it possible to make global styles available to classic themes that don't have theme.json?

For me this should be the way to go. I don't see too much technical issues with making the global styles available to classic themes. Maybe some exceptions for "global layout" or things like that.

I don't see a style book read only UI as very useful.

[t-hamano]

So you want to expose a "read only" UI?

Yes, I intended that.

I don't see too much technical issues with making the global styles available to classic themes. Maybe some exceptions for "global layout" or things like that.

Thanks for letting me know. If this is possible, it might make sense to expose both the Style Book and the global styles at the same time.

[mtias]

I think the global styles UI should reflect the state of the theme.json support regardless. It doesn't make sense to see the "Background" item on a classic theme if it's not supported, but it'd be useful to modify the color palette if that one is.

[mrwweb]

@youknowriad

I don't see a style book read only UI as very useful.

There are many comments on this thread asking for exactly that for the purposes of creating a Style Guide page and QAing theme styles.

[ltrihan]

@youknowriad

I don't see a style book read only UI as very useful.

There are many comments on this thread asking for exactly that for the purposes of creating a Style Guide page and QAing theme styles.

Indeed, without wanting to repeat myself, having the style book would be a huge time saver when setting up the graphic charter of a site. It can be a powerful tool for the designer and the theme developer.

[masteradhoc]

@ltrihan totally second your opinion. The Style Book is a unbelievable asset which gives you a great overview as a developer and graphic designer if the base settings are correct or adjustments have to be made. I'd love to see this as a feature also for classic themes - even if it means for the moment its only a read only mode that can be activated manually.

@ramonjd is your PR everything thats needed here or more work needs to be done?

[ramonjd]

Hi @masteradhoc!

is your PR everything thats needed here or more work needs to be done?

Do you mean WordPress/wordpress-develop#7336? That PR dips its toe in the water only, but it's the right pool if you get my metaphor.

To be honest, I'm not yet confident I know how things will proceed but if pressed, I'd speculate:

• The style book should be accessible from the admin bar for classic themes, which means
• it should be capable of being self contained, outside a site editor environment, but
• still able to consume global styles and render block lists, and at the same time
• can be dropped in a site editor context and interact with controls — for example, clicking on blocks opens the global styles for that block — for block themes.

Note there's nothing technical there, but #53431 does capture a lot of the momentum.

I agree it would be useful tool to abstract and make available to all themes that support theme.json.

Edit: Might be interesting for folks:

• Update: Make the styles sections a preview of the style book with a l… #65619