Bug when using only custom spacing sizes and setting spacingScale.steps to 0

[tomdevisser]

Description

When configuring a theme to use only custom spacing sizes in theme.json, I ran into issues with the spacingScale setting.

If I set settings.spacing.spacingScale.steps to 0, the JSON schema throws an error:

“Value is below the minimum of 1.”

However, if I set it to 5 (to match the number of custom spacingSizes I’ve defined), the UI unexpectedly shows the default spacing sizes — even though I’ve explicitly set "defaultSpacingSizes": false.

This seems to expose two bugs:

1. There’s no valid way to fully disable the internal spacing scale when using only custom sizes.
2. The default scale is applied even when it’s explicitly turned off, depending on the steps value.

Step-by-step reproduction instructions

1. Create a block theme using schema version 3.
2. In theme.json, configure spacing settings as follows:

"spacing": {
  "defaultSpacingSizes": false,
  "blockGap": true,
  "customSpacingSize": false,
  "margin": true,
  "padding": true,
  "spacingScale": {
    "steps": 5
  },
  "spacingSizes": [
    { "name": "Extra Small - 0.5rem", "size": "0.5rem", "slug": "xs" },
    { "name": "Small - 1rem", "size": "1rem", "slug": "sm" },
    { "name": "Medium - 1.5rem", "size": "1.5rem", "slug": "md" },
    { "name": "Large - 2.5rem", "size": "2.5rem", "slug": "lg" },
    { "name": "Extra Large - 3rem", "size": "3rem", "slug": "xl" }
  ],
  "units": ["rem"]
}

3. Observe that the spacing UI includes default spacing sizes, even though they were explicitly disabled.
4. Try setting steps to 0 to remove the default scale — the schema rejects it as invalid.

Screenshots, screen recording, code snippet

Environment info

• LocalWP setup
• PHP 8.2.27
• WordPress 6.8.1
• No plugins installed
• Browser: Brave v1.79.123

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

Please confirm which theme type you used for testing.

• Block
• Classic
• Hybrid (e.g. classic with theme.json)
• Not sure

[t-hamano]

However, if I set it to 5 (to match the number of custom spacingSizes I’ve defined), the UI unexpectedly shows the default spacing sizes — even though I’ve explicitly set "defaultSpacingSizes": false.

The spacingScale field is an option to automatically generate presets based on certain conditions. If you want to enable only the presets you define, you do not need to define it. Example:

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 3,
	"settings": {
		"appearanceTools": true,
		"layout": {
			"contentSize": "840px",
			"wideSize": "1100px"
		},
		"spacing": {
			"defaultSpacingSizes": false,
			"blockGap": true,
			"customSpacingSize": false,
			"spacingSizes": [
				{ "name": "Extra Small - 0.5rem", "size": "0.5rem", "slug": "xs" },
				{ "name": "Small - 1rem", "size": "1rem", "slug": "sm" },
				{ "name": "Medium - 1.5rem", "size": "1.5rem", "slug": "md" },
				{ "name": "Large - 2.5rem", "size": "2.5rem", "slug": "lg" },
				{ "name": "Extra Large - 3rem", "size": "3rem", "slug": "xl" }
			]
		}
	}
}

[tomdevisser]

Thank you, @t-hamano! I tested it, and it works.

While that approach does seem to work, I generally prefer to be explicit and define all settings to avoid unexpected changes from future core updates. That said, it looks like steps only accepts integers, and setting spacingScale to an empty object still results in the default sizes being generated.

I’ll go ahead and update the issue from a bug to an enhancement.

[t-hamano]

I generally prefer to be explicit and define all settings to avoid unexpected changes from future core updates.

If any changes are made that affect backward compatibility, a version update will be made, so we shouldn't have to worry about that.

See https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/theme-json-reference/theme-json-migrations.md

I’ll go ahead and update the issue from a bug to an enhancement.

Specifically, what improvements are you hoping to see?