Style variations for block types

[jameskoster]

Block style variations are preset block designs. A button defaults to being filled, but has an outline variation. We could expand this system so that it was possible to edit style variations, as well as creating new custom ones. For example, I might want to create a paragraph style with a slightly larger font size and a drop-cap for occasional use in my posts / pages. By creating a Style, I am empowered to update all blocks utilising that style at once, whereas currently I'd need to update all blocks one-by-one.

You might find access to managing style variations in an ellipsis menu:

Style variations would show up in a list below other block-specific properties, in Global Styles → Blocks → Block name:

Style variations can be conceptually thought of as fitting somewhere between "Theme" and "User" in the style hierarchy, so any customizations you apply exist on top of existing values, rather than replacing them:

This would let you edit a style variation globally, and all blocks using that variation get updated as a result.

Note that this particular aspect needs a little further thought, please see the comments below as well.

Related: #44361

---

Issue updated Nov 11.

Initial proposal

Theme style variations allow users to change the look and feel of their entire site in a few clicks:

It would be interesting to explore how we might apply this concept to individual blocks in global styles. For example, I might want to create a paragraph style with a slightly larger font size and a drop-cap for occasional use in my posts / pages. By creating a Style, I am empowered to update all blocks utilising that style at once, whereas currently I'd need to update all blocks one-by-one.

We can hopefully connect this to the current block style system, giving folks control (create, update, delete) over styles like the one we find on the Button block:

Related: #44361

[phil-sola]

This definitely sounds like a nice addition to Global styles in the site editor. I can see that being powerful and enabling users to completely change the look of their sites with the blocks they are using with one click.

Imagine your buttons all changing, or as mentioned above a specific paragraph style being implemented site-wide with this type of settings.

[jameskoster]

Here, I imagine that the link breaks:

Yes good point. Breaking the link is definitely an option.

An alternative to consider: we might maintain the link but (somehow) mark the style as being edited locally. From there you can either leave the changes local, push them to the variation, or perhaps even create a new one. To make this work we'd probably need to include a "Default" option in the styles panel, meaning to use the base configuration from global styles.

I suppose another consequence with this approach is that you could theoretically do without the Manage styles view altogether – you'd inherently 'managing' them all the time. Not sure if that's a good thing or not :)

At that point I guess this begins to overlap with #44361 quite a bit.

[jasmussen]

An alternative to consider: we might maintain the link but (somehow) mark the style as being edited locally. From there you can either leave the changes local, push them to the variation, or perhaps even create a new one. To make this work we'd probably need to include a "Default" option in the styles panel, meaning to use the base configuration from global styles.

There's already a default style, good point, I suppose all style can just be additive. I.e. this:

— The link is still there, I just added a 4px border which wins.

[jameskoster]

If you saved there, would the border be applied globally?

I was thinking something more along these lines (but with something better than the *):

[jasmussen]

If you saved there, would the border be applied globally?

No, I don't think the link actually has to be more than what exists today in terms of base styles that get overridden, classic CSS style, by local changes. That would let us keep this and keep the "push to global" from 44361 separate. I'd agree, it should push to the active style variation, but that we wouldn't need to do more here.

Let me share an example. I've thought a bit about how solid and filled buttons could coexist with the same height, yet still use the border tool, and I would imagine the base CSS was something like this:

.wp-block-button__link {
	background: black;
	color: white;
	border-width: 2px;
	border-style: solid;
	border-color: transparent;
}

That is, default style and width, and a border even on the solid version, just transparent. Then an outline style would simply change the colors:

<a class="wp-block-button__link" style="background-color: transparent; border-color: currentColor;">Outline</a>

Now what happens if I change the border width as in the mockup? This:

<a class="wp-block-button__link" style="background-color: transparent; border-color: currentColor; border-width: 4px;">Outline</a>

What happens if I change the border-color? Either of the following two, depending on developer feedback! First option: it just appends the border-color property at the end, letting it win the fight:

<a class="wp-block-button__link" style="background-color: transparent; border-color: currentColor; border-color: #ff0000; border-width: 4px;">Outline</a>

