Reduce the specificity of block styles to simplify editor styles slightly

[jasmussen]

This PR is round 2 of #8350. The ultimate goal is to make it easier for themes to style the editor, and to do less CSS overriding in order to do so.

Problem: Currently, every single block is born with an intrinsic top and bottom margin. This margin matches the padding that sits between the block and the "selected block" border, plus 2px of space. This margin is the same regardless of whether the block needs a margin or not, and it is applied to nesting containers as well. In the case of the Columns block for example, that means the column block (singular) has top and bottom margin, even though it shouldn't have that.

Since then a number of changes have been made to the editor to make it a good time to revisit this:

• The block outlines and toolbars have been refactored to not rely on margins at all to position themselves. These will still be painted correctly outside of the block, though they may overlap content visibly if a zero margin block is selected.
• A more solid editor style system has been introduced that makes it easier to customize the editor to look like the front-end. As a result of this, feedback around CSS specificity and having to override these margins have surfaced to a higher degree.

Proposed solution: By removing the intrinsic margin, we can re-apply it only to the blocks that actually should be born with an intrinsic margin, such as paragraphs, lists, quotes ,etc.

Some discussion points that are likely to surface: where should those vanilla styles be stored? How should they be structured so that themes can easily override them? Should these not be loaded if a theme provides its own editor styles? Should we leverage the cascade and store these generically in one location or should these be applied in the style.scss file for every block in the library? Given these intrinsic margins have been present since day one, can we expect plugin authors to remember to add these margins themselves for every block they make? Is there a back-compat way we provide these default margins to blocks that rely on them?

This is a try branch, in order to figure out answers to those questions. This first commit only does a few things:

• It rearranges some CSS to put things in more logical locations.
• It removes the intrinsic margins, then blanket reapplies them in that new vanilla stylesheet location with a new CSS variable.

Next commits will explore how to remove that blanket reapplication, and try to provide those vanilla styles in a per-block basis.

This PR, depending on feedback, will likely be ready to go once the editor looks mostly the same in this branch as it does in master, regardless of the WordPress theme you're running. But with the added benefits that themers now have increased quality of life.

See also:

#13989 (comment)
https://github.com/WordPress/gutenberg/pull/8350/files

CC: @m-e-h @chrisvanpatten

[jasmussen]

When this margin is 2em, it perfectly matches the existing margin. This means no overlap between blocks when selected or hovered:

We can't totally prevent that from happening. For example a 3rd party block might add zero margin, and it'll look like this:

I.e. overlap.

Is this something we should be okay with? Technically it works fine since the multi block selection style and block boundaries are painted outside the block. But surfacing here for discussion.

[m-e-h]

This style rule will only match up with the current margins for the bottom.
Is matching up with the current margins a goal with all blocks, some blocks , or just by coincidence sometimes?

[jasmussen]

This style rule will only match up with the current margins for the bottom.
Is matching up with the current margins a goal with all blocks, some blocks , or just by coincidence sometimes?

Well it's a little more complex than that. In https://codepen.io/joen/pen/XOLamR you can see sort of a minimalistic microcosm of the current block setup. The red backgrounds represent the block footprint. The margin between the red is what those blocks themselves provide. You could have zero margin, and the text would bump against each other. Since blocks paint the selected borders outside the block footprint, this would mean those borders would overlap adjacent blocks, like this:

Inversely if you have a ton of margin, you'll just get a lot of space between blocks:

There's $block-padding variable, set to 14px if I recall. It would be nice to, separately, explore making this variable styleable by an editor style. For example if you have a layout that relies on really tight block margins but you don't want the selected block borders to overlap. But this is a challenge, and one best looked at separately I'd say.

So to answer your question, yes it's a lucky coincidence that 2em = 32px (2x16px base font), and that happens to be the same as ($block-padding * 2) + $block-spacing;

[joyously]

Is the border really a border? Perhaps it should use outline instead, so it doesn't affect the margin collapse.

[jasmussen]

