Allow creating and editing custom block style variations in Global Styles

#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.

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.

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.

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

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.

@jasmussen

@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.

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.

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 😬

@onetrev

@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 🙏

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.

@aaronrobertshaw

Hi @aaronrobertshaw,

Revisiting this feature request.

When building themes with the block editor we often want multiple design variants of the same core block (e.g. primary button, secondary button, outline button, subtle button, button for cards, etc.).

Am I right that this currently requires to register block variations and style it outside of the theme.json or create entirely separate custom blocks?

Ideally it would be possible to define block variations directly in theme.json. This would make it much easier to create design variants of core blocks

I’m curious if something like this is being considered or is anywhere on the roadmap.

@WinsleyJ

Hi @WinsleyJ 👋

There are still plans as per this issue to allow managing block style variations via the Global Styles UI. Unfortunately, there have been competing priorities that would yield greater rewards, so this has remained on the backburner.

Am I right that this currently requires to register block variations and style it outside of the theme.json or create entirely separate custom blocks?

If I understand the question correctly, no, you can register the block style variations within the theme.json.

You can find more information here: https://make.wordpress.org/core/2024/06/24/section-styles/#defining-block-style-variations

I would recommend using theme.json partials under the /styles directory as detailed via the post above.

Just want to say it would be really great to have the ability to create custom Block Style Variations in core. Right now it feels like maybe the biggest missing feature when implementing a Block Theme fully on a live site, as you have no real way to organize repeating styles and you end up making a mess. It would also be super useful even when developing locally and saving theme files to Git, as it would allow prototyping and refining all within Global Styles, rather than jumping between JSON files and the Theme Editor.

Short of that it would be really good if we could at least customize Block Style Variations registered with register_block_style() using the Global Styles editor. AFAICT doing so is not currently possible, you must have them as JSON files to be able to edit them. If we were able to customize register_block_style() variations then a plugin could be created that let you define empty variations that would then be managed in Global Styles. As-is it seems the only such plugin that could be created would have to add files to your live theme directory, which strikes me as a very bad approach and the reason that plugin doesn't currently exist (again, AFAICT).

Good luck to anyone trying to push this overall feature forward! It will be a huge win for people who want to create no-code block themes that still follow professional-grade DRY principles!

@jerclarke

Hi @jerclarke 👋

Short of that it would be really good if we could at least customize Block Style Variations registered with register_block_style() using the Global Styles editor.

You can. This was added when block style variations were implemented in WordPress 6.6.

There's more info in the core Section Styles post but the short version is, register_block_style can take a style_data array, any variation with a non-empty style_data array is editable via Global Styles.

@aaronrobertshaw

Thanks @aaronrobertshaw you pointed out what was missing: I was comparing file-based .json variations that had a styles section to PHP registrations that didn't have a style_data, and didn't realize that was the key difference. In both cases, if there's no "style" defined they don't show up in the editor, I just didn't have a PHP one around that used styles that way.

Multi-block variations still can't be edited though, right?

After some more testing, I guess the main things missing are the ability to create custom variations using the UI (of course) and the ability to edit variations in a "multi-block" way. I got my plugin working to register custom variations with PHP, and even to register them for multiple blocks, but if I edit them with Global Styles, they end up being "separate" for each block, both in how they work and in how they show up in style.json when saving the theme with Create Block Theme. That's the intended behavior, it seems, just noting it in case it helps someone else on the same journey as me. It's weird that you define a multi-block variation then it silently gets converted into two single-block variations with the same name. It's not very intuitive and of course limits our options in building robust design systems.

@jerclarke

Multi-block variations still can't be edited though, right?

@jerclarke I'd encourage you to take a look at the Section Styles post I shared.

That shows you examples of defining a single block style variation that is available across multiple block types. See the blockTypes property in theme.json partials for section styles.

to edit variations in a "multi-block" way.

This is currently via the theme.json partial noted. In future it would be via the proposed overhaul to the Global Styles information architecture. I'd imagine editing the generic base version of a block style variation in the "multi-block" way, would be the top level of global styles would have a variations option that can be drilled into and that offer the ability to configure the selected block types i.e. configure the variation's blockTypes property.

but if I edit them with Global Styles, they end up being "separate" for each block... That's the intended behavior, it seems

Correct. This is by design so a block can define its own tweak to a shared variation.

It's weird that you define a multi-block variation then it silently gets converted into two single-block variations with the same name. It's not very intuitive and of course limits our options in building robust design systems.

