WP 6.3 CSS specificity change breaks Block Gap margin in themes

[dbushell]

Description

WP 6.3 changed the inline CSS it generates for Gutenberg blocks.

Assuming block gap is configured to 1rem this from 6.2.2:

body .is-layout-flow > * + * {
  margin-block-start: 1rem;
  margin-block-end: 0;
}

changed in 6.3 to:

:where(body .is-layout-flow) > * {
  margin-block-start: 1rem;
  margin-block-end: 0;
}

The selector used changed specificity from 0-1-1 to the lower 0-0-0.

This can easily conflict with existing themes built on earlier versions of WordPress. Any theme stylesheet starting with a CSS reset probably includes:

p {
  margin: 0;
}

Removing browser default styles from elements like paragraph margin.

The p selector has a specifity of 0-0-1 so it overrides the block gap margins for certain Gutenberg block layouts because that was lowered to 0-0-0 in 6.3.

This is a breaking change that can introduce visual bugs to existing themes. There are likely many unique edge cases caught out by this specifity change and others, but CSS resets are extremely common practice so I've included that example.

Step-by-step reproduction instructions

1. Install WordPress 6.2 (older version)
2. Add/create a theme that includes a CSS reset with p { margin: 0; }
3. Add a page with a Columns block with two or more paragraphs in the first column
4. Inspect the front-end and see the block gap overrides the reset styles to give spacing between paragraphs
5. Upgrade to WP 6.3
6. Inspect the front-end and see the block gap is now missing between paragraphs

Screenshots, screen recording, code snippet

Example setup:

Example render in 6.3 missing block gap spacing:

Environment info

No response

Please confirm that you have searched existing issues in the repo.

Yes

Please confirm that you have tested with all plugins deactivated except Gutenberg.

Yes

[aaronrobertshaw]

Thanks for flagging this issue @dbushell 👍

It's a tricky one. The layout styles needed to have their specificity reduced to address a regression, introduced when layout support landed, that prevented global margin styles from taking effect.

The original PR (#47858) has some history and context that might be important here. It discusses the impacts of reducing the specificity on themes, 3rd party blocks etc. There is also a dev note that communicated the specificity reduction for some layout types.

@tellthemachines and @andrewserong do you have any recommendations when it comes to CSS resets and how they play with layout styles?

[dbushell]

Thanks for the added context I was struggling to find related notes.

My concern is that this and similar specificity changes have broken existing themes that auto-updated to WordPress 6.3. I build themes for clients but I'm not always employed to maintain them. Either way, I do not expect such visual bugs to be introduced. Dissuading or disabling updates isn't a viable solution. Perhaps my expectations are wrong? If so I'll comment on that no further, but I cannot continue to develop themes for WordPress as a freelancer. Apologies if this is the wrong place to vent such frustrations.

For any theme developers experiencing this issue, one fix may be to wrap the CSS reset styles in a cascade layer.

@layer reset {
  /* reset styles, e.g: */
  p { margin: 0; } 
}

This will bring their priority back down below the Gutenberg styles, and below the rest of the theme styles (which presumably they were already).

[andrewserong]

Thanks for the discussion here!

do you have any recommendations when it comes to CSS resets and how they play with layout styles?

This is a tricky one, but unfortunately this was a necessary breaking change. When it comes to layout, the layout styles for blocks themes are responsible for resetting margins, so there's (likely) no need for themes to do this themselves. There are also some themes that wish to intentionally override layout styles for particular elements, so it's difficult to give general advice for resets in a complete way, but my own opinion is that for themes that use layout, there's probably no need for margin-based resets (though themes may wish to still include other kinds of resets).

Either way, I do not expect such visual bugs to be introduced. Dissuading or disabling updates isn't a viable solution. Perhaps my expectations are wrong?

Thank you for providing candid feedback here! For what it's worth, I know contributors try to avoid breaking changes wherever possible, and unfortunately some features that fix issues for some use cases sometimes result in what appear to be visual bugs for other use cases. It can be challenging to find the right balance here — the objective is to always maintain backwards compatibility where possible and to hopefully on balance make the experience better overall through each release.

When it comes to the layout block support, it's recently gone through some iterations honing in on a hopefully more stable set of rules for now.

[dbushell]

Thanks for the reply. I hope I've expressed my feedback and criticism constructively. To clarify one point:

When it comes to layout, the layout styles for blocks themes are responsible for resetting margins, so there's (likely) no need for themes to do this themselves. There are also some themes that wish to intentionally override layout styles [...]

WordPress' flagship Twenty Twenty-One theme does this heavily, and Twenty-Two to a lesser degree.

[...] but my own opinion is that for themes that use layout, there's probably no need for margin-based resets (though themes may wish to still include other kinds of resets).

I don't disagree, but CSS resets are extremely common, the Twenty Twenty-One theme uses a CSS reset.

My point is that if WordPress flagship theme developers are unsure what is best pratice to style around Gutenberg, how are others expected to?

When it comes to the layout block support, it's recently gone through some iterations honing in on a hopefully more stable set of rules for now.

I appreciate the difficultly but those iterations continue to break themes. I've tried to fully embrace Gutenberg since WP 5.0. My frustrations come from years of clients asking why their website suddenly looks broken. I'm not blameless, but I can usually point to a WP update.

It seems to me many of these issues are self-imposed due to the frequency of WP/Gutenberg releases.

[spencerfinnell]

The original PR #47858 / WordPress 6.3 might also be causing other regressions related to block gap/spacing: #36053 (comment)

[carolinan]

Twenty twenty-One was built before the CSS changes to the block layout and it is not updated for two major reasons:

• As a default theme, it is required to continue to support the original minimum WordPress version. (So It can not be updated to only support the latest changes).
• Lack of contributors who have time and are able to work on fixing bugs with bundled themes.

[FabianKielmann]

This is also a problem when using tailwind.css. The reset is part of the main tailwind imports and adding a @layer reset {} as suggested above for example just results in other css issues.