Should these styles be in theme.scss, or editor.scss? Currently, theme.scss is currently loaded in the editor regardless of whether the theme has opted in, but it has the added benefit of not being output in the theme itself unless opted into.

It seems like we should either load theme.scss only into the editor if opted into, or reconsider what it means for the editor to have a "vanilla stylesheet". See later comments on that.

[getdave]

So in the case of the heading Block theme.scss exists to

1. Apply default heading styling rules within the Editor
2. Optionally (when opted into) apply heading styling in the Theme when you load front of the website.

Is that right?

[m-e-h]

I'm still unsure about outputting un-scoped element styles in a theme's front-end. Even with opt-in theme.css.

The pros:

• specificity couldn't be any less
• If the theme has this styled at all it's styles will be used
• 98% of themes will have h* font-sizes defined.

The questions:

• What if the theme has made a choice to go with the browser defaults for heading font-size or margins. Would they be happy with our modified defaults?

Essentially what we're doing here and with any naked element styles is creating our own "browser defaults".
Do we need to add our own styles here at all? The browser defaults aren't that bad.

[jasmussen]

Great thoughts, thank you.

What if the theme has made a choice to go with the browser defaults for heading font-size or margins. Would they be happy with our modified defaults?
Essentially what we're doing here and with any naked element styles is creating our own "browser defaults".
Do we need to add our own styles here at all? The browser defaults aren't that bad.

I agree, the browser defaults aren't bad!

However this is another one of those situations where if we don't provide any styles for the heading sizes, then the WordPress heading sizes will be used because we inherit them. Here's an example:

That's an unscoped h1 style that the wp-admin stylesheet provides. For h1 it happens to match the browser default of 2em, but this is not hte case with h2 and h3s, and as you can also see it customizes the default font weight of all heading sizes too.

It is frustrating that this bleeds from the wp-admin into the editing canvas, and as mentioned I would like to refactor this away long term by better scoping the admin styles, or by protecting the canvas using Shadow DOM, or any other method we can to prevent or mitigate CSS bleed.

So this PR is focusing on the most beneficial next step we can take — which is to still normalize those sizes, but at least reduce the specificity so they are easier to override.

My reason for putting these in theme.scss was to provide a theme some means to adopt them without outright copy them. Another option is to put them into editor.scss, where they will ONLY be loaded for the editor. But then a theme has to copy them, if they want to build on them. But in this specific case — for headings — maybe this is what we want?

The other perspective is that it can be convenient for a theme to simply opt into styles using
add_theme_support( 'wp-block-styles' );�and then the frontend immediately looks like the backend and can then build from there. But perhaps this is an argument for a separate opt in, something like add_theme_support( 'wp-block-normalize' );, which opts into the same normalization stylesheet that we need for the editing canvas?

[jasmussen]

Similar question here.

Because the purpose of this PR is to remove the intrinsic block margin, we have to actually re-apply those margins somewhere else.

Where should these rules live? Should they be in a vanilla editor style only? Should they be opinionated editor styles as they are here? Or something else? Really difficult question, but it gets at the heart of some of the CSS bleed issues this PR also aims to fix. CC: @m-e-h for expert commentary here thank you.

[m-e-h]

Same as with headings. If the theme has their own p margins, those will get used. Otherwise it'll fall back to these styles or to the browser styles.

Both Chrome and Firefox have this:

p {
    margin-block-start: 1em;
    margin-block-end: 1em;
}

which is the same as margin-top and margin-bottom

Here are some samples of default browser styles for reference: https://github.com/mozdevs/cssremedy/tree/master/process/UA_stylesheets

[m-e-h]

Where should these rules live?

Good question. Not really sure.

I do think that general selectors like this should probably never go in a block specific stylesheet.
Sure, this is a "paragraph" block and it makes sense to style a p here but it sets a poor example. I wouldn't want to encourage blocks to freely use element selectors in their block styles.

