Theme JSON: Add a spacing.blockBackgroundPadding style property

[aaronrobertshaw]

Follow up to #82024. See #36586.

What?

#82024 moved the padding that blocks get when they have a background color to a --wp--style--block-background-padding custom property.

This PR adds a theme.json style that sets the same property, so themes can change or remove that padding without custom CSS.

Why?

Setting the custom property today means hand writing CSS in styles.css. A first class property is easier to find, validates against the schema, and can be set for a single block type.

How?

styles.spacing.blockBackgroundPadding maps to the custom property the block stylesheets already read, following the same pattern as the existing root padding properties. Both the backend and the editor output it, and a test on each side asserts the same output so the two can't drift apart.

The property stays theme facing for now, so it does not appear anywhere in the Global Styles interface.

How to use

{
	"version": 3,
	"styles": {
		"spacing": {
			"blockBackgroundPadding": "0"
		}
	}
}

Any value works, not only 0, including a preset such as var:preset|spacing|50. For a single block type, set it under styles.blocks, for example styles.blocks.core/group.spacing.blockBackgroundPadding, and blocks nested inside inherit it unless they set their own.

Testing Instructions

Group and Template Part only load these styles when a theme calls add_theme_support( 'wp-block-styles' ), so test with Twenty Twenty-One as well as Twenty Twenty-Five.

1. Insert a Paragraph, List, Heading, Preformatted, Columns, Group, and Template Part block, and give each one a background color.
2. Confirm the padding on each looks the same in the editor as it does on the front end.
3. Add the snippet above to the theme's theme.json. Confirm the padding is removed from all seven, in the editor and on the front end.
4. Change the value to 1rem 2rem and confirm all seven pick it up.
5. Move the value under styles.blocks.core/group. Confirm Group changes, the other six keep the default, and a Paragraph with a background color nested inside the Group inherits the Group's value.
6. Add a core/paragraph value as well and confirm it wins over the one inherited from the Group.
7. Confirm blocks without a background color are unchanged.
8. Confirm nothing new appears in the Styles interface.

Alternatives

Instead of allowing custom padding values this could be a simple boolean that enables or disables the default padding. At this stage, we might as well let theme authors have more control rather than less.

[github-actions]

Size Change: +15 B (0%)

Total Size: 7.91 MB

📦 View Changed

Filename	Size	Change
build/scripts/blocks/index.min.js	45.6 kB	+15 B (+0.03%)

_{compressed-size-action}

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: aaronrobertshaw <aaronrobertshaw@git.wordpress.org>
Co-authored-by: tellthemachines <isabel_brison@git.wordpress.org>
Co-authored-by: andrewserong <andrewserong@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Flaky tests detected in c279c2f.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/32951064987
📝 Reported tests:

persists table layout across all tabs with unified view persistence in /test/e2e/specs/site-editor/pages-view-persistence.spec.js, passed after 1 failed attempt.

Error: apiRequestContext.get: socket hang up
Call log:
  - → GET http://localhost:8889/wp-admin/themes.php?action=activate&stylesheet=twentytwentyone&_wpnonce=108a3d99cc
    - user-agent: Playwright/1.62.1 (x64; ubuntu 24.04) node/20.20 CI/1
    - accept: */*
    - accept-encoding: gzip,deflate,br
    - cookie: wordpress_test_cookie=WP%20Cookie%20check; wordpress_23778236db82f19306f247e20a353a99=admin%7C1787908239%7Ch2ZDMqCEdRyabbJcay9hfxnt6L4HqbuE5CTssthjZDo%7C5dbd9b9f4fcf63f3d666c5f55884714b38a49bede143fac1a46f6fa0bfa6951f; wordpress_logged_in_23778236db82f19306f247e20a353a99=admin%7C1787908239%7Ch2ZDMqCEdRyabbJcay9hfxnt6L4HqbuE5CTssthjZDo%7C8bdad6d1dd54e06d747d2fbd85e0f560b5bba938d510bf3c5a9708f438b14997; wp-settings-time-1=1787736429
  - ← 302 Found
    - date: Wed, 26 Aug 2026 09:27:09 GMT
    - server: Apache/2.4.68 (Debian)
    - x-powered-by: PHP/8.3.33
    - expires: Wed, 11 Jan 1984 05:00:00 GMT
    - cache-control: no-cache, must-revalidate, max-age=0, private
    - referrer-policy: strict-origin-when-cross-origin
    - x-frame-options: SAMEORIGIN
    - content-security-policy: frame-ancestors 'self';
    - x-redirect-by: WordPress
    - location: http://localhost:8889/wp-admin/themes.php?activated=true
    - server-timing: wpTotal;dur=33.23, wpMemoryUsage;dur=4707216, wpDbQueries;dur=43
    - content-length: 0
    - keep-alive: timeout=5, max=93
    - connection: Keep-Alive
    - content-type: text/html; charset=UTF-8
  - → GET http://localhost:8889/wp-admin/themes.php?activated=true
    - user-agent: Playwright/1.62.1 (x64; ubuntu 24.04) node/20.20 CI/1
    - accept: */*
    - accept-encoding: gzip,deflate,br
    - host: localhost:8889
    - cookie: wordpress_test_cookie=WP%20Cookie%20check; wordpress_23778236db82f19306f247e20a353a99=admin%7C1787908239%7Ch2ZDMqCEdRyabbJcay9hfxnt6L4HqbuE5CTssthjZDo%7C5dbd9b9f4fcf63f3d666c5f55884714b38a49bede143fac1a46f6fa0bfa6951f; wordpress_logged_in_23778236db82f19306f247e20a353a99=admin%7C1787908239%7Ch2ZDMqCEdRyabbJcay9hfxnt6L4HqbuE5CTssthjZDo%7C8bdad6d1dd54e06d747d2fbd85e0f560b5bba938d510bf3c5a9708f438b14997; wp-settings-time-1=1787736429

    at RequestUtils.activateTheme (/home/runner/work/gutenberg/gutenberg/packages/e2e-test-utils-playwright/src/request-utils/themes.ts:45:32)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/pages-view-persistence.spec.js:34:3

[tellthemachines]

and blocks nested inside inherit it unless they set their own.

I wonder if this'll be unexpected because that's not how other spacing values work (or any other block supports for that matter). I understand why it works like that given we're using a custom property, and conceivably theme devs can specify values for each block type if they want, so it's probably not much of an issue.

[aaronrobertshaw]

I wonder if this'll be unexpected because that's not how other spacing values work

Yeah, it's a good question. One I was concerned about initially as well.

The more I thought on it though, the more it didn't seem like a big deal. Most issues and history I could find was about theme authors and users just wanting to avoid the background color dependent padding altogether. Even less to only opt out of it for a single block type.

I'm certainly open to other ideas or opinions though.

[tellthemachines]

This is working well but it feels overkill as an API, mostly because we're adding a property that can be set on any block, but will only work on a very few of them. For Group and Template Part it'll only have an effect on themes that include those stylesheets, which classic themes have to explicitly add support for and are not recommended for use on block themes at all.

It might be better to leave this for now, see how the custom property added in #82024 gets used, and then revisit if needed.

[aaronrobertshaw]

Appreciate the thoughtful feedback. I don't hold a strong opinion either way.

The initial PR, #82024, seemed to get a positive response to adding the theme.json setting to avoid theme authors requiring custom css values. I'd be ok, with closing this PR for now and seeing how only the custom property in #82024 goes like you said.

@ramonjd and @andrewserong, what do you think?

[andrewserong]

I'd be ok, with closing this PR for now and seeing how only the custom property in #82024 goes like you said.

This is a weakly held opinion, but I'd go that way, too. Conceptually I like the idea of this PR but it sort of raises a question of should you also be able to set blockBackgroundPadding on blocks that don't canonically support it? I.e. a take a random block that supports background colors, should I be able to set its padding just for when a background is applied? That could be a cool feature, but it's a bit beyond the original intention in #82024 which was just to allow themes a mechanism to remove the block background padding, rather than add it 🤔

So, my vote would be to land #82024 for now, and come back to this if/when there's a desire from theme devs to have more control over it.

[aaronrobertshaw]

but it sort of raises a question of should you also be able to set blockBackgroundPadding on blocks that don't canonically support it

That's it in a nutshell, really.

I'll close this one then get the base PR merged. We can resurrect this if needed down the line.