Section Styling, Colorways, and Typesets for WP 6.6

[aaronrobertshaw]

Goal

To bring together the related and overlapping explorations around section styling, colorways, and typesets.

While each separate concept might not be fully realised by currently open PRs, the hope is that this issue can help define what should be delivered for 6.6.

History & Context

Section Styles

Related Issues

• Section Specific Theme.json
  • The original issue is still relevant as the explorations to date on this either have been closed or do not fully implement theme.json for block instances.
• Element Color Sets
  • The main pain point for users this issue aimed to solve was needing to repeat the same configuration of colors across multiple individual block instances when those color choices to differ to the main global styles for the block type.
• Extending Block Style Variations
  • The current approach, more on this below.

Explorations:

• Section specific theme.json within block attributes
  • This was shelved as it doesn't facilitate sharing and reusing the section specific styling across other block instances. The idea was to move the section styles to Global Styles.
• Section specific styles within Global Styles / Theme.json
  • This exploration introduced a new sections property to theme.json and attempted to allow some level of fallback between section styles when swapping themes or theme style variations.
  • This approach had several issues and a consensus was reached to abandon it in favour of leveraging block style variations as a mechanism to achieve section styling.
• Extending Block Style Variations
  • The first approach proposed in this issue but superseded by Block Styles: Extend block style variations as mechanism for achieving section styling #57908
  • With this PR, block style variations can now style elements as well as inner block types (and their elements too)
  • It's also an initial step towards allowing block style variations to be registered across multiple block types
  • Follow-ups already in the works include:
    • updating the block style variations UI
    • updating the theme.json API to allow referencing variation definitions rather than having to redefine them in theme.json if not using guteneberg_register_block_style with a style object
• Using v2 CustomSelectControl to update block style variations UI
  • This new component isn't ready for use so an alternate approach using a dropdown has been created
• Abandoned: Theme.json: Extend block style variations support #56540

Colorways and Typesets

Related Issues

• Element Color Sets
  • As noted within the Section Styling section above, this issue in part aimed to alleviate the need for users to reconfigure the same colors or typography settings across different blocks
  • Another aspect of this issue was to allow some composability between color and typography styles making it easier and quicker for new sites to settle on a look that was right for them.
• A Mechanism for Applying Colorways and Typesets
  • At the theme level within Global Styles, this has been explored via #56622. It's worth noting here that this exploration focuses only on the root Global Styles level and not block instances or "sections".
  • Some early explorations into implementing colorways and typesets for block instances didn't progress to the stage of a draft PR as it became clear that the primary user need here was already mostly solved via the proposed extended block style variations.
  • Halting explorations on colorways and typesets on block instances, still leaves the gap where theme.json (settings and styles) aren't fully implemented on individual blocks or "sections".
• Typography for elements in block instances or "sections"
  • Recently, the available elements that could have their colors configured within block instances were expanded to include buttons and headings. This was intended as a first step only with potential follow-ups including allowing typographic styles for such elements within block instances.

Original Proposed Plan

For WordPress 6.5, this proposal suggests pushing forward on two fronts.

1. Extending block style variations
2. Implementing colorways and typesets at the theme level in Global Styles

Through extended block style variations, theme authors will be able to more effectively style sections of pages and templates that differ from that block's global styles without having to repeat the same configurations over and over e.g. styling darker sections on a page. This will include the ability to style elements and inner block types within the block style variation.

That feature's functionality then essentially solves the main user need for colorways and typesets on individual block instances or "sections".

The composability of colorways and typesets holds the most value at the theme or "root" level of Global Styles, as in addition to unlocking a wide array of possibilities, it will assist users in more quickly achieving an overall look and feel for their site that they are pleased with.

The benefit in composable colorways and typesets on individual blocks or sections may not warrant the increased complexity and additional work required from a UI perspective. Especially given move powerful block style variations meet the same need.

This isn't 100% set in stone, so please feel free to highlight issues or ask questions on this issue.

Proposed Plan

Note: This plan has been revised to the outline below. For posterity the original plan can be read under the History and Context section above.

For WordPress 6.5 the plan is to:

1. Land a broad reduction in the specificity of global styles
2. Have that reduction of specificity broadly tested across blocks and themes through the 6.5 beta period
3. Implement colorways and typesets at the theme level in Global Styles
4. Delay landing extended block style variations until early in the 6.6 release schedule

The thinking behind delaying the extended block style variations until post-6.5 includes:

• The feature needs more time to be refined
• There are a lot of edge cases so multiple rounds of testing would be beneficial
• More time is needed to ensure the right approach is settled on, and what that is, may depend on feedback received around the broad reduction of style specificity

Why block style variations and section styling?

Through extended block style variations, theme authors will be able to more effectively style sections of pages and templates that differ from that block's global styles without having to repeat the same configurations over and over e.g. styling darker sections on a page. This will include the ability to style elements and inner block types within the block style variation.

That feature's functionality then essentially solves the main user need for colorways and typesets on individual block instances or "sections".

The composability of colorways and typesets holds the most value at the theme or "root" level of Global Styles, as in addition to unlocking a wide array of possibilities, it will assist users in more quickly achieving an overall look and feel for their site that they are pleased with.

The benefit in composable colorways and typesets on individual blocks or sections may not warrant the increased complexity and additional work required from a UI perspective. Especially given move powerful block style variations meet the same need.

This isn't 100% set in stone, so please feel free to highlight issues or ask questions on this issue.

Tasks

Block Style Variations

• Extend block style variations to support elements, block styles, registration across multiple types and with option style objects (@aaronrobertshaw)
• Reduce global block style specificity (@tellthemachines)
• Block Styles: Make block style variations control scale for increased number of variations #57780
• Support shared block style variation definitions
• Update documentation e.g. architecture style generation docs

Global Styles: Colorways & Typesets

• Collect colorways and typesets from theme style variations and allow the independent application of them within Global Styles (PR @scruffian)

cc/ @SaxonF, @mtias, @annezazu, @talldan

[annezazu]

Thank you for this! Updating the Roadmap to 6.5 post to link to this issue.

[aaronrobertshaw]

A potential blocker has been encountered for the extended block style variations. A detailed breakdown of the issue can be found on the PR.

[aaronrobertshaw]

Update 11 Jan 2024

After much testing, discussion, and exploration, a consensus has been reached regarding the potential blocker noted above. Element styles on individual block instances will have their specificity increased to ensure the user's selection is honoured and these choices override the values from block style variations.

Additionally, it appears as though the v2 CustomSelectControl is not ready for use in the editor yet. The extended block style variations feature is not dependent upon any UI updates. Their goal is to allow the UI to scale as the number of available block style variations do. For the time being, this is not likely to be a big issue and could land post 6.5 if needed.

If time permits, a button and popover combination to achieve a similar UI to earlier mockups of colorways, could be explored.

[aaronrobertshaw]

Additionally, it appears as though the v2 CustomSelectControl is not ready for use in the editor yet.

I've pulled an alternative approach to updating the UI using a simple Dropdown from some earlier colorway explorations into a draft PR (#57780). If it's decided that a UI update is required, this might provide a path forward.

[aaronrobertshaw]

Summary of Explorations and the Current Approach

Block Style Variation Registration:

A new global function has been added: gutenberg_register_block_style.

The WP_Block_Styles_Registry class is marked final in core, so this function was added to allow block style variations to be registered across multiple block types. It also accepts a style object in place of a stylesheet or handle.

The WP_Theme_JSON_Resolver_Gutenberg class absorbs any style objects into the theme's data as if the variation was defined there.

Alternatively, a block style variation can be registered without any style data. It can then have its styles defined within theme.json e.g. styles.blocks.<block-type>.variations.<name>.

Theme.json / Style Objects:

Block style variations will support styles for inner elements and block types. For example:

{
	"styles": {
		"blocks": {
			"core/group": {
				"variations": {
					"dark": {
						"elements": { ... },
						"blocks": { ... },
					}
				}
			}
		}
	}
}

Elements specific to a variation's inner block types will not be supported due to this excessively increasing specificity of styles.

To avoid having to define a variation's styles within theme.json repeatedly, there is a secondary PR proposing to allow referencing a shared block style variation definition.