So, the more I think about it, maybe a separate set of styles like this, imported or enqueued before any other block styles, is a good way to go.
It would be invisible to any theme (most) that had their own styles for these elements.

[joyously]

Would it make a difference if you viewed it from a Drupal developer's perspective?

[chrisvanpatten]

This feels appropriate for some kind of "canvas reset" file, which is only enqueued in the backend.

[jasmussen]

Same as with headings. If the theme has their own p margins, those will get used. Otherwise it'll fall back to these styles or to the browser styles.

Just to clarify, Otherwise it'll fall back to these styles or to the browser styles. is not correct for the editing canvas. In the editing canvas it will fall back to the WP-admin styles, which look like this:

I'm starting to think that the idea by @getdave and later @chrisvanpatten of a "normalization" stylesheet might be the correct place to put styles like these, which are unfortunately necessary for the time being.

[jasmussen]

This could also be 2em if we thought that was nicer.

[kjellr]

I'd prefer if we could stick to em-based sizes for all text-related measurements in general. It looks like we're already doing that with top/bottom margins for our headings, so we should continue that here.

[jasmussen]

This here is inspired by feedback on a separate but related PR, here: #14366 (comment)

The idea is that we know we want to apply a modicum of styles to blocks, either to support them structurally (function in the first place), or to make sure we don't provide a broken or unstyled-looking experience. In the case of the figcaption element as is the core of that other PR, this element is born without margins, which means it sits right up next to the image unless it receives a margin.

The question is, should Gutenberg have such a base stylesheet that cascades? I've collected the two existing rules we already have, for img and iframe, and once that other PR goes through, we'd also have figcaption on this list. Should p also be there? And should there be a way to opt-in to this vanilla stylesheet, or opt out of it? These are questions that would be good to figure out, and I would appreciate your thoughts.

[getdave]

should Gutenberg have such a base stylesheet that cascades?

I'm not clear on the implications of this either way. Or is that the question?

Are you proposing effectively a normalize.css style base stylesheet for the Editor that just restores the default styles in a standard manner or would this go further still?

And should there be a way to opt-in to this vanilla stylesheet, or opt out of it?

You should certainly be able to disable it if you know what you're doing. Probably on by default.

[joyously]

I think the biggest group of themes is the ones that created a style sheet for the old editor. The best way to move forward with the least impact is to have the add_editor_style function call the new block editor style function that loads the styles with the prefixed selectors. Then the old styles will be in effect for the editor and the front end, and no blocks are styled. The HTML elements themselves are styled. This is the majority of existing themes. The editor should only style the UI elements and not the blocks. If any blocks need styling, put it in the style sheet that is opt-in.
With the old editor, there were rudimentary styles for standard classes alignleft. alignright, aligncenter. These were not output on the front end. The theme is responsible for that, and it makes sense to continue in the same way.

[jasmussen]

This has the side-effect of always providing this much space down to the first block:

Compare with master:

But this is actually the simplest and cleanest way to provide a consistent experience without resorting to crazy first-child and conditional rules. Consider a situation where the first block inserted is not born with a top-margin. Or consider one where the first block inserted has a HUGE intentional top margin. If we zero that margin out to override and provide a different one, we cancel that out.

By providing this slightly larger margin, we avoid all that happening. If we are passionate about keeping the current behavior while improving things, the real way to go here is to convert the title to an actual block, and not just a "faux" block as it is right now.

[getdave]

This rule seems ok, especially when we consider that if the first Block does have a margin and it is larger than the bottom margin on the page title then margin collapsing should ensure that it doesn't double up.

Block shouldn't have huge top margins, but if they do then perhaps the Block author should be responsible for ensuring they play nicely in these types of situations?

[kjellr]

This seems 100% fine to me, for all the reasons @getdave mentioned. And frankly, I like the appearance of the little bit of extra margin up there. 😄

[joyously]

I say remove all styles that have padding and margins for blocks. Only style the UI elements of the editor.

[jasmussen]

Let's discuss this one too.

In browsers, if you don't load a stylesheet, ol and ul are both born with 1em margins above and below.

