Allow creating and editing custom block style variations in Global Styles

[tellthemachines]

#46343 added the ability to edit block style variations in Global Styles. That was only part of the scope of the initial issue (#44417), but further steps required a few changes to be made to the global styles APIs. Now that #47098 is done, it should be straightforward to add new variations from the global styles UI.
Also, given the addition of per-block custom CSS in #46571, we could consider:

• adding a custom CSS field to block style variations, which would open the door to
• making custom block style variations editable. Even if custom styles are added via a stylesheet instead of theme.json, having a custom CSS field would allow for easy overrides.
• it should also be possible to add custom block style variations via theme.json.

[annezazu]

Noting that "needs design feedback" has been added to this issue and it's been added to the "Needs design" column. While there are designs on the original issue for development to get started, it's advantageous to have design reviewing once more with how much has evolved around 6.2. Leaving this for coordination purposes @WordPress/gutenberg-design as development will start but will need assistance.

[SaxonF]

Once this branch is finished we might be better served using the same variant interface as what's found in local styles so that it's familiar.

[carolinan]

it should also be possible to add custom block style variations via theme.json.

Should this register a new style variation? Or would it still require register_block_style()?
If it could be done via theme.json only, developers may be able to remove more PHP.

PR for outputting the CSS:
#49396

[jasmussen]

Here are two mockups that expand on Saxon's sketch above (and Saxon please feel free to correct anything in the Figma if I missed a beat).

Just as orientation, an ellipsis menu in the Styles panel could take you to where those variations are managed, i.e. Global Styles:

Once there, styles would be edited just as Global Styles → Blocks are:

Note that the above mockup shows using the regular panels instead of the drilldowns. I could go either way on this, but such a change should likely be implemented separately if need be; the main point is to edit a variation as if it were a block in Global Styles.

[SaxonF]

@jasmussen with #49428 the global view will be consistent with the local view, so the thought was the variant selection / modifying should also work the same way. ie no drill down. You just select the variant as you do in local, then make any changes. Clicking the plus adds a new variant.

add-variant.mp4

This way it's also consistent with how you could make local changes and "push to global" if a block has variants.

Obviously this means 49428 has to land first so will spend some time on that this week.

[jasmussen]

Oh cool, thanks for sharing that video. I've personally not too strong an opinion on whether we do the ItemGroup + Drilldown or the "style buttons as tabs", so I suppose implementation wise the path of least resistance can be chosen. Thanks Saxon.

[carolinan]

Please reconsider the horizontal buttons with the block style names. It is difficult to use them when the names are truncated.
I will share the issue where users has left feedback about these buttons, once I find it 😬

[jasmussen]

For what it's worth, the style of those buttons could be explored and improved independently of their behavior of acting as tabs in this state.

[jameskoster]

I don't have a strong opinion either, but we probably need to think about variation actions beyond create, e.g. delete, duplicate. With the itemGroup approach that could easily be handled in a more menu:

I find it trickier to see how this would work with the button approach. Did you have an idea @SaxonF?

[paaljoachim]

I have revisions in the back of my mind right now. This PR: #46667
Let's say that we have a method to seeing what was adjusted in a revision. We could transfer the same method over to viewing a style variation. As a specific style might be made up of various adjusted settings.

In this case it would mean seeing an overview of style variations and then clicking these to open these up to show what they are made up of. Seeing each individual setting and value which makes up a specific style variation. Perhaps similar to what James shared here: #37037

It would create a consistent experience in viewing an item. Be it a revision or a style and perhaps other items which are made up of smaller pieces.

[SaxonF]

Is there a case where we use ItemGroup as a selection mechanism? It seems its generally reserved for listing items like elements and revealing more about them via drill down or popover.

What about following a pattern similar to Keynote and Figma by using a Dropdown/Select?

variant-selection.mp4

For what it's worth, the style of those buttons could be explored and improved independently of their behavior of acting as tabs in this state.

I agree with @jasmussen here that we could pull variation selection out into its own issue, possibly grouping with a "delete variation" action.

[oandregal]

#49827 is experimenting with the API for registering/unregistering style variations from theme.json (no UI, just being able to control style variations lifecycle from the theme.json).

[jasmussen]