References in theme.json so far only support referencing a single property value, not an object. To avoid having to merge the referenced values with anything customized by the user throughout the code, the secondary PR above is in the process of being updated so the theme.json resolver will resolve the referenced block style variations into the theme.json data.

The initial proposal for a home for referenced block style variations is: styles.blocks.variations. Each variation within that could also define an array of block names for which it is available to.

Global Styles:

The aim of #56540 is for block style variation styles to be generated as per normal but with the addition of styles for their inner element and block type styles.

This approach currently has two main issues;

1. CSS specificity
2. Nesting the application of block style variations

CSS Specificity

The more nested styles we generate, i.e. element and block type styles for variations, the greater those styles' specificity. Currently, this results in a CSS specificity for elements of 0-2-1 e.g. .wp-block-group.is-style-dark a.

This is a problem because styles for elements configured explicitly by the user on a block instance only have a specificity of 0-1-1, e.g. .wp-elements-123 a, and the block style variation element styles would incorrectly take precedence.

A lot of exploration went into trying to reduce the block style variation specificity however reducing them too far would mean they wouldn't override global block styles.

The current trade-off in #56540 is to bump the specificity of the block instance element styles while further exploration into reducing all global block styles to zero specificity is carried out.

Nested Block Style Variations

This one is more of a problem in terms of user experience. It is a valid use case that a user would like to apply a variation to a block already within another block with a variation applied.

It might be the user wants a dark section across the page but to assign light styles to cards within that section.

With the simple generation of styles for block style variations in #56540, they are defined once for each block type. This means all such styles will have the same specificity.

When it then comes to block style variations on a block inside another, its inner blocks and elements would match both selectors and so the last to be defined in the stylesheet would take precedence, perhaps incorrectly.

The generated styles cannot be reordered reliably so this issue might be unavoidable for the approach in #56540.

While arguments can be made as to how likely the use case of nested variations is to occur, it would be a broken experience for a user attempting to assign a block style variation and not seeing the desired changes.

If we were to omit the block styles control in the UI, when the currently selected block has an ancestor with a variation, it could be confusing to see the control on some blocks and not others despite them being of the same type. This also wouldn't stop a user from dragging a block with a variation into a container block that already has one.

An Alternative

