Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add block spacing gap config to theme.json and add support for this CSS variable to the "flow/default" layout. #33812

Merged
merged 17 commits into from
Aug 19, 2021

Conversation

youknowriad
Copy link
Contributor

Folks have asked for some time now for a consistent way to tweak the margin/gap between blocks. This PR tries to solve that.

Decisions and choices made on this PR

  • The "block gap" is a generic style that can apply to any container block no matter of its layout type (right now we have flow and flex layouts but more will come)
  • Each layout type can "consume" the gap configuration and CSS variable and apply it to its children properly. In the current PR, the "flow" (or default) layout type uses the gap config to space the blocks vertically. While not implemented yet the "flex horizontal" layout could use the gap to space the blocks horizontally.
  • No UI/block support has been added for now, but we could imagine the gap being added to the inspector controls of container blocks (regardless of their layout type) to tweak its value contextually.
  • We'll provide a default style for this property for themes with theme.json file. This is most likely going to impact themes that are trying to switch to theme.json. I think the impact is not going to be very big but it's worth mentioning.

Notes

For block templates a global CSS style applied to the root of the block templates is added by default to the theme.json generated stylesheet. Unfortunately for classic templates, we can't generate that styles automatically in the frontend because the "wrapper" for post-content doesn't have a consistent className (like .entry-content or something). This is also the exact same reason we ask these theme-authors to add "layout" (wide/full alignments) styles on their own to the frontend. We could potentially try a solution for this separately by relying on a convention.

Testing instructions

  • tweak the "spacing": { "gap": "some value" } in your theme.json file
  • Ensure that it impacts editor and frontend properly
  • Check that there's no specific block styles overriding this gap.