Let's unstick this. It seems like the outstanding feedback is whether to use ItemGroups or a dropdown or something else, but the remaining pieces of these mockups are solid. Is that right?

If yes, then I'd like to update this issue and move it to a dev. The ItemGroup is already widely in use in Global Styles, so if we want to move to something else that seems best to create an issue for separately, and then do it in one fell swoop:

[fabiankaegy]

Hi all 👋

It's been a wile since this issue saw any movement. Is there anything one can do to help move it forward?

The ability to define block style variations that actually use the underlying block settings instead of just a custom class name is soooo valuable and it would really help us implementers by having to build way fewer completely custom block extensions to achieve a similar result :)

[unscripted]

It's been a wile since this issue saw any movement. Is there anything one can do to help move it forward?

I want the full functionality that @tellthemachines defined in this issue. However, as defined, feels a bit more like an epic.

I view this as four potential "features" where some focus on providing the support to the developer others open it globally via the UI.

1. Add ability to style custom variations in theme.json.
2. Add ability to edit/save custom variations in the global style editor.
3. Add ability to register custom style variations in theme.json.
4. Add ability to create/delete custom style variations in the global style editor.

IMO, this should start by supporting the developer with adding support to style custom variations in the theme.json that are registered via register_block_style in PHP or wp.blocks.registerBlockStyle in JS.

[aaronrobertshaw]

Hi @unscripted 👋

Thanks for the feedback!

The four features you outlined are definitely on the radar for block style variations. To varying degrees, features 1-3, are being worked on as a means for providing easier styling of sections.

I'm not sure if they'll make it into WP 6.5 but you can follow the latest on this section styling issue and some of the related PRs:

• Theme.json: Extend block style variations support #56540
• Block Styles: Extend block style variations as mechanism for achieving section styling #57908
• Theme.json: Allow shared block style variations via separate theme.json files #57787

[onetrev]

Can I suggest this be moved to be a high priority please? Or maybe this is an issue for Create Block Theme, but because of this issue right now if you make any changes to a custom block style variation and then use "Save Style Changes" in Create Block Theme, all your custom style variation changes are lost -- without warning.🤦

[aaronrobertshaw]

Hi @onetrev 👋

To know whether this is an issue with Create Block Theme or style variations within core/Gutenberg, it would be helpful if you could share some steps on how to replicate the problem. Perhaps in a dedicated issue as this issue is related to enhancing a current feature rather than addressing a bug.

I've quickly tried:

1. Creating a new blank block theme via the Create Block Theme plugin
2. Customizing the button outline block style variation
3. Confirming the customized block style variation displays as I defined it
4. Creating a clone of a theme with custom block style variations
5. Customizing the custom block style variations of the cloned theme in the site editor
6. Applying the custom block style variations and confirming display in both editor and frontend

The above all worked as I expected. I'm not greatly familiar with Create Block Theme so there is a good chance I'm missing something.

After the smoke testing above, I suspect it might be an issue with Create Block Theme. Maybe the best path forward is to submit a bug on the Create Block Theme repo. It can be debugged from there and any fixes or updates needed in Gutenberg can be created in turn.

Thanks for flagging the potential issue 👍

[onetrev]

Hey @aaronrobertshaw, appreciate you quickly trying this out. I can see right away though where you went wrong.

You were customising a core included block style variation. The issue is if you have your own custom variation you've added via PHP or JS in your theme. :) In that case, as noted in the same docs above you can't style these via theme.json, and it links to this very issue. And because you can't style them in theme.json, then Create Block Theme fails to save them. Or so I believe.

[aaronrobertshaw]

You were customising a core included block style variation

@onetrev, see step 4 in what I tried: "Creating a clone of a theme with custom block style variations". These custom style variations were defined in my test theme using theme.json partials under /styles and via register_block_style passing style_data.

In that case, as noted in the same docs above you can't style these via theme.json

If only defining a traditional Block Style without any accompanying style data (whether passed to the block style registration function or from theme.json files), you are correct they can't be customized via Global Styles. They should still be available in your created theme though.

Here are a couple of recent posts around using custom block style variations and how they can be customized in Global Styles.

• Section Styles Dev Note
• Styling sections, nested elements, and more with Block Style Variations in WordPress 6.6