In this case, and the reason this rule sits in editor-styles.scss, is that it actually has to be rewritten again, otherwise the editing canvas will inherit upstream rules from the WordPress admin CSS.

While the long term solution here is to refactor the WordPress admin to be better scoped and not bleed into the editing canvas, that's likely a ways out. In the mean time, there's this.

Which brings us to the question: is this the right place for it? How about theme.scss like the p rules?

[getdave]

This feels like this is needed to ensure the core markup in the editor renders in a suitable fashion out of the box. Therefore in my mind it should be part of the core editor styles rather than an optional Theme specific style. If Theme authors want to tweak the spacing they can do so or they can opt out of the theme.css file entirely and provide their own rules.

[joyously]

Don't have any styles on plain elements. If you can't put a class on it for the editing canvas, you shouldn't be styling it.

[m-e-h]

it should be part of the core editor styles rather than an optional Theme specific style.

I agree. This shouldn't be optional if we're re-normalizing something from common.css or an inline style from WP admin. If that's the case margin: initial would work as well.

However, currently theme.css isn't optional in the editor so there would be fine if that doesn't change.

[jasmussen]

Don't have any styles on plain elements. If you can't put a class on it for the editing canvas, you shouldn't be styling it.

This is a noble goal, one we should strive for. But until we can prevent CSS bleed from wp-admin through, for example, Shadow DOM, we have to unstyle even plain elements, otherwise they will look like just another wp-admin settings page. Just to be completely clear, here's what that would look like: https://user-images.githubusercontent.com/1204802/54341682-b75ec680-463a-11e9-964f-607f5223364f.gif

[jasmussen]

@ellatrix can you recall why we added this rule?

I removed it in this PR, because it bleeds into the p tag inside the Paragraph block, and as part of this PR we'd like to provide as clean and easily CSS overridable rules for that tag as possible. See https://github.com/WordPress/gutenberg/pull/14407/files#diff-7d328366ff8c0797fbdd334dcdf8b1a2R1

As far as I can tell, removing this one doesn't cause any visual regressions, but if you can recall why it's there it might help verify this.

[jasmussen]

If we're mostly using 2em for blocks that need it, we might want to retire this. But it's fortunate that 2em matches 32px, which happens to be the same as this.

[getdave]

It's fantastic to see this experiment raised. It really needs addressing, especially in context of Columns.

I've left what feedback I can. Available to discuss.

[jasmussen]

Thank you for the feedback, it's solid! I'll respond more in depth later, but just wanted to say thanks!

[kjellr]

I'm going to dig in more in depth later, but in general, this is looks great. It behaves generally like it did before, but our code is less aggressive.

Just a quick bug to note: the spacer block seems to disappear under adjacent blocks sometimes:

[jasmussen]

Wonderful, thanks for testing Kjell.

Yes, I definitely want to go over each block with a fine tooth comb to ensure the out of box experience is solid. I have, for the time being, focused on the Paragraph and Heading because once we get those right (and their CSS in the right place), all the other blocks can follow that pattern.

[jasmussen]

For all of you reviewing, and please do because I'm excited to get this PR on the road, I'd like to clarify a bit about the CSS we have for blocks, why we have it, and why it's necessary.

In general, the CSS we load into the editor falls into more than just one category:

1. There's structural CSS in order for a block to function (for example Cover)
2. It's also about providing a good, intentionally designed base experience for the editor, even for older WordPress themes that do not provide editor styles. For example ensuring figcaption has a margin, see Try: Move color and font size from captions to theme #14366
3. Finally, and this is a tricky part, we have to provide CSS styles to the editor, where they would otherwise inherit upstream CSS bleed styles from wp-admin, as is for example the case with the ol and ul styles, which are provided for the wp-admin and bleed into the editor.

For 3, the long term solutions are wide-ranging from Shadow DOM to simply refactoring wp-admin. But in order to provide near-term improvements, we have to override those.