There are some early explorations into an alternative approach (#57908).

This alternative proposes to:

• Continue using block style variations as a mechanism for defining section styles
  • This includes current methods of registration and the ability to reference a shared variation within theme.json
• Instead of generating generic styles for all block style variations in the global styles stylesheet, they will be omitted there
• Apply a unique class name to blocks that have a variation applied to them
• Generate a partial stylesheet for the block style variation scoped using the unique class name applied to the block
  • This means the order the styles are defined is controlled and in the correct order for the cascade to work correctly.
  • This has the downside side of potentially more CSS being generated if lots of variations are used but also less if no block style variations get applied to blocks.

While this approach may not be perfect either. It does look promising towards solving the issue with the nested application of block style variations.

For it to work though, it would depend on the across-the-board reduction of block style specificity in #57841 .

Note: The early exploration is just that, early, and not fully functional or tested. So there is potential for more unexpected edge cases.

UI

As this feature will hopefully increase the value and use of block style variations, their number is expected to also increase. The current UI of a button per style isn't very scalable and might need some tweaking.

Early mockups here included using a custom select control. At the current time, CustomSelectControl cannot render the desired color swatches and the new second version for that component isn't quite ready. The new version would do the job, however.

As an interim measure, there's a further PR implementing a similar UI using a Dropdown component instead, #57780.

The Path Forward

With the current issues facing #56540 and limited time before the 6.5 beta & release, it is worth considering if it is possible to get this feature to a suitable state to land.

Reducing the scope of these extended block style variations would likely mean not supporting inner element and block type styles for them. This severely limits the value of the feature, if that were to land as an MVP.

This leads to three primary questions:

1. Is a bump in specificity for user generated element styles on a block instance okay?
2. How can the inability to apply nested block style variations be mitigated if it is deemed to be unsupported?
3. Is it worth pulling the feature from 6.5 so that the approach can be refined and new solutions worked towards?

---

cc/ @youknowriad, @SaxonF, @richtabor, @tellthemachines, @andrewserong, @talldan

Apologies for the mass ping but I'd love to get your thoughts and feedback so we can settle on a decision and plan to move forward sooner rather than later 🙏

[youknowriad]

Is a bump in specificity for user generated element styles on a block instance okay?

I think that's probably a breaking change on its own, did we try how this impact existing plugins and themes trying to override these styles? Not saying it's a not go but wondering about impact.

Is it worth pulling the feature from 6.5 so that the approach can be refined and new solutions worked towards?

IMO, if we think we need more time to work on this properly, it's definitely on the table to pull this out of 6.5. It's IMO important to not ship something here that we're not satisfied about and that has the potential to harm us in the future.

---

Can we have a summary of the existing style generation use-cases we have in some kind of table to help us think about these specificity issues. (Maybe add this to the architecture docs). Something like:

style	selector
global style	body
block type style	.wp-my-block
global element	.my-element
element within block type	.wp-my-block .my-element
block instance style (layout)	.someinstanceid
block instance element style	.someinstanceid .my-element
block style variation regular style	.wp-my-block.is-style
element within block style variation	.wp-my-block.is-style .my-element
block type within block style variation	.wp-my-block.is-style .wp-other-block
element within block type within block style variation	.wp-my-block.is-style .wp-other-block .my-element

I guess there's also "global style variations" we may want to introduce in this table.

We could compute the specificity and order them properly. I'm hoping this could give us better hints about what we want and just align us better.

[aaronrobertshaw]

I think that's probably a breaking change on its own,

Agreed.

Initially, I was under the impression this would be a blocker to extending block style variations to cover inner elements as well. My position softened on it after lengthy conversations with @tellthemachines, @andrewserong, and @SaxonF.

The general thinking resulting from those discussions was that these are styles generated by a user decision to explicitly override styles within a block instance. To that end, increasing the specificity, while a change, wouldn't really change the intended functionality.

did we try how this impact existing plugins and themes trying to override these styles? Not saying it's a not go but wondering about impact.

The majority of the focus has been trying to find an approach to avoid the need to bump it at all, via #57841 & #57908.

Some initial searches of plugins and themes didn't return too many hits for explicit strings like .wp-elements-. Performing a much broader search for any say, links within a .wp- class, returns too many hits to comb through with a high certainty.

I did trawl through the themes on the first page of results. Mostly, the top themes in that last search fell into the following scenarios:

• The style was already overridden by the current specificity of block instance element styles, primarily due to elements styles being enqueued later.
• The style was already more specific than the proposed bump in element styles results in.
• The theme or block related to the style didn't support user selected element colors
• Link style targets a non-block element

In that initial page of results, the majority of styles also did not set colors which is all the per block instance element styles support at the moment.

None of these findings are very robust of course and we really need broad testing. Hopefully, they do provide something more to go on in terms of estimating the severity and impact of increased specificity here.

---

Can we have a summary of the existing style generation use-cases we have in some kind of table to help us think about these specificity issues. (Maybe add this to the architecture docs). Something like:

💯 This would definitely be beneficial as we continue to evolve these sorts of features.

I guess there's also "global style variations" we may want to introduce in this table.

I'd see this table as scoped by a global style variation, if we're talking about theme style variations.

We could compute the specificity and order them properly. I'm hoping this could give us better hints about what we want and just align us better.

I like the idea. I think doing so reliably is the catch.

In general, the table looks good for most cases. There are some things that may throw it out of whack though.

• Global Style: This should be configurable by the root_selector option passed through to get_stylesheet however there's currently a small bug in the code. I'll put up an independent fix for that soon.
• Elements: Generally these are just a simple element but buttons and captions use more complex selectors. This doesn't really impact instance element styles though as the same element selectors are used there also.
• Blocks: All block selectors can be configured via the Block Selectors API and the old __experimentalSelector block.json property.
  • While a single class does cover most blocks, it isn't all of them e.g. Table
  • This creates a problem given block instance element styles only use a single class regardless of what complex selector a block itself might actually use
  • This is an existing problem for some edge cases now
  • If we add the block selectors to the class generated for block instance element styles, we're increasing the specificity as well
• Features: There's also the possibility that blocks configure certain feature styles (typography, border etc) to apply to inner markup.
  • One example could be, a block specifying for text decoration to be applied to an inner element so the browser doesn't paint it over all elements in the block's markup.
  • The extended block style variations also take the block's feature selectors into account when generating styles
  • For the vast majority of use cases, this isn't required for applying color styles and might be a smaller issue given block instance element styles only support applying colors at present

The block style variation class, .is-style, is currently prepended to the block's selector. That also means it will break if used on a block with a simple element as its selector, e.g. the paragraph block which uses p. This is a minor edge case we can address separately.

---

It's IMO important to not ship something here that we're not satisfied about and that has the potential to harm us in the future.

👍 This is my sentiment also.

At this stage, I'd be more confident in giving the feature additional time to bake but want to make sure I'm not being too conservative.

We do have a little time left, if we can achieve clarity on exactly what needs to be changed and what we're happy with delivering as an MVP.

I'm personally finding this a little murky at the moment, especially given the viability of some solutions being dependent on ongoing explorations (#57841).

Perhaps for 6.5 we could:

• Aim to land just the broader reduction of block style specificity calling it out for greater focus during beta testing
• Delay extending block style variations until after the release giving it a full release cycle within Gutenberg to be refined
• Also, deliver Add color and typography presets to Global Styles #56622 to provide some enhancements towards site building

That being said, I'm not 100% ready to give up on the feature for this release yet 🤞

P.S. Apologies for the essay length reply 😅

[youknowriad]

Aim to land just the #57841 calling it out for greater focus during beta testing
Delay extending block style variations until after the release giving it a full release cycle within Gutenberg to be refined
Also, deliver #56622 to provide some enhancements towards site building

You're the lead here. I think that plan makes sense to me. It's all about confidence. For the first item in the list, if the plan is to switch to "increase specificity of user generated element styles", is #57841 still needed?

[gaambo]

Just a minor thing I want to add:
I think the language regarding "styles", "style variations", "(block) variations" in the block editor is suboptimal and can be confusing for developers (and users). Seeing the examples here use a styles key in which a variations key is nested, seems to make this more complicated. Also "block styles" can mean a registered block style (which adds is-style- class to a block) but also registering a stylesheet/inline CSS for a block (see register_block_style).
This is no objection to any of the discussed points about the feature. Just want to point out, that searching in the documentation or on the web, it's sometimes pretty difficult and confusing, when "variations" is used in multiple places but has different meanings. So maybe this can be anticipated and clearer naming be used.

[aaronrobertshaw]

For the first item in the list, if the plan is to switch to "increase specificity of user generated element styles", is #57841 still needed

If we went with the original approach (#56540), then #57841 wouldn't be a requirement.

With the original approach, a user can't reliably apply a variation to a block within another variation. This is appearing to be a very desired use case and a blocker to that approach.

It's looking like we'll need to pursue the alternate approach instead (#57908).

[aaronrobertshaw]

Thank you very much for the feedback @gaambo, it's greatly appreciated 👍

I think the language regarding "styles", "style variations", "(block) variations" in the block editor is suboptimal and can be confusing for developers (and users).

Agreed. I've had to be very explicit to try and avoid some confusion here but in doing so the discussion becomes verbose and harder to read in my opinion.

Also "block styles" can mean a registered block style (which adds is-style- class to a block) but also registering a stylesheet/inline CSS for a block (see register_block_style).

Correct. These should still be supported but the intent here is to open up theme.json as a means for defining some of these and giving users a bit more control over tweaking them.

Just want to point out, that searching in the documentation or on the web, it's sometimes pretty difficult and confusing, when "variations" is used in multiple places but has different meanings.

100% agree!

So maybe this can be anticipated and clearer naming be used.

As a lot of these terms are already out in the wild as you noted, I think it needs a concerted effort to rename/rebrand them all. Along with some clear communication to the community around that. Something similar to how reusable blocks were renamed to patterns.

Unfortunately, that might need to be something we look at for beyond WP 6.5.

[aaronrobertshaw]

I've updated the plan in the issue description as follows:

For WordPress 6.5 the plan is to:

• Try reducing specificity of global styles block selector. #57841
• Have that reduction of specificity broadly tested across blocks and themes through the 6.5 beta period
• Add color and typography presets to Global Styles #56622
• Delay landing extended block style variations until early in the 6.6 release schedule

The thinking behind delaying the extended block style variations until post-6.5 includes:

• The feature needs more time to be refined
• There are a lot of edge cases so multiple rounds of testing would be beneficial
• More time is needed to ensure the right approach is settled on, and what that is, may depend on feedback received around the broad reduction of style specificity

The PRs related to this issue are in the process of being updated or closed as appropriate. Once that is complete, I'll provide another update with all the relevant links.

[aaronrobertshaw]

Quick Update:

Work is still ongoing over in #57908 however it is now pretty functional and is looking somewhat promising 🤞.

The effort to reduce overall block style specificity is also progressing. It has required some rejigging of the order in which styles are loaded and this has just been merged to core (WordPress/wordpress-develop#6010). The equivalent for Gutenberg is now up in #58761.

The changes to the style loading order will be all that makes 6.5 as the reduction of specificity is only really required to unlock the block style variations work. Delaying the reduction of specificity until post 6.5 will allow more time for testing given the edge cases popping up around opinionated block styles.

[aaronrobertshaw]

With enhanced block style variations being delayed until 6.6, it should be possible to update the related UI using the new v2 CustomSelect components instead of having to take the interim step of using a Dropdown.

Given this, I've updated #57780 accordingly.

[mtias]

I believe the latest design uses the variation card but just with the color dots.

[aaronrobertshaw]

Thanks for flagging that @mtias as I was going off the only mockup I had 👍

I still have some questions around the UI that I've left as a comment over on the UI PR. Block style variations cover more than just colors, so I'd like to make sure I understand how all possible styling options are covered in terms of the control's UI, where it's located etc.

[aaronrobertshaw]

Quick Update (March 13th):

Together with @richtabor, I've taken a bit of a look at how the current approach to extending block style variations might be impacted by other work related to colorways and typesets.

The conclusion reached was that colorways and typesets would not (at least in the short to medium term) be composable at the individual block instance level. Doing so introduces a range of issues including:

• Requiring the ability to apply multiple variations at once
• Managing the resulting conflicts or ordering issues due to needing to continue supporting pre-existing block style variations that might span color, typography, and all other styles
• Adding complexity to the UX / UI when accounting for broad block styles alongside color/typography specific variations
• Inability to reliably compose block styles registered with a stylesheet vs those with a theme.json partial/style object

The alternative is to in future iterations allow for composing colorways and typesets into new block style variations at the Block Type level within Global Styles. From there, those composed block style variations can be applied to an individual block instance as per any other.

As part of this, the proposed UI updates will be put on hold and given further thought. The potential for block style variations to cover more than color styles means for some, the introduction of a color card doesn't make a lot of sense, e.g. button's outline or image's rounded block styles.

The next steps towards landing this feature involve helping test and push forward the broad reduction of block style specificity in #57841. (Note: #57841 will be split into smaller PRs for easier review in the near future)

Once that reduction of specificity is in place, the plan is to merge the current approach to extended block style variations in #57908.

cc/ @SaxonF

[aaronrobertshaw]

Quick Update (April 10th):

The main PR (#57908) has been brought up to date and made compatible with some recent changes on trunk. It has also been taken out of draft status and is ready for broader feedback and review.

The hope is this initial iteration might be able to land in time for the Gutenberg 18.2 release 🤞

[aaronrobertshaw]

Quick Update (April 23rd):

#57908 is still progressing after receiving some broader attention recently.

Lots of feedback and a few bugs have been addressed. The delay at the moment is trying to optimize the feature a little and ensure satisfactory performance before getting final approval to merge.

Depending on how this goes, it might impact whether the feature lands for 18.2 as previously hoped for.

[aaronrobertshaw]

Now the functionality of #57908 has stabilized somewhat, the plan is to chop up that PR into several smaller ones where each subset of changes can be evaluated for performance and refined if necessary before landing.

This means section styling will not land for 18.2.