@youknowriad youknowriad added Customization Issues related to Phase 2: Customization efforts Needs Dev Note Requires a developer note for a major WordPress release cycle [Feature] Themes Questions or issues with incorporating or styling blocks in a theme. [Feature] Full Site Editing [Type] New API New API to be used by plugin developers or package users. labels Aug 2, 2021
@youknowriad youknowriad self-assigned this Aug 2, 2021
@@ -2,7 +2,5 @@
&.has-background {
// Matches paragraph Block padding
padding: $block-bg-padding--v $block-bg-padding--h;
margin-top: 0;
margin-bottom: 0;
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was conflicting with the this consistent margin styling. @jasmussen maybe you know where in our code base we define the block margins and whether we should move these to classic.css now.

@github-actions
Copy link

github-actions bot commented Aug 2, 2021

Size Change: +5.45 kB (+1%)

Total Size: 1.04 MB

Filename Size Change
build/block-directory/index.min.js 6.2 kB -4 B (0%)
build/block-editor/index.min.js 119 kB +453 B (0%)
build/block-editor/style-rtl.css 13.9 kB +14 B (0%)
build/block-editor/style.css 13.8 kB +9 B (0%)
build/block-library/blocks/group/theme-rtl.css 70 B -23 B (-25%) 🎉
build/block-library/blocks/group/theme.css 70 B -23 B (-25%) 🎉
build/block-library/common-rtl.css 1.29 kB +458 B (+55%) 🆘
build/block-library/common.css 1.29 kB +458 B (+55%) 🆘
build/block-library/editor-rtl.css 9.87 kB +478 B (+5%) 🔍
build/block-library/editor.css 9.85 kB +478 B (+5%) 🔍
build/block-library/index.min.js 147 kB +163 B (0%)
build/block-library/style-rtl.css 10.2 kB +467 B (+5%) 🔍
build/block-library/style.css 10.3 kB +466 B (+5%) 🔍
build/block-library/theme-rtl.css 692 B +4 B (+1%)
build/block-library/theme.css 696 B +4 B (+1%)
build/blocks/index.min.js 47 kB +48 B (0%)
build/components/style-rtl.css 15.7 kB +1 B (0%)
build/customize-widgets/index.min.js 11.1 kB +709 B (+7%) 🔍
build/data/index.min.js 7.09 kB +66 B (+1%)
build/edit-navigation/index.min.js 13.6 kB +265 B (+2%)
build/edit-navigation/style-rtl.css 3.19 kB +98 B (+3%)
build/edit-navigation/style.css 3.19 kB +94 B (+3%)
build/edit-post/index.min.js 28.6 kB +217 B (+1%)
build/edit-post/style-rtl.css 7.2 kB +24 B (0%)
build/edit-post/style.css 7.2 kB +25 B (0%)
build/edit-site/index.min.js 26.2 kB +298 B (+1%)
build/edit-site/style-rtl.css 5.07 kB +63 B (+1%)
build/edit-site/style.css 5.07 kB +63 B (+1%)
build/edit-widgets/index.min.js 16 kB +190 B (+1%)
build/edit-widgets/style-rtl.css 4.06 kB +47 B (+1%)
build/edit-widgets/style.css 4.06 kB +46 B (+1%)
build/editor/index.min.js 37.7 kB +122 B (0%)
build/editor/style-rtl.css 3.74 kB -183 B (-5%)
build/editor/style.css 3.73 kB -181 B (-5%)
build/rich-text/index.min.js 10.6 kB +25 B (0%)
build/widgets/style-rtl.css 1.05 kB +7 B (+1%)
build/widgets/style.css 1.05 kB +8 B (+1%)
ℹ️ View Unchanged
Filename Size
build/a11y/index.min.js 931 B
build/admin-manifest/index.min.js 1.09 kB
build/annotations/index.min.js 2.7 kB
build/api-fetch/index.min.js 2.19 kB
build/autop/index.min.js 2.08 kB
build/blob/index.min.js 459 B
build/block-directory/style-rtl.css 1.01 kB
build/block-directory/style.css 1.01 kB
build/block-library/blocks/archives/editor-rtl.css 61 B
build/block-library/blocks/archives/editor.css 60 B
build/block-library/blocks/archives/style-rtl.css 65 B
build/block-library/blocks/archives/style.css 65 B
build/block-library/blocks/audio/editor-rtl.css 58 B
build/block-library/blocks/audio/editor.css 58 B
build/block-library/blocks/audio/style-rtl.css 111 B
build/block-library/blocks/audio/style.css 111 B
build/block-library/blocks/audio/theme-rtl.css 125 B
build/block-library/blocks/audio/theme.css 125 B
build/block-library/blocks/block/editor-rtl.css 161 B
build/block-library/blocks/block/editor.css 161 B
build/block-library/blocks/button/editor-rtl.css 474 B
build/block-library/blocks/button/editor.css 474 B
build/block-library/blocks/button/style-rtl.css 605 B
build/block-library/blocks/button/style.css 604 B
build/block-library/blocks/buttons/editor-rtl.css 315 B
build/block-library/blocks/buttons/editor.css 315 B
build/block-library/blocks/buttons/style-rtl.css 370 B
build/block-library/blocks/buttons/style.css 370 B
build/block-library/blocks/calendar/style-rtl.css 207 B
build/block-library/blocks/calendar/style.css 207 B
build/block-library/blocks/categories/editor-rtl.css 84 B
build/block-library/blocks/categories/editor.css 83 B
build/block-library/blocks/categories/style-rtl.css 79 B
build/block-library/blocks/categories/style.css 79 B
build/block-library/blocks/code/style-rtl.css 90 B
build/block-library/blocks/code/style.css 90 B
build/block-library/blocks/code/theme-rtl.css 131 B
build/block-library/blocks/code/theme.css 131 B
build/block-library/blocks/columns/editor-rtl.css 194 B
build/block-library/blocks/columns/editor.css 193 B
build/block-library/blocks/columns/style-rtl.css 474 B
build/block-library/blocks/columns/style.css 475 B
build/block-library/blocks/cover/editor-rtl.css 666 B
build/block-library/blocks/cover/editor.css 670 B
build/block-library/blocks/cover/style-rtl.css 1.23 kB
build/block-library/blocks/cover/style.css 1.23 kB
build/block-library/blocks/embed/editor-rtl.css 488 B
build/block-library/blocks/embed/editor.css 488 B
build/block-library/blocks/embed/style-rtl.css 400 B
build/block-library/blocks/embed/style.css 400 B
build/block-library/blocks/embed/theme-rtl.css 124 B
build/block-library/blocks/embed/theme.css 124 B
build/block-library/blocks/file/editor-rtl.css 300 B
build/block-library/blocks/file/editor.css 300 B
build/block-library/blocks/file/style-rtl.css 255 B
build/block-library/blocks/file/style.css 255 B
build/block-library/blocks/file/view.min.js 322 B
build/block-library/blocks/freeform/editor-rtl.css 2.44 kB
build/block-library/blocks/freeform/editor.css 2.44 kB
build/block-library/blocks/gallery/editor-rtl.css 707 B
build/block-library/blocks/gallery/editor.css 706 B
build/block-library/blocks/gallery/style-rtl.css 1.05 kB
build/block-library/blocks/gallery/style.css 1.05 kB
build/block-library/blocks/gallery/theme-rtl.css 122 B
build/block-library/blocks/gallery/theme.css 122 B
build/block-library/blocks/group/editor-rtl.css 159 B
build/block-library/blocks/group/editor.css 159 B
build/block-library/blocks/group/style-rtl.css 57 B
build/block-library/blocks/group/style.css 57 B
build/block-library/blocks/heading/editor-rtl.css 152 B
build/block-library/blocks/heading/editor.css 152 B
build/block-library/blocks/heading/style-rtl.css 76 B
build/block-library/blocks/heading/style.css 76 B
build/block-library/blocks/home-link/style-rtl.css 247 B
build/block-library/blocks/home-link/style.css 247 B
build/block-library/blocks/html/editor-rtl.css 283 B
build/block-library/blocks/html/editor.css 284 B
build/block-library/blocks/image/editor-rtl.css 728 B
build/block-library/blocks/image/editor.css 728 B
build/block-library/blocks/image/style-rtl.css 482 B
build/block-library/blocks/image/style.css 487 B
build/block-library/blocks/image/theme-rtl.css 124 B
build/block-library/blocks/image/theme.css 124 B
build/block-library/blocks/latest-comments/style-rtl.css 284 B
build/block-library/blocks/latest-comments/style.css 284 B
build/block-library/blocks/latest-posts/editor-rtl.css 137 B
build/block-library/blocks/latest-posts/editor.css 137 B
build/block-library/blocks/latest-posts/style-rtl.css 528 B
build/block-library/blocks/latest-posts/style.css 527 B
build/block-library/blocks/list/style-rtl.css 63 B
build/block-library/blocks/list/style.css 63 B
build/block-library/blocks/media-text/editor-rtl.css 266 B
build/block-library/blocks/media-text/editor.css 263 B
build/block-library/blocks/media-text/style-rtl.css 488 B
build/block-library/blocks/media-text/style.css 485 B
build/block-library/blocks/more/editor-rtl.css 431 B
build/block-library/blocks/more/editor.css 431 B
build/block-library/blocks/navigation-link/editor-rtl.css 474 B
build/block-library/blocks/navigation-link/editor.css 474 B
build/block-library/blocks/navigation-link/style-rtl.css 94 B
build/block-library/blocks/navigation-link/style.css 94 B
build/block-library/blocks/navigation/editor-rtl.css 1.69 kB
build/block-library/blocks/navigation/editor.css 1.69 kB
build/block-library/blocks/navigation/style-rtl.css 1.65 kB
build/block-library/blocks/navigation/style.css 1.64 kB
build/block-library/blocks/navigation/view.min.js 2.52 kB
build/block-library/blocks/nextpage/editor-rtl.css 395 B
build/block-library/blocks/nextpage/editor.css 395 B
build/block-library/blocks/page-list/editor-rtl.css 310 B
build/block-library/blocks/page-list/editor.css 310 B
build/block-library/blocks/page-list/style-rtl.css 242 B
build/block-library/blocks/page-list/style.css 242 B
build/block-library/blocks/paragraph/editor-rtl.css 157 B
build/block-library/blocks/paragraph/editor.css 157 B
build/block-library/blocks/paragraph/style-rtl.css 248 B
build/block-library/blocks/paragraph/style.css 248 B
build/block-library/blocks/post-author/editor-rtl.css 210 B
build/block-library/blocks/post-author/editor.css 210 B
build/block-library/blocks/post-author/style-rtl.css 182 B
build/block-library/blocks/post-author/style.css 181 B
build/block-library/blocks/post-comments-form/style-rtl.css 140 B
build/block-library/blocks/post-comments-form/style.css 140 B
build/block-library/blocks/post-comments/style-rtl.css 360 B
build/block-library/blocks/post-comments/style.css 359 B
build/block-library/blocks/post-content/editor-rtl.css 138 B
build/block-library/blocks/post-content/editor.css 138 B
build/block-library/blocks/post-excerpt/editor-rtl.css 73 B
build/block-library/blocks/post-excerpt/editor.css 73 B
build/block-library/blocks/post-excerpt/style-rtl.css 69 B
build/block-library/blocks/post-excerpt/style.css 69 B
build/block-library/blocks/post-featured-image/editor-rtl.css 398 B
build/block-library/blocks/post-featured-image/editor.css 398 B
build/block-library/blocks/post-featured-image/style-rtl.css 143 B
build/block-library/blocks/post-featured-image/style.css 143 B
build/block-library/blocks/post-template/editor-rtl.css 99 B
build/block-library/blocks/post-template/editor.css 98 B
build/block-library/blocks/post-template/style-rtl.css 378 B
build/block-library/blocks/post-template/style.css 379 B
build/block-library/blocks/post-terms/style-rtl.css 73 B
build/block-library/blocks/post-terms/style.css 73 B
build/block-library/blocks/post-title/style-rtl.css 60 B
build/block-library/blocks/post-title/style.css 60 B
build/block-library/blocks/preformatted/style-rtl.css 103 B
build/block-library/blocks/preformatted/style.css 103 B
build/block-library/blocks/pullquote/editor-rtl.css 198 B
build/block-library/blocks/pullquote/editor.css 198 B
build/block-library/blocks/pullquote/style-rtl.css 361 B
build/block-library/blocks/pullquote/style.css 360 B
build/block-library/blocks/pullquote/theme-rtl.css 167 B
build/block-library/blocks/pullquote/theme.css 167 B
build/block-library/blocks/query-pagination-numbers/editor-rtl.css 122 B
build/block-library/blocks/query-pagination-numbers/editor.css 121 B
build/block-library/blocks/query-pagination/editor-rtl.css 270 B
build/block-library/blocks/query-pagination/editor.css 262 B
build/block-library/blocks/query-pagination/style-rtl.css 168 B
build/block-library/blocks/query-pagination/style.css 168 B
build/block-library/blocks/query-title/editor-rtl.css 85 B
build/block-library/blocks/query-title/editor.css 85 B
build/block-library/blocks/query/editor-rtl.css 131 B
build/block-library/blocks/query/editor.css 132 B
build/block-library/blocks/quote/style-rtl.css 169 B
build/block-library/blocks/quote/style.css 169 B
build/block-library/blocks/quote/theme-rtl.css 220 B
build/block-library/blocks/quote/theme.css 222 B
build/block-library/blocks/rss/editor-rtl.css 202 B
build/block-library/blocks/rss/editor.css 204 B
build/block-library/blocks/rss/style-rtl.css 289 B
build/block-library/blocks/rss/style.css 288 B
build/block-library/blocks/search/editor-rtl.css 165 B
build/block-library/blocks/search/editor.css 165 B
build/block-library/blocks/search/style-rtl.css 374 B
build/block-library/blocks/search/style.css 375 B
build/block-library/blocks/search/theme-rtl.css 64 B
build/block-library/blocks/search/theme.css 64 B
build/block-library/blocks/separator/editor-rtl.css 99 B
build/block-library/blocks/separator/editor.css 99 B
build/block-library/blocks/separator/style-rtl.css 250 B
build/block-library/blocks/separator/style.css 250 B
build/block-library/blocks/separator/theme-rtl.css 172 B
build/block-library/blocks/separator/theme.css 172 B
build/block-library/blocks/shortcode/editor-rtl.css 474 B
build/block-library/blocks/shortcode/editor.css 474 B
build/block-library/blocks/site-logo/editor-rtl.css 462 B
build/block-library/blocks/site-logo/editor.css 464 B
build/block-library/blocks/site-logo/style-rtl.css 153 B
build/block-library/blocks/site-logo/style.css 153 B
build/block-library/blocks/site-tagline/editor-rtl.css 86 B
build/block-library/blocks/site-tagline/editor.css 86 B
build/block-library/blocks/site-title/editor-rtl.css 84 B
build/block-library/blocks/site-title/editor.css 84 B
build/block-library/blocks/social-link/editor-rtl.css 165 B
build/block-library/blocks/social-link/editor.css 165 B
build/block-library/blocks/social-links/editor-rtl.css 812 B
build/block-library/blocks/social-links/editor.css 811 B
build/block-library/blocks/social-links/style-rtl.css 1.33 kB
build/block-library/blocks/social-links/style.css 1.33 kB
build/block-library/blocks/spacer/editor-rtl.css 307 B
build/block-library/blocks/spacer/editor.css 307 B
build/block-library/blocks/spacer/style-rtl.css 48 B
build/block-library/blocks/spacer/style.css 48 B
build/block-library/blocks/table/editor-rtl.css 471 B
build/block-library/blocks/table/editor.css 472 B
build/block-library/blocks/table/style-rtl.css 481 B
build/block-library/blocks/table/style.css 481 B
build/block-library/blocks/table/theme-rtl.css 188 B
build/block-library/blocks/table/theme.css 188 B
build/block-library/blocks/tag-cloud/style-rtl.css 146 B
build/block-library/blocks/tag-cloud/style.css 146 B
build/block-library/blocks/template-part/editor-rtl.css 636 B
build/block-library/blocks/template-part/editor.css 635 B
build/block-library/blocks/template-part/theme-rtl.css 101 B
build/block-library/blocks/template-part/theme.css 101 B
build/block-library/blocks/term-description/editor-rtl.css 90 B
build/block-library/blocks/term-description/editor.css 90 B
build/block-library/blocks/text-columns/editor-rtl.css 95 B
build/block-library/blocks/text-columns/editor.css 95 B
build/block-library/blocks/text-columns/style-rtl.css 166 B
build/block-library/blocks/text-columns/style.css 166 B
build/block-library/blocks/verse/style-rtl.css 87 B
build/block-library/blocks/verse/style.css 87 B
build/block-library/blocks/video/editor-rtl.css 571 B
build/block-library/blocks/video/editor.css 572 B
build/block-library/blocks/video/style-rtl.css 173 B
build/block-library/blocks/video/style.css 173 B
build/block-library/blocks/video/theme-rtl.css 124 B
build/block-library/blocks/video/theme.css 124 B
build/block-library/reset-rtl.css 527 B
build/block-library/reset.css 527 B
build/block-serialization-default-parser/index.min.js 1.09 kB
build/block-serialization-spec-parser/index.min.js 2.79 kB
build/components/index.min.js 209 kB
build/components/style.css 15.8 kB
build/compose/index.min.js 10.2 kB
build/core-data/index.min.js 12.3 kB
build/customize-widgets/style-rtl.css 1.5 kB
build/customize-widgets/style.css 1.49 kB
build/data-controls/index.min.js 614 B
build/date/index.min.js 31.5 kB
build/deprecated/index.min.js 428 B
build/dom-ready/index.min.js 304 B
build/dom/index.min.js 4.53 kB
build/edit-post/classic-rtl.css 492 B
build/edit-post/classic.css 494 B
build/element/index.min.js 3.16 kB
build/escape-html/index.min.js 517 B
build/format-library/index.min.js 5.36 kB
build/format-library/style-rtl.css 668 B
build/format-library/style.css 669 B
build/hooks/index.min.js 1.55 kB
build/html-entities/index.min.js 424 B
build/i18n/index.min.js 3.59 kB
build/is-shallow-equal/index.min.js 501 B
build/keyboard-shortcuts/index.min.js 1.49 kB
build/keycodes/index.min.js 1.25 kB
build/list-reusable-blocks/index.min.js 1.85 kB
build/list-reusable-blocks/style-rtl.css 838 B
build/list-reusable-blocks/style.css 838 B
build/media-utils/index.min.js 2.88 kB
build/notices/index.min.js 845 B
build/nux/index.min.js 2.03 kB
build/nux/style-rtl.css 747 B
build/nux/style.css 743 B
build/plugins/index.min.js 1.83 kB
build/primitives/index.min.js 921 B
build/priority-queue/index.min.js 582 B
build/react-i18n/index.min.js 671 B
build/redux-routine/index.min.js 2.63 kB
build/reusable-blocks/index.min.js 2.28 kB
build/reusable-blocks/style-rtl.css 256 B
build/reusable-blocks/style.css 256 B
build/server-side-render/index.min.js 1.32 kB
build/shortcode/index.min.js 1.48 kB
build/token-list/index.min.js 562 B
build/url/index.min.js 1.72 kB
build/viewport/index.min.js 1.02 kB
build/warning/index.min.js 248 B
build/widgets/index.min.js 6.27 kB
build/wordcount/index.min.js 1.04 kB

compressed-size-action

@youknowriad
Copy link
Contributor Author

@ellatrix This config doesn't seem to work in the site editor for some reason, not sure I understand why.

@carolinan
Copy link
Contributor

I find this concept more confusing than simply having margin support.

@jasmussen
Copy link
Contributor

Nice, thanks for working on this. I'm a big fan of gap! (See also #32366).

As far as the instructions in this PR, this also works as advertised, however it doesn't appear to be the gap that I was expecting. I'm getting this:

.editor-styles-wrapper .edit-post-visual-editor__post-title-wrapper > * + *, .editor-styles-wrapper .block-editor-block-list__layout.is-root-container > * + * {
    margin-top: var( --wp-theme-block-gap );
    margin-bottom: 0;
}

Would I get true gap if I set my layout to be a flex or grid container?

The margin-based gap as I see here is useful enough on its own, but the reason I'm longing for "true" gap is that it lets you stop worry about first-child/last-child margins entirely. I often compare it to Figma's auto-layout:

autolayout

Basically with using only padding and gap (Figma calls it "Space between items"), you can quite easily create consistent spacing. This is especially useful in masonry galleries, where you might have to tackle gnarly nth-child rules.

@youknowriad
Copy link
Contributor Author

This is inspired by on some advanced layout work you can read about here https://every-layout.dev/layouts/stack/
The gap only works in flex containers and for "flex" layout, that's exactly what we'll be using, but for "flow" layout, that trick is needed and it solves all the last-child/first-child issues.

@youknowriad
Copy link
Contributor Author

I find this concept more confusing than simply having margin support.

Margin is not something that will solve this issue consistently, theme authors will need to be able to target, first and last blocks... Also, it doesn't scale well to all types of layouts.

@mtias
Copy link
Member

mtias commented Aug 4, 2021

The key mental shift here is that margin, conceptualized as the spacing between blocks, is something extrinsic to the block itself and better imagined as a property of the container. Individual blocks can overwrite margin values, but it should be sporadic and considered more advanced (it can be difficult to handle for a user and break visual rhythm).

I think we might want to avoid gap to designated it, though, and lean more strongly on the "block" property. The description should be "Set the spacing between blocks". For the property perhaps spacing.blocks is fine? If we want to keep gap, maybe it should be blockGap.

Having control over this globally and per container should simplify how you need to deal with blocks and margins, as it should handle dealing with the top / bottom blocks by default, which has been a bit painful in columns already. In the "spacing" panel we should also be clear when a block is overwriting the default gap setting.

@youknowriad
Copy link
Contributor Author

I added support for the blockGap to the flex layout as well.

@andrewserong
Copy link
Contributor

andrewserong commented Aug 6, 2021

I think this looks very cool, I like the idea of using gap to control the spacing between blocks, and the CSS variable approach looks like a clever way to do it!

No UI/block support has been added for now,

Separately, I've been chipping away at a PR to add in a gap block support feature in #33991 as a way of trying to come up with a solution for #32366. My PR is split out from the ToolsPanel / DimensionsPanel work in #32392 and adds in UI / block support with a BoxControl in the inspector controls and global styles for controlling the gap. I was imagining this as a way of handling gap (and row-gap and column-gap for control over separate vertical and horizontal spacing) for blocks like Buttons, Navigation, Social Links, and possibly longer term the Gallery block. It's implemented in a similar way to margin and padding, but might not be the right way to go about it.

It looks like this PR will provide a more general solution and approach for layouts, so it looks like it might supersede my one. But I just thought I'd check in case there's anything useful in #33991 that you might want to pull in here or if there's a way to combine things. I'm happy to help any way I can!

With this PR, do you imagine the layout types will be rolled out to all other container blocks (e.g. Buttons, etc) or would we have a different approach for those sorts of blocks versus, say Group? It could also be good to include the ability to separately control row vs column gap, depending on where we roll the feature out, to support different kinds of layouts.

@jasmussen
Copy link
Contributor

Thank you, that's helpful! Sounds like the CSS-first refactor can move forward and be revisited further.

I don't think we have that yet but the use-cases for it are not clear yet. The issue you mentioned was a bug that is now closed. The block gets "flex" if the default layout is defined as "flex".

I ran into wanting to create a classic header menu that featured a site logo and a navigation block left and right as part of the Header template part, and finding that the stack-margin ruleset was applied even though I went for a horizontal layout:

Screenshot 2021-09-01 at 10 48 45

But that use case is already met by #33316, since this can now just be a single navigation block inside the header. But it does support the separate conversation we were having about allowing the group block to become a horizontal flex container.

@jasmussen
Copy link
Contributor

A thing I noticed as well. We output only the .wp-site-blocks > * + * rule which zeroes out the bottom margin and applies the top margin as a gap. We don't output a matching .wp-site-blocks > * { margin-top: 0; margin-bottom: 0; }; to take care of the first block in the stack:

before

Since in vertical flows, those margins commonly collapse, it's been fine so far. But it seems like we should? I can open a separate ticket.

@youknowriad
Copy link
Contributor Author

I think that makes sense 👍

@andersnoren
Copy link

From #33991, I got the impression that this feature is opt-in with settings.spacing.blockGap, but it seems like the .wp-container-XXX > * + * margin styles are output in 11.4.0 regardless of whether settings.spacing.blockGap exists or is set to false. Just double-checking if that's intentional.

@youknowriad
Copy link
Contributor Author

The current reasoning is that it's intentional, the style is not opt-in, the per block UI is.

@andersnoren
Copy link

Got it. That might cause some issues for themes that have different margins for different elements (for example, larger margin for headings, tables, separators etc. than paragraphs) and at different breakpoints, since the specificity on the styles overwriting .wp-container-XXX > * + * needs to be very high.

@youknowriad
Copy link
Contributor Author

it only applies to themes with theme.json though which I think has just been release on 5.8. So hopefully not a lot of themes. The dev note is supposed to clarify that. Do you think that's a fine shipping plan?

@youknowriad
Copy link
Contributor Author

youknowriad commented Sep 1, 2021

I'm also curious about the use-case. Would things like this solve it?

styles: {
   core/heading: {
       margin: "some value" 
   }
}

I'm also thinking it might not be the best approach because we don't want that "margin" value when the block is inside a horizontal/flex container for instance.

@andersnoren
Copy link

I think being able to opt out would lower the barrier for existing themes adding theme.json pretty significantly, since most themes would probably need to modify their margin styles a lot to overwrite the default gap value (in the cases where they want to overwrite them). I think there are cases where themes built with theme.json from the ground up would want to opt out as well, if many elements in the design have different margins for different breakpoints.

I'm also curious about the use-case. Would things like this solve it?

Being able to set the gap on a block level would definitely go a long way.

I'll ask for some input in the theme review channel on Slack.

@youknowriad
Copy link
Contributor Author

I think there are cases where themes built with theme.json from the ground up would want to opt out as well, if many elements in the design have different margins for different breakpoints.

The issue I have with this is that blocks shouldn't have intrinsic margins because blocks shouldn't be assuming that they are inserted in a "flow" container, they can be on a flex container, horizontal... and those margins won't make sense anymore. I don't think a theme author should have the responsibility to define all these use-cases because it will break very quickly.

We can add a way to "not output these styles", but I fear that this is just making things worse for themes and break some blocks in different contexts. So how to solve this use-case more holistically?

@MaggieCabrera
Copy link
Contributor

Got it. That might cause some issues for themes that have different margins for different elements (for example, larger margin for headings, tables, separators etc. than paragraphs) and at different breakpoints, since the specificity on the styles overwriting .wp-container-XXX > * + * needs to be very high.

I just checked this and [class*="wp-container-"] .block-selector is enough to override this rule. I'd want to control the margins of the blocks via theme.json like so. I get the problem when the block is in a flex group. My experience is that we want to establish defaults on a vertical level and then make exceptions on the horizontal one most of the time, but that might not be a good way to go about it.

@andersnoren
Copy link

Yeah, it's a difficult balance to strike. Most theme authors will want to have some degree of control over margins though, at least on the base element level (paragraphs, lists, headings, etc.), and it can pretty quickly lead to specificity wars.

For example, the margin styles generated for the h1 element by the code below get overwritten by the new .wp-container-XXX > * + * styles in 11.4.0:

"styles": {
	"elements": {
		"h1": {
			"spacing": {
				"margin": {
					"bottom": "48px",
					"top": "64px"
				}
			},
			"typography": {
				"fontSize": "var(--wp--preset--font-size--heading-1)",
				"letterSpacing": "var(--wp--custom--letter-spacing--heading)",
				"lineHeight": "var(--wp--custom--line-height--heading)",
				"fontWeight": "var(--wp--custom--font-weight--normal)"
			}
		},
	}
}

So if a theme would want to have a different margin than the blockGap for h1, they would need to add CSS looking something like this to overwrite it:

:root h1 {
	margin-bottom: 48px;
	margin-top: 64px;
}

@justintadlock
Copy link
Contributor

justintadlock commented Sep 1, 2021

Should theme authors be able to opt-out? If this is ever a question that comes up, the answer is always: Absolutely, 100%, yes!

The only assumption we should make is that a theme author will want to do something custom. If we start from that position, these sorts of conversations will happen less often.

This block gap feature has created issues across the board for me. My plan is to work with it as much as possible, but I am already seeing places where it will be problematic and force specificity battles.

Doing this in a per-block level would ease some of that. For example, my Heading elements tend to have a different top margin than Paragraph elements (this was actually the first thing I noticed that was broken).

Edit: On the topic of horizontal, flex, etc. containers: those are exceptions to the rule. For example, I target :first-child to remove top margins, which I think is pretty typical in design systems. This automatically handles things like the Columns/Column blocks. The same or similar methods would work in other types of containers.

@youknowriad
Copy link
Contributor Author

Should theme authors be able to opt-out? If this is ever a question that comes up, the answer is always: Absolutely, 100%, yes!

I disagree with this take. This means that everything should be optional in WordPress and goes against the decisions not options. some things need to be options but not everything.

After the discussion we had here, I agree that for now the block gap styles need to be opt-out because we don't have answers for all the use cases yet but I don't think it should be a rule to have an opt-out for everything personally. For instance for structural styles, I'd rather have the themes rely on Core always instead of reinventing their own. Themes are here to bring personality and design but not to define what "horizontal alignment" means for instance.

This block gap feature has created issues across the board for me. My plan is to work with it as much as possible, but I am already seeing places where it will be problematic and force specificity battles.

I'd love to learn mode about the use-cases to be able to come up with the best abstractions that solve this. If we always fallback to CSS to solve these issues, specificity issues will continue forever and adaptation as Core changes structural changes will continue to be a nightmare. Theme.json is an attempt to solve that, so we should try to reduce the need for these custom CSS (other than things that bring personality) from themes.

Doing this in a per-block level would ease some of that. For example, my Heading elements tend to have a different top margin than Paragraph elements (this was actually the first thing I noticed that was broken).

👍 Yes that use-case has been raised above and makes sense but it's also important to understand that it only makes sense in the "flow" layout. If you insert a heading block inside a horizontal container, it shouldn't have any margins. For this particular reason, we need to be more smart about it:

  • If it's theme author's responsibility, they'll forget about these things and create broken designs
  • if it's core responsibility, we need ways to ensure these things work properly in all contexts.

@MaggieCabrera
Copy link
Contributor

I can think of other cases where you'd want a different gap per block. One example would be the "small" blocks that have post meta content such as post date or post tags, we encountered this on skatepark, where the margin bottom (or gap) for an h1 could be 5 times or more the spacing between these smaller blocks:

Screenshot 2021-09-01 at 18 30 47

@chthonic-ds
Copy link
Contributor

Seeing the recent comments here, I was dreading how this might affect the block-based theme I'm currently working on. The effects ended up being minimal due to already adopting the "styling the context" approach every-layout.dev endorses, but at a different location: the .post-content level. My experience has been header/footer areas benefit less from the same rules, due to having their own micro-contexts to manage.

A few examples from my current theme where elements require different "gaps" in a flow context:

  • <h2> and <h3> following any element
  • any element following a Columns block (excluding another Columns block)
  • any element following a full/wide aligned element with a background colour set
  • any top-level element with a background colour set following any element
  • "meta" content following a heading

Should theme authors be able to opt-out? If this is ever a question that comes up, the answer is always: Absolutely, 100%, yes!

Very much agree from a theming perspective.

For instance for structural styles, I'd rather have the themes rely on Core always instead of reinventing their own.

If it's theme author's responsibility, they'll forget about these things and create broken designs. If it's core responsibility, we need ways to ensure these things work properly in all contexts.

I've gone back and forth since 5.0 with adding to core styles vs. 100% custom styles, and, overall, I've seen custom styles be the only way to achieve layouts I'm handed, as well as being the easiest to maintain over the long term (the other reason is, using custom styles has allowed me to use things like CSS Grid for layout now rather than waiting for it to appear as a WordPress-provided option).

Working with WordPress post-5.0 has meant learning to write styles in a much more defensive and resilient way, something I see as a positive outcome. However, I do often feel idiotic for writing my own style-sheets. Perhaps it's time to send a clear signal to someone like me by removing the option to dequeue core styles?

@mjsdiaz
Copy link

mjsdiaz commented Sep 2, 2021

I find this concept more confusing than simply having margin support.

I would like to be able to opt out for the theme global gap and opt-in on specific blocks.

@ellenbauer
Copy link

Should theme authors be able to opt-out? If this is ever a question that comes up, the answer is always: Absolutely, 100%, yes!

Yes, yes, yes!!! I think this is an absolute must, since a general rule might work for some smaller projects, but it does not leave enough choice/control for theme developers to make custom decisions.

At the moment I get the feeling in general that we might need more clarity on "what goes where" as I struggle to understand what is meant to be block 'territory' and what is theme territory and so on.
Is this just me or do others feel the same?

@iandunn
Copy link
Member

iandunn commented Sep 9, 2021

we don't have answers for all the use cases yet...
I'd love to learn mode about the use-cases to be able to come up with the best abstractions that solve this

I opened #34716 to start documenting use cases that need improvement

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Customization Issues related to Phase 2: Customization efforts [Feature] Themes Questions or issues with incorporating or styling blocks in a theme. Needs Dev Note Requires a developer note for a major WordPress release cycle [Type] New API New API to be used by plugin developers or package users.
Projects
Status: Done
Development

Successfully merging this pull request may close these issues.