The three are important to keep in mind, when evaluating where a CSS rule should be placed, and subsequently loaded.

[chrisvanpatten]

I haven't dug into these enough to leave detailed feedback, but overall I really appreciate the ideas at play here. I think the "ideal" state (which, admittedly, may not actually be possible) is that Gutenberg's UI is completely agnostic about all styles except its own editor chrome. This definitely moves us a bit closer in that direction, which is really nice to see.

[chrisvanpatten]

@jasmussen Just to clarify:

There's structural CSS in order for a block to function (for example Cover)

Is this essentially the editor.css file provided by each block? This doesn't live in a centralized place, right? (Although we may compile it down to one place in the case of core blocks, I mean that these are editor styles linked to specific blocks, not applying in a global/editor-level context)

It's also about providing a good, intentionally designed base experience for the editor, even for older WordPress themes that do not provide editor styles. For example ensuring figcaption has a margin, see #14366

I know there's more discussion happening on #14366, but I think this is a particular area of confusion. It seems like these styles always load in the editor, but are opt-in on the front-end. There may be nothing we can do about it now, but it would be helpful to clarify — is there in fact a way to opt-out of these styles loading in the editor?

I would also add that I think a good long term goal should be to remove these styles. At a certain point, they would be replaced by loading front-end styles within the editor (or loading the editor over the front-end), so older themes don't need any special accommodations.

Finally, and this is a tricky part, we have to provide CSS styles to the editor, where they would otherwise inherit upstream CSS bleed styles from wp-admin, as is for example the case with the ol and ul styles, which are provided for the wp-admin and bleed into the editor.

I saw a note about normalize above and it does seem like that's the sort of vein this is in — a wp-specific reset, that essentially allows the editor canvas to start from a (relatively) unstyled place. Is that reasonable?

[jasmussen]

I haven't dug into these enough to leave detailed feedback, but overall I really appreciate the ideas at play here. I think the "ideal" state (which, admittedly, may not actually be possible) is that Gutenberg's UI is completely agnostic about all styles except its own editor chrome. This definitely moves us a bit closer in that direction, which is really nice to see.

I would agree with this, with the added note that in this ideal state, the editor is already and always styled, because it just loads the theme stylesheet in directly!

It's good to restate this as the utopian goal. As you say we might not be able to fully get there, but I think we can get close, even if it may take many in-between steps, like this PR.

[jasmussen]

Is this essentially the editor.css file provided by each block? This doesn't live in a centralized place, right? (Although we may compile it down to one place in the case of core blocks, I mean that these are editor styles linked to specific blocks, not applying in a global/editor-level context)

No, by structural block styles, specifically with the Cover block as an example, there are styles that are necessary to load into both the editor and the theme in order for the block to work at all. For example the fixed background won't work unless the block itself supplies the ruleset, even to the theme. Though if you want as CSS pure an experience, one could imagine a block manager could disable blocks on a per-user or per-site basis, and thus not enqueue those styles.

It seems like these styles always load in the editor, but are opt-in on the front-end. There may be nothing we can do about it now, but it would be helpful to clarify — is there in fact a way to opt-out of these styles loading in the editor?

I think it's okay to have that conversation here! So to simplify: you're suggesting that theme.scss should only be loaded into the editor if the theme has declared support using add_theme_support( 'wp-block-styles' ); correct? @gziolo @mapk what are your thoughts on this? Are there any obvious aspects I'm missing?

I saw a note about normalize above and it does seem like that's the sort of vein this is in — a wp-specific reset, that essentially allows the editor canvas to start from a (relatively) unstyled place. Is that reasonable?

It's both a wp-admin styles reset, but it's also a vanilla style for themes that don't supply editor styles, which is still the overwhelming majority of themes. The idea being that if you're using an old theme, you should still have a good editing experience, and not have something that looks unstyled (or in this case it would actually be a gray wp-admin Settings-like page). Balancing that with allowing those themes that actually do style the editor to easily override it, is sort of the crux of it all.