Iterate on absorbing block styles as part of the global styles mechanism

[oandregal]

Follow-up to #33977
Part of #45171, #41232, and #41236.

What

Finalize the work that was started at #34180 to absorb block's CSS as part of the global styles' mechanism.

Why

By absorbing the block's CSS, WordPress will be able to reduce the CSS loaded in the page, themes and users will have a reliable (no specificity issues) and fine-grained mechanism to override styles from lower-level sources.

Note that the global styles' mechanism takes the CSS needs that different sources declare, and creates a single stylesheet that merges them all. The current sources are:

• default (WordPress bundled theme.json)
• blocks (__experimentalStyle from block.json)
• theme (the own theme's theme.json
• user (the styles provided via the global styles sidebar)

If block's CSS is not fully absorbed, the goal is not complete.

How

The current experimental implementation uses a __experimentalStyle key in the block.json of the block.

We could explore other alternatives when/if the current experiment becomes insufficient or ergonomically inconvenient. For example, it was suggested that blocks could also have a separate styles.json that could help address the style variations issues (see).

Current status

Blocks

• Button
  • Added partial support in #34180
  • Partially remove styles in #41822
  • Remove all remaining styles in #41934
• Pullquote
  • Added partial support in #43195
• Navigation
  • Added partial support in #41898
• Table
  • Added partial support in #41689
  • Removed support in #43813
• File
  • Added partial support in #41822
  • Removed support in #41931
• Audio
  • Added partial support in #41689
  • Removed support in #43813
• Embed
  • Added partial support in #41689
  • Removed support in #43813
• Image
  • Added partial support in #41689
  • Removed support in #43813
• Video
  • Added partial support in #41689
  • Removed support in #43813

Issues

• Themes without theme.json don't have these styles in the post editor Styles coming from __experimentalStyles are not enqueued in the post editor for themes without theme.json #46818
• Style variations and theme.json styles. They are different mechanisms that don't understand each other. See "block styles variations" and "style variations for blocks". As a result, the current mechanism cannot absorb the following CSS:

.wp-block-button { border-radius: 9999px; }
.wp-block-button.is-style-squared { border-radius: 0; }

[oandregal]

cc @scruffian @adamziel @ajlende @MaggieCabrera @getdave @draganescu @gziolo @matiasbenedetto @carolinan as people that were involved in some of the PRs (authors or reviewers) that implemented initial support for __experimentalStyle. We can use this issue for coordinating future work. Please, edit the issue description as you see fit.

[oandregal]

Added this bug report to the list of issues #46818

[mtias]

@oandregal it seems all these tasks are done — can we close?

[oandregal]

This is how the __experimentalStyle in block.json is used in practice: pullquote and navigation. Both blocks still provide extensive CSS separately.

Given its current state, I think we should reconsider this API and revert it. If people still find the problem worth solving (merge block styles as part of thetheme.json styles: core/block/theme/user), we could explore alternatives.

[scruffian]

If we revert we just have to make sure that global styles settings are able to take precedence over the default styles. We might also lose some performance enhancements but that's minor.

[oandregal]

If we revert we just have to make sure that global styles settings are able to take precedence over the default styles.

This is already what happens: the global styles stylesheet loads after the block's. When WordPress only loads the CSS of the block, the global styles are added as "inline styles" of the block, hence loading after as well.

We might also lose some performance enhancements but that's minor.

There are only 3 lines of CSS that could be overridden by the theme or user theme.json. TwentyTwentyThree only overrides one of them, so that's what we prevent from sending to the browser. The current API has had very low impact. If we think this is due to it not being ergonomic (writing CSS within block.json is weird), we could look into alternatives.

[scruffian]

the global styles stylesheet loads after the block's.

if the blocks CSS is more specific than Global Styles then even if it loads later it won't win.

[oandregal]

if the blocks CSS is more specific than Global Styles then even if it loads later it won't win.

👍

We still only have 3 lines of CSS that use it, though, so it is not a problem in practice. When we landed the theme.json API, the goal was to be able to represent a theme without any CSS. This API should be able to do the same for blocks.

Why is it not more widespread? How do we expand its usage? Would a different implementation help?

[scruffian]

Why is it not more widespread? How do we expand its usage? Would a different implementation help?

I think its because people have a different view of how theme.json should work.

My understanding of the reasoning for bringing rules into block.json is that it enabled us to load them conditionally - so we could only ship styles when the block was on the page. This is a good performance enhancement. However I think some people expect theme.json styles to always be on the page, so this change doesn't align with that.

[oandregal]

My understanding of the reasoning for bringing rules into block.json is that it enabled us to load them conditionally - so we could only ship styles when the block was on the page.

We already load the styles of the block conditionally (we don't need theme.json for this).

As I see it, the value proposition is more about being able to override the block styles from the upper layers (theme and user), effectively controlling specificity. For example, when a user selects a style for a block via the global styles sidebar, does it work in all cases? Or are there cases that do not work due to block styles being declared in CSS and having specificity issues?

This is a good performance enhancement. However I think some people expect theme.json styles to always be on the page, so this change doesn't align with that.

While it was already in the original plans, the issue was created by the community #33977 so I presume there is interest. The comments on the make core announcement https://make.wordpress.org/core/2022/08/01/moving-core-block-styling-to-json/ point to how the ergonomics as the source of the struggles.

Thinking of next steps: it sounds like we need to find the current use cases for which the global styles sidebar does not work due to block CSS and figure next steps from there.

[fklein-lu]

There are several issues here that this approach would solve.

The first is that the block styles shipped with WordPress 5.0 were too specific. The goal was to make blocks good, no matter what theme. This meant that developers had to fight with WordPress to get their own styles applied.

The style engine solved this issue for themes, child themes, and user customizations. Core styles are still not part of this. The fact the CSS is always written in a "good enough" approach, and to solve one particular issue doesn't help.

Second, yes there are issues with customization options not working. Try styling the navigation with theme.json, and you'll see what I mean. There are also issues like this one #33871

To top things off, the CSS in WordPress keeps changing. See https://core.trac.wordpress.org/ticket/58815 or https://twitter.com/aurooba/status/1691576607167902127 for a recent examples.

CSS breaking between versions is one of the biggest annoyances that developers have. All you do is upgrade WordPress, and suddenly CSS that used to work doesn't.

Third is that we need to get to presetting elements in the settings sidebar. If a block has a text size applied, then the text size palette should reflect this. If it has a padding preset, the same.

Now that's a longer roadmap. But the blocks in Core need to be part of that. If they continue to use CSS, then that will never be possible.

Fourth is that this API makes sense beyond Core blocks. If I do ship blocks in my plugin, I want to preset styles. But I also want these styles to be overwritten by the theme (or the user). Which is way easier for the theme and users if this is all in one system.

Finally the big one. WordPress told theme developers that they shouldn't use CSS. For very good reasons. So why should Core continue to use CSS?

The question is not why should styles be in block.json. It should be why not?

For sure the ergonomics of theme.json are an issue. There's a big lack of developer tooling in WordPress. But that shouldn't keep this from progressing, since that lack of tooling is not going to change soon.

[scruffian]

Another reason to keep these settings in block.json is that it means we can accurately represent them in the UI, as outlined here: #27796.