Personally, I'm not sure I agree with this. Especially in the absence of use cases or examples where an issue is demonstrated. Perhaps you could expand on this point? It would assist in shaping any future direction here, I'm sure.

That said, this is a separate discussion to creating and editing block style variations within Global Styles. It is a lower level shift in the implementation and probably warrants its own standalone issue.

It's weird that you define a multi-block variation then it silently gets converted into two single-block variations with the same name. It's not very intuitive and of course limits our options in building robust design systems.

Personally, I'm not sure I agree with this. Especially in the absence of use cases or examples where an issue is demonstrated. Perhaps you could expand on this point? It would assist in shaping any future direction here, I'm sure.

Hmm, the value seems obvious to me. I can already make a variation with JSON that can be applied to multiple blocks, thus allowing me to make different elements match as part of the design system:

{
	"$schema": "https://schemas.wp.org/wp/6.7/theme.json",
	"version": 3,
	"title": "Big & Grey",
	"slug": "text-big",
	"blockTypes": ["core/heading", "core/paragraph", "core/list", "core/quote"],
	"styles": {
		"color": {
			"text": "var:preset|color|accent-4"
		},
		"typography": {
			"fontSize": "110%",
			"lineHeight": "1.5"
		}
	}
}

So assuming that has value, I think it's kind of self-evident that there's value in being able to customize that kind of variation in the context of Global Styles, while keeping it applying to the same set of block types. E.g. If I was updating a site that had that variation on it, I could go in and choose a new color rather than grey, while keeping them all synced up.

That said, this is a separate discussion to creating and editing block style variations within Global Styles. It is a lower level shift in the implementation and probably warrants its own standalone issue.

Agree it could be another ticket. That said, as the system for adding variations is considered, there's probably some important architectural decisions that would affect whether it would also work in a system where multi-block variations are supported in Global Styles.

To be clear, you referred to editing a variation via Global Styles which is only available at a per-block-type level at present. It only makes sense for editing a variation within UI specific to a single block type that it affects that single block type only.

See my previous reply for something I think could make sense for editing a shared variation:

I'd imagine editing the generic base version of a block style variation in the "multi-block" way, would be the top level of global styles would have a variations option that can be drilled into and that offer the ability to configure the selected block types i.e. configure the variation's blockTypes property.

In other words, in the Site Editor navigate to something like: Styles > Variations > "Shared variation name", then style that or configure the blocks to which it is available.

Additionally, as block style variations work now, any shared definition is simply a shorthand to avoid redefining the same definition for each separate block type. The result is still ultimately a single style variation per block, just as Block Styles always have been for block types.

Additionally, as block style variations work now, any shared definition is simply a shorthand to avoid redefining the same definition for each separate block type. The result is still ultimately a single style variation per block, just as Block Styles always have been for block types.

The idea that a multi-block variation is just shorthand for multiple single-block variations is an eye-opening description, though I don't think it's the best approach. When editing it as a .json file for multiple blocks it feels like a shared variation, and it feels good and logical that it's shared, since the name and CSS class are the same and it's a good way to build a design system across blocks. Being able to work in this way while using the GUI rather than editing files is a natural extension of the concept.

I think ideally treating them as "Shared" and making the customization (and creation) experience make sense would be a good thing. As you say, it would make sense to have a "variations" ui at the global level, though I think you'd also want/need "multi-block variations" to work from the Styles > Blocks > {block} > Style Variations view. It wouldn't be simple, but it would make sense if that interface "knew" when a variation applied to various blocks, and organized the available options around ensuring that the resulting mix of styles were all appropriate for all affected blocks.

So I guess I'm throwing a vote out there for "multi-block variations" as an organizing principle, rather than a side effect of a shorthand notation.

Either way thanks for the replies Aaron, appreciate you taking the time 🙏🏻

though I think you'd also want/need "multi-block variations" to work from the Styles > Blocks > {block} > Style Variations view

I think we're over complicating this concept.

Shared variations can apply to multiple block types. This makes these shared variation "global" in nature as they aren't owned by a single block type. Therefore, Styles > Variations is the right home for them.

Anything specific to a single block type, relates only to that block type. So the right home for these is Styles > Blocks > Block Type > Variations. This would operate as it does now. When global styles/theme.json are generated the shared definition populates the block type specific variations property.

There is a discussion to be had on the expected UX when editing a shared variation after a block type has already tweaked its version of the variation styles. Should the updated shared variation be merged with the per-block-type edits, or is it expected that the user edit variation styles for that block type remain steady. That is tangental to this issue though and more of an implementation detail.