The developer handbook documentation is currently in the process of being updated to reflect the latest iterations to Block Styles.

if you make any changes to a custom block style variation and then use "Save Style Changes" in Create Block Theme, all your custom style variation changes are lost

This is the part that confused me most as you shouldn't have been able to make any customizations to regular Block Styles registered via the approach you linked above.

To the point of your original comment, being able to create custom block style variations via Global Styles directly would save needing to manually define block style variations with style data within the theme. This would certainly cut down the potential for error.

This enhancement for the feature is definitely on the cards but as noted in the linked dev note there is quite a bit of UI work required in Global Styles before a nice user experience can be achieved there.

[onetrev]

Hey @aaronrobertshaw ... I should have done this sooner as there has been confusion. I have created screenshots, which make it super clear the process and 100% confirming this issue, which I would say is a pretty major bug.

1. Using Twenty Twenty Four theme and WP 6.6.1.

2. Created a Block Style Variation, whether created by JS, PHP, or Section Style, the same issue occurs. I used Section Style for this demo, since it's the fastest, so let's stick with that for recreating it.

3. Here's the current style it set in my section style for a new custom block style for a button called "Fancy Button". It has black bg, white text.

4. Now using the Site Editor "Styles" editor, make some changes. I made the bg orange.
   

5. Save changes with Create Block Theme, ensuring "Save Style Changes" is selected.
   

6. Boom! All your styles are gone, the original block variation styles are back as they are not saved to your theme.json and the database changes are removed (the latter is supposed to happen since that's what Create Block Theme is all about).

7. Sadness rains down. :)

[aaronrobertshaw]

@onetrev, thanks for the extra replication steps 👍

They do make it clear the issue is with the Create Block Theme plugin, not Gutenberg. I'm not familiar with the inner workings of that plugin so you'll need to create an issue on the plugin repo.

From my latest round of testing, I could only replicate the issue when the changes to Global Styles hadn't been saved using the Gutenberg "Save" button first. The issue also occurs when styling a general block type, e.g. setting a background color on paragraphs.

Screen.Recording.2024-08-12.at.12.22.32.PM.mp4

So my thinking is:

1. It's an issue with the Create Block Theme plugin, using Gutenberg's save works fine
2. The issue isn't related to block style variations, given the same behaviour with general block type styles etc, so this GitHub issue isn't related
3. Next steps for debugging, over on the new issue to be created in the Create Block Theme repo, would be to check if there actually has been a regression or if this has been the established behaviour for a while

Sadness rains down. :)

Hopefully, knowing you can hit the Gutenberg save first to make Create Block Theme work as you expected will alleviate some of that sadness until the plugin can be updated.

[onetrev]

Amazing @aaronrobertshaw you did this screencast. Thank you. After carefully observing I did further tests, and unlike you I had the same problem. I was always using the "Save" button, my style edits always reverted unlike yours.

So after a lot of time and even more testing, I wondered if you were running the Gutenberg plugin? My guess is yes. Reason being, with the Gutenberg plugin running then yes as long as you save your edits first in the editor (like you demonstrated) then it DOES work.

In conclusion, I'd stay this is still an existing bug with WP 6.6.1 + Create Block Theme, which is resolved somehow by using the Gutenberg plugin. Which seems odd. This fact is why I'm reticent to submit this in Create Block Theme yet. If you want to test again, please do. But please make sure you start over with a clean version of TT4, no edits made to theme.json. Cheers!

[aaronrobertshaw]

@onetrev we need to try and avoid hijacking this issue further as it is unrelated to what you're wrestling with. There is no problem with creating a separate issue and continuing the discussion there.

Feel free to ping me on the issue and I'll try and continue assisting. Thanks 🙏

[onetrev]

Sorry! I was feeling this issue belonged here because the problem is Create Block Theme is trying to write the styles to your theme.json file and it's not supported, so what happens in nothing gets written, but Create Block Theme clears all db edits expecting the edits were saved to your theme.json file. The last bullet in the OP says:

it should also be possible to add custom block style variations via theme.json.

This is also noted in this "alert" box in the docs. Either way, good point on not polluting this further and I'll move this issue to Create Block Theme as well so that maybe something can be done in the near term to avoid people losing their edits.