Use Global Styles or theme.json to style individual blocks

[fklein-lu]

What problem does this address?

There's no secret that theme developers have been frustrated with the ability to style blocks.

There are a number of issues here:

1. Block classes are inconsistent. Not only between blocks, but also between the frontend and the backend.
2. Block markup changes. The most recent example would be the Group block removing the inner container.
3. Block styles can be hard to override. Again this is an issue for the frontend and the backend.

Full-site editing introduces the theme.json file, which is intended to fix all of these issues. Because theme developers use Global Styles to express how they want a block to be styled. And WordPress takes care of translating these instructions to CSS.

This is a win-win situation: WordPress can evolve its blocks without needing to keep existing markup. And theme developers can be sure that their themes don't break when WordPress upgrades.

But this is not without drawbacks. It's common for block styles to be so specific that they overload styles provided by theme.json. It's also not easy to debug, as the default block styles are still loaded, and then overloaded by the Global Styles of the theme.

What is your proposed solution?

Blocks should use the same styling mechanism as themes do. And that is Global Styles.

Because every attribute under the styles key could be used for blocks as well. There's no reason for example why a block would need to use CSS for margins, if Global Styles could be used.

The benefits are two-fold:

1. This would be a great dogfooding exercise for block authors. Because if they can't style their blocks the way they want it using Global Styles, how are theme developers supposed to do it?
2. This would get rid of unnecessary CSS being enqueued. WordPress would take the default styles, merge in the theme styles, and then output that final result.
3. This is a cleaner API, and more future proof. If themes move towards theme.json, then blocks as the building pieces of themes need to do the same. This would also prevent future bugs between default styles and theme styles, as both are handled through the same mechanism.

[getdave]

@nosolosw might be able to provide some insight here.

[oandregal]

If I get this right, the essential question here is: why don't we move all the CSS we can from the block-library package (core blocks) to core's theme.json?

I think this is worth exploring. I actually had a draft PR for a block at some point. We need to be aware it doesn't solve everything (third-party blocks's CSS can't be moved to the core's theme.json) and that the block-library package needs to work in a standalone (meaning that it doesn't have "global styles" as a dependency). So, this is best-explored case by case.

As a matter of fact, I've started to investigate easy wins in this area a few days ago #33924 Perhaps it serves to highlight the challenges.

[fklein-lu]

My thinking covered both Core and third party blocks.

The JSON file with the styles would be placed inside of the block's directory, the same as block.json. This way every block is shipped with it's own styles.

Of course this would mean adding code to handle parsing of this new JSON file. I consider that splitting up the styles per block not only makes this work for all blocks (not just Core's) but it also is conceptually better than using a theme.json file.
Only themes should use that file, as it's very much built for purpose.

Blocks can use the same schema as the style section in theme.json. Of course one could also consider adding a style section to block.json.

The possibilities are plenty, but the outcome should be the same: no CSS usage when it can be done with Global Styles.

[oandregal]

Adding more thoughts to the issue of overriding block styles: by using a system that's easily overridable by the theme, we could ship the opinionated block styles by default and get rid of wp-block-styles block support, which is all or nothing (doesn't allow per-block opt-in).

[oandregal]

JFYI @jasmussen @youknowriad

[youknowriad]

I think using block.json to style a block sounds like a good idea to me: instead of linking to a CSS file, allow using a theme.json like config.

I don't think it should cover all block styles though, there's a lot of things we don't want to allow in theme.json styles.

[fklein-lu]

[...] we could ship the opinionated block styles by default and get rid of wp-block-styles block support, which is all or nothing (doesn't allow per-block opt-in).

I consider that this is both outside of the scope of this ticket, and not a good idea.

First of all WordPress' dedication to backwards compatibility means that a feauture that is opt-in cannot be changed to opt-out (or override as in this case). This is because such a change would break existing theme styles on upgrade.

Second what I do see here as the end goal, and correct me if I'm wrong, is that theme developers build beautiful themes. A great looking design is by its nature opinionated. And one opinion (that of the theme designer) and another opinion (that of the Gutenberg block designers) don't mix. And theme developers shouldn't have to unset styles which they don't want.

As an example I find the styles for the blockquote quite questionable. And that is fine, because that's my opinion of the design. And it's worth as much as the opinion of whoever implemented these styles. So as that opinion doesn't count more than mine, it shouldn't be forced onto me, requiring me to painstakingly undo all the stuff I don't want.

[jasmussen]

To echo Riad, styles in block.json make a lot of sense: most of the existing styles were created in that early space between themes an block themes where some blocks needed some visual indication of their behavior in absence of editor styles that didn't yet exist. Since then and especially with block themes, more and more of those styles have been refactored away in favor of editor styles, global styles and even browser fallback styles (if you don't provide a font, you get Times New Roman).

"As much as we can" is worth emphasizing, as for some CSS properties the feature likely won't be worth surfacing as a design tool.

[oandregal]

I've prepared a prototype for this at #34180 Would welcome feedback on direction before committing to do anything else.

[oandregal]

@fklein-lu WordPress 6.1 has landed an experimental API for this. We need to iterate on it, so I think we can close this high-level strategic issue and follow the work on the more tactical one at #45198