So I guess I'm throwing a vote out there for "multi-block variations" as an organizing principle, rather than a side effect of a shorthand notation.

To me, this still sounds like over complication. We can just have "block style variations". When defined at the global level or via theme.json style partials, they can define allowed blocks. When within the block type's own definitions that's already implicit. How that is represented in the UI has already been covered. There's only a question of whether to merge edits or not.

So to this issue's main thrust about creating and editing block style variations in Global Styles, there's no need to create new concepts or terminology. We already have too much in that regard 😅

You make good points, and indeed my head starts to spin because conceptually it's very complex.

But I'd stand by the following points:

When you edit the global styles for a block, and look at the list of Style Variations, you should see all of them, including ones that apply to multiple blocks.
If you then click and edit it, it should continue to apply to the same blocks, rather than forking into a variation with the same name that now applies to just one block.
To make that successful, it seems to me we need a UI for variation editing that understands when they apply to multiple blocks, and adjusts the UI accordingly.

So while it would be good to have a global top-level list of style variations that apply to multiple blocks, I think you should also be able to access them by going to the block itself and clicking on the variation there.

While it wouldn't be simple, I think the most forward-looking solution is to make "multi-block" variations an inherent part of the "add variation" system, and make all contexts where you edit variations multi-block-aware.

When you edit the global styles for a block, and look at the list of Style Variations, you should see all of them, including ones that apply to multiple blocks.

Agreed. Global styles already does this for a block type.

If you then click and edit it, it should continue to apply to the same blocks, rather than forking into a variation with the same name that now applies to just one block.

I don't agree with this. A user should be able to customize a block style variation for a specific block type regardless of whether it was originally defined as a shared block style variation or not. This was a requested use case with the initial implementation of the feature.

To make that successful, it seems to me we need a UI for variation editing that understands when they apply to multiple blocks, and adjusts the UI accordingly.

We would with the proposed Styles > Variations UI. If you edit there it's the shared version. The Styles > Blocks > Block Type > Variations UI would be for the individual block type only.

I think you should also be able to access them by going to the block itself and clicking on the variation there

This is more a navigation issue which could be solved with an appropriate design, perhaps a link back to shared variations at the global level.

While it wouldn't be simple, I think the most forward-looking solution is to make "multi-block" variations an inherent part of the "add variation" system, and make all contexts where you edit variations multi-block-aware.

In the discussions I've had, this conceptually is simple, though.

Global level is shared. Block type level is not shared.

If you are in Styles > Variations, adding a variation there is inherently global and shared as it would allow assigning allowed block types to it.
Adding a variation while at Styles > Blocks > Block Type > Variation has that implicit context that all styles there are for that block type only, so too would a variation created there.

and make all contexts where you edit variations multi-block-aware

This is essentially the main point I can't get behind, it doesn't make sense to make everything editable in all places. Perhaps it's worth spelling out why with an existing parallel:

We already have shared styles at the global level, like text color, that apply across block types. If you then set a text color on a single block type, we don't push that edit back into the shared/global definition. The block type value overrides the inherited one. Block style variations should be that same well-known model. The shared definition is inherited and merged into each block type's styles like a default. Editing the shared definition happens at the global level, and block-type-specific overrides happen at the block type level. The end result is the same as how inheritance already works everywhere else, which is why we don't need a new multi-block variation editing solution within the context of a block type's global styles UI.

Navigation Menu

Repository navigation

Allow creating and editing custom block style variations in Global Styles #49602

18 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Allow creating and editing custom block style variations in Global Styles #49602

Description

Activity

annezazu commented on Apr 6, 2023

SaxonF commented on Apr 11, 2023

carolinan commented on Apr 11, 2023

jasmussen commented on Apr 11, 2023

SaxonF commented on Apr 12, 2023

jasmussen commented on Apr 12, 2023

carolinan commented on Apr 12, 2023

18 remaining items

aaronrobertshaw commented on Aug 12, 2024

onetrev commented on Aug 13, 2024

WinsleyJ commented on Mar 10, 2026

aaronrobertshaw commented on Mar 10, 2026

jerclarke commented on Jul 21, 2026

aaronrobertshaw commented on Jul 22, 2026

jerclarke commented on Jul 27, 2026

aaronrobertshaw commented on Jul 27, 2026

jerclarke commented on Jul 27, 2026

aaronrobertshaw commented on Jul 27, 2026

jerclarke commented on Jul 27, 2026

aaronrobertshaw commented on Aug 4, 2026

jerclarke commented on Aug 4, 2026

aaronrobertshaw commented on Aug 4, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions