Add a high-level intro to styles in the block editor

[oandregal]

This PR adds a new document to the handbook: a high-level intro to how styles work in the block editor.

It points to the relevant reference guides and tutorials for readers to dig deeper into each one of the ideas presented. It's aimed to block authors and people working in the block editor project. It intentionally tries to avoid block editor jargon and it doesn't presume any knowledge by the reader, other than a familiarity with the block editor and what a block is.

It needs to be complemented with a couple of new tutorials, to be done in separate PRs. Namely, one that explains how to use block supports, both for static and dynamic blocks. Related #38210

Feedback

Read the doc here.

At the moment, I'm particularly interested in hearing what people think of the general structure and the block styles section. Does this work as a general intro? Anything people find missing? I expect further explanations and code deep downs to be developed in the tutorials.

TODO

• Set it up as a new page in the handbook.
• Contents for user-provided global styles
• Note about the link between skip serialization and global styles Add a high-level intro to styles in the block editor #38208 (comment)

Follow-up PRs (up for grabs):

• Find a place for some implementation utils (functions to get styles from attributes in "skip serialization" mode) see comment.
• Find a place for documenting how "Editor Styles" work and how the theme-provided styles get loaded in the editor. Also: classic.css and reset.css. See comment.

[ivan-ottinger]

Thank you for working on the new docs. I appreciate it.

While I cannot officially review this PR (as I don't have the rights to do that), here are a couple of things that came to my mind while reading the proposed text:

• I like the structure; from a perspective of someone who is just getting into styling blocks, the sections sharing details on Supports API are quite helpful
• I wonder if it would make sense to add some info on how to approach working with older blocks that don't have block.json available;
• There are a couple of functions in Gutenberg, e.g. __experimentalGetSpacingClassesAndStyles() that can be helpful when we build custom blocks, but it is not clear if this API is going to stay or not

A couple of tiny typos (in an improvised suggestion markdown :) )

was → were:

- Since the introduction of the block editor in WordPress 5.0, there was tools for the users to "add styles" to specific blocks.
+ Since the introduction of the block editor in WordPress 5.0, there were tools for the users to "add styles" to specific blocks.

Extra the:

- The linked proposal is exploring a different way to serialize the user changes: instead of each block support serializing its own data (for example, classes such as has-small-font-size, has-green-color) the idea is the the block would get a single class instead (for example, wp-style-UUID) and the contents of that class will be generated in the server by WordPress.
+ The linked proposal is exploring a different way to serialize the user changes: instead of each block support serializing its own data (for example, classes such as has-small-font-size, has-green-color) the idea is the block would get a single class instead (for example, wp-style-UUID) and the contents of that class will be generated in the server by WordPress.

And again, thanks so much!

[oandregal]

Sharing feedback I've got privately:

1. Some folks shared interest in going deep down into how this works: the filters in use, pointing directly to the code where this happens, etc.
2. Point to the existence of some functions useful in "skip serialization" mode (__experimentalUseColorProps, __experimentalUseBorderProps, __experimentalGetSpacingClassesAndStyles, etc).

I'll incorporate something for the second point directly in this PR.

As for the 1st point. My first instinct was to keep this doc as approachable as possible to block authors, so they don't feel that they need to know how the internals of this API work to implement their blocks. That shouldn't be a requirement. I also understand how that would be useful for core contributors. I'd like to hear thoughts on this, especially from other folks new to this area or that have interacted with this lately.

[youknowriad]

I felt that the "styles" document might not be the right place to expand on how block supports work. Would it be better if in this document block supports are treated just like any "local/serializable" style and just link to their document for block authors that want to know more about them?

[youknowriad]

I read the content here for block supports and it does make a lot of sense and have value but maybe it's better moved to the block supports document itself.

[ramonjd]

Would it be better if in this document block supports are treated just like any "local/serializable" style and just link to their document for block authors that want to know more about them?

This sounds like a good idea. Block supports are still in development, so the docs might need a roomy home.

It's probably still relevant to this doc to emphasise that many block supports add inline styles to block containers, and that they're rendered to the page with the block.

[oandregal]

I won't add any further to "how block supports" work and the utility functions in use. This can be done in a different PR and probably can go in the block supports docs.

[youknowriad]

I felt that the "styles" document might not be the right place to expand on how block supports work. Would it be better if in this document block supports are treated just like any "local/serializable" style and just link to their document for block authors that want to know more about them?

[youknowriad]

I read the content here for block supports and it does make a lot of sense and have value but maybe it's better moved to the block supports document itself.

[youknowriad]

Do we need a chapter about "Editor Styles" and how all these theme provided styles get loaded in the editor as well? (in addition to classic.css and reset.css) or is this specifically about frontend?

[oandregal]

I see this doc as a "map to the main subsystems" someone needs to be aware of, so not about the frontend. I've added a todo task in the issue description to consider this once the global styles section has a draft.

[oandregal]

Upon re-reading the whole document, I think the v1 doesn't need to cover this.

"How styles are enqueued into the editor" is a whole new topic that needs to cover a lot of ground by itself: add_editor_style(...), add_theme_support('editor-styles'), add_theme_support('wp-block-styles'), reset.css/classic.css, the iframe, add_filter( 'enqueue_block_editor_assets', ...` and probably some other things I've forgotten. Some of this is already mentioned on theme support.

[andrewserong]

Thanks for putting this together @oandregal! This reads really well to me, and nicely covers some of the main areas we're hoping to address with the style engine. Thanks for linking through to the relevant issues, too (and nicely articulating the issue of complex blocks like the Table block 🙇).

I hope you don't mind, but I've added a few suggestions, mostly for copy-editing things (typos and grammar), but otherwise it's looking really good to me! (There's a few instances of an before UI that I've switched to a — usually if the vowel sounds like a y when read aloud, it should be a).

Since it's documentation, I'd be in favour of seeing what we can get in in the shorter-term and follow up with additions as we need to in follow-up PRs. Also CC: @aaronrobertshaw and @ramonjd for visibility since they've been looking at block supports and style engine things quite a bit recently, too 🙂

[ramonjd]

This is a fantastic start, thanks for taking the time to document your knowledge on this.

[aaronrobertshaw]

Thank you very much for working on this @oandregal, it is greatly appreciated 👍

I think @andrewserong has covered most of the wording related tweaks that could improve things. So I'll limit my comments below to a couple of clarifications that might help avoid some points of confusion I've seen pop up regularly around the block supports API.

Lastly, the level of knowledge this is being aimed at is great. I think it will be tremendously useful for those starting to look closer in this area. Well done!

[oandregal]

Pushed a draft for the global styles section so we have a first v1 for this document. Would welcome reviews for this new section.

[aaronrobertshaw]

The new section on Global Styles reads well to me 👍

I've left some minor comments and suggestions regarding fixing small typos or tiny improvements to wording.

Thanks again for writing this up. I'm sure it will help lots of people.

[oandregal]

Feedback has been incorporated and this is now ready for landing.

[ntsekouras]

This is great @oandregal! Thanks for working on this!

I've left minor comments and I'm going to pre approve because I think we can land and iterate more if needed. My only small concern is whether the block supports section really belongs here.

[ntsekouras]

Since we're talking about final, it feels to me okay not to mention transforming.

[youknowriad]

I think that's a great addition.

[oandregal]

These are things that are not covered by this PR but folks mentioned that could be useful to have in some place:

• Find a place for some implementation utils (functions to get styles from attributes in "skip serialization" mode) (see).
• Find a place for documenting how "Editor Styles" work and how the theme-provided styles get loaded in the editor. Also: classic.css and reset.css. See.

I don't plan to work on them at the moment, but wanted to give them visibility in case anyone has the bandwidth/interest.

[gziolo]

Excellent work, this is going to be super helpful for both contributors and extenders ❤️

[andrewserong]

Great work @oandregal, thanks again for adding in the extra documentation, +1 to the above comment, it's going to be really helpful for folks 😀