... but ideally, it would replace the border-color rule that was otherwise inherited from the style variation, like so:

<a class="wp-block-button__link" style="background-color: transparent; border-color: #ff0000; border-width: 4px;">Outline</a>

But at the end of the day, it would be the style hierarchy from #20331, just with "Style variation" wedged between theme and user. What do you think?

[jameskoster]

Yes that sounds fine to begin with, though it will recreate this issue, for block style variations. It's probably not such a big deal here though.

[jasmussen]

Hmm, would it actually? Just working through a matrix for the Button example:

1. I have a default Fill button and change the border color to yellow, then switch it to outline. Border stays yellow.
2. Same, but I push the yellow border change to be global first. From outline, I clear the yellow border color, and it's black, because "Outline" sets it to currentColor. Switch back to "Fill", and border becomes yellow.

In which flow do you see style "loss" by switching?

[jameskoster]

Oh, I misunderstood. I thought that switching styles would remove customisations. In this case you're correct there would be no loss.

However, don't the style buttons lose some meaning this way? Say for example the Outline style has yellow text by default, you make the text green, then switch to fill, then back to outline, your green customisation persists. So how do you reset back to the default config for the Outline style?

Edit: I suppose you would just reset here:

Is that obvious enough?

[jasmussen]

It's hard to say without diving into a PR, but I think of the styles as literal variations that you build additional styles upon. But it may be there are intricacies coming into clarity when technical input lands.

[jameskoster]

I have a small concern that it won't be obvious when you're using a variation a la carte, and when you're using a customised version, and that could lead to inconsistencies across a site. But I agree it's hard to know how much any of this matters until we can get a feel for it. Apologies for the slight detour, I think your latest designs look good (pending any other feedback)!

[jasmussen]

Cool, good thoughts. I'll tentatively update the issue, add the uncertainties, and hopefully technical input can clarify a few things which I can follow up on.

[tellthemachines]

Looking into this, I have a few questions 😄

• From the discussion above, it seems we want style variation customisation to exist in a Global Styles panel, which may be linked to from the post editor sidebar, is that right?
• Should we only be able to customise Core style variations, or also 3rd party ones? (3rd party could come from either theme or plugins)
• Should these customisations be preserved on theme switch?

An initial thought about implementation: we'll probably be looking at a similar mechanism to the one we use for global block style customisation, so something like:

.wp-block-button .wp-block-button__link {
    background-color: #9b538c;
    color: var(--wp--preset--color--white);
    font-size: clamp(1.35rem, 1.35rem + ((1vw - 0.48rem) * 0.865), 1.8rem);
}

Default variations styles attach themselves to the block+variation classname, like so:

.wp-block-button.is-style-outline>.wp-block-button__link:not(.has-background), .wp-block-button .wp-block-button__link.is-style-outline:not(.has-background) {
    background-color: transparent;
    background-image: none;
}

We'd probably want the output for a variation customisation to be something like the second example.

Another open question is how style variations are shown in the UI; I would assume that they would need to migrate from being CSS classes (is-style-rounded) to becoming design tools presets (a la border-radius: 9999px;)

Global styles/style variations will have to be attached to classnames, because otherwise existing blocks with those variations won't get updated when the styles change. There's also the issue of specificity, as global styles should never override local block-specific ones. This should work fine because block-specific are always either inline, or rule sets with !important 😅

— do those values need to be shown in the UI when picking a preset? In these designs, I omitted that intentionally so that if you go back and edit a style variation, there is a link in place so all blocks using that style variation get updated.

Do you mean should the UI for changing the style variations display existing values for the editable properties? If within the global styles interface, this should be possible. Where we usually run into problems is displaying global styles values in the post editor.

[jasmussen]

From the discussion above, it seems we want style variation customisation to exist in a Global Styles panel, which may be linked to from the post editor sidebar, is that right?

The link is a bonus, but yes. It's a deep-link to where style variations are managed, which just happens to be globally.

Should we only be able to customise Core style variations, or also 3rd party ones? (3rd party could come from either theme or plugins)

There's a technical question here, as existing style variations are CSS based, i.e. with hard-coded values in block style.scss files, i.e.

	// Variations
	&.is-style-rounded img,
	.is-style-rounded img {
		// We use an absolute pixel to prevent the oval shape that a value of 50% would give
		// to rectangular images. A pill-shape is better than otherwise.
		border-radius: 9999px;
	}

For all core blocks, I would hope that we could move away from these hard-coded values, in favor of design tool presets. That is, instead of applying a CSS class with an attached border-radius, we use the border-radius control. That would also let you override these properties on a per-block basis, which is a nice bonus.

For all these modern style variations, I'd love for them to be editable, even if they originated from 3rd parties (themes/plugins). But it seems impossible to make "classic" style variations editable, simply because they are by definition hardcoded. To handle that, we could do something like this, show a contextual message if classic style variations are present:

What do you think?

Should these customisations be preserved on theme switch?

Good question. My take: core and custom style variations, yes, as they'd be saved globally. 3rd party variations, not sure what's possible here. @jameskoster any thoughts?

Global styles/style variations will have to be attached to classnames, because otherwise existing blocks with those variations won't get updated when the styles change. There's also the issue of specificity, as global styles should never override local block-specific ones. This should work fine because block-specific are always either inline, or rule sets with !important 😅

If they have to be attached to classnames, can the CSS for these classes be dynamic so it isn't baked into each block style.scss files?

[jameskoster]

My take: core and custom style variations, yes, as they'd be saved globally. 3rd party variations, not sure what's possible here. @jameskoster any thoughts?

It's difficult when it comes to third party entities because the behaviour you want is likely to be highly situational, so I don't really know if there's a silver bullet solution here. Sometimes you'll want to keep them, other times you won't. Ideally we make it easy for the user to choose how to proceed, though I acknowledge that would involve a lot of extra work.

I'm reminded of #25071, and in the short term I suppose it makes sense to treat customised third party variations the same way we treat customised third party templates (keep them on switch). Un-customised third party variations can be discarded.

[tellthemachines]

For all these modern style variations, I'd love for them to be editable, even if they originated from 3rd parties (themes/plugins). But it seems impossible to make "classic" style variations editable, simply because they are by definition hardcoded. To handle that, we could do something like this, show a contextual message if classic style variations are present:

We can't erase the values of style variations and replace them with new ones, but we can override them with new rules based on design tools presets. In practise, this won't make any difference to users, except that the new rule will maybe be a little more specific. What we might run into when trying to customise existing variations is the inability to override styles there are no design tools for (e.g. custom masks that crop images in a certain way). This is more of an issue with 3rd-party variations, because I think the ones we have in core blocks are pretty standard.

Am I missing any other reasons why we shouldn't override classic style variations?

With the 3rd party blocks I was asking mainly to know if we should include them in the list of editable style variations or not (it's pretty easy to exclude them entirely, or I guess we could show them but make them uneditable)

If they have to be attached to classnames, can the CSS for these classes be dynamic so it isn't baked into each block style.scss files?

Sure, any CSS we generate will be treated exactly like the global styles customisations for specific blocks, which get added dynamically to the DOM.

[jasmussen]

Am I missing any other reasons why we shouldn't override classic style variations?

Perhaps the specificity necessary would cause headaches? Might not be a problem in practice.

Am I missing any other reasons why we shouldn't override classic style variations?

I'd think whichever is easiest for the first version, then I'm sure we'll know more. Though if we did exclude them, I'd show them as ineditable, just so people won't be confused why they're missing.

Sure, any CSS we generate will be treated exactly like the global styles customisations for specific blocks, which get added dynamically to the DOM.

👌

[tellthemachines]

I've got an initial PR that allows for editing existing style variations in #46343, if folks would like to test! It doesn't implement the UI from the designs above yet - I'm still looking at how best to do that.

Do we have any existing components for the + button that adds a new variation? What does it look like when we click the +? Mainly I'm wondering whether we get an input to name the new variation straightaway, or jump right into editing.

[jameskoster]

I would expect to see a modal asking the user to input a name, similar to when you create a new custom template.