Extend theme.json to provide spacing size presets

[glendaviesnz]

What problem does this address?

Background discussion.

On the above issue, there was some consensus that there would be value in extending theme.json to allow spacing size presets to be added, which gives users a set of preset size tokens to select from as well as/or instead of just adding custom spacing values.

This blog post provides a good introduction to some of the reasons for this.

This is intended to be a top-level issue for some of the initial discussions, as well as tracking the ongoing work needed to implement this.

The block UI will need to allow people to select from the presets (e.g. padding value Medium) in addition to the "absolute value" settings (e.g typing "23px"), and also allow for theme authors to disable the option to add absolute values.

Update

Summary of discussion and suggested way forward

Todo

• Add UI to Global styles to allow managing spacing presets #61986
• Add UI for adding fluid values at the block level. Ensure that [mobile requirements]
• Look at disabling core scale with false or null as well as by setting steps:0
• Investigate adding of utility classes instead of inline styles (needs to work conditionally based on current blocks or too many classes will be generated)
• Add nearest fallback options if the current theme does include a currently assigned preset

Done

• Theme.json: Add spacing size presets #41527
• Add spacing presets support to style engine #41990
• Spacing presets: add editor UI support #42173
• Fix sizing of custom setting toggle icon (Spacing presets: fix/minor issues noted in initial UI PR #43214)
• Disable presets in global styles if no preset values(Spacing presets: fix/minor issues noted in initial UI PR #43214)
• Plumb through the customSpacingSize value from theme.json to UI and disable custom sizing when false (Spacing presets: Implement disabling of custom space sizes #43216)
• Add spacing presets to Margin controls
  (Mobile spacing issues #40486) are looked at as part of this
• Fix layout of BoxControl when 0 spacing scale steps(Spacing presets: fix/minor issues noted in initial UI PR #43214)
• Add spacing presets to Block Gap controls
• Fix the glitchy spacing visualiser - currently ends up out of sync if changing sizes quickly
• Add some indication to the UI when editing custom sides (eg. group block margins only affect top and bottom) to indicate in linked mode which sides will be affected - Spacing: Optimize & condense unlinked spacing controls #50660
• Add spacing presets option to Spacer block height
• Explore option of easily allowing of editing top/bottom and left/right together - Spacing: Optimize & condense unlinked spacing controls #50660

[eric-michel]

With regards to spacing, I think there are two levels of issues:

1. For margin and padding, there is no way to define a limited, preset list of values at all in theme.json. The current margin and padding controls only allow for direct numeric control of spacing (via units like px, rem, etc). This is in contrast to font size and color palette, which at least allow for defining a limited list of options.
2. If preset values become allowed, should they be unified into a standard naming convention, like gap-1, gap-2, gap-3 etc to improve interoperability? This is the proposal in the issue (Proposal: Standardized block markup, theme.json design tokens, and CSS classes to improve interoperability #38998) that inspired this more narrowly focused one.

Item 1 is probably the biggest missing feature for the way we use Gutenberg. Item 2 is a larger project that I definitely think has merits, but even addressing item 1 would be a huge leap forward.

Just allowing spacing.units to accept an array of preset options similar to font size and then having those options selectable from the margin and padding controls for supported blocks would be amazing. Something like:

"spacing": {
	"units": [
		{
			"slug": "xs",
			"size": "0.25rem",
			"name": "XS"
		},
		{
			"slug": "sm",
			"size": "0.5rem",
			"name": "SM"
		},
		{
			"slug": "md",
			"size": "1rem",
			"name": "MD"
		},
		{
			"slug": "lg",
			"size": "2rem",
			"name": "LG"
		},
		{
			"slug": "xl",
			"size": "4rem",
			"name": "XL"
		},
	]
},

Issue #35306 includes some additional conversation regarding defining preset spacing values.

[cbirdsong]

Summarizing my points in #35306, most of which are mirrored in #38998 and its accompanying blog post:

• Custom spacing values are difficult to keep consistent as a site grows and burdensome for non-technical editors.
• Storing spacing values as inline styles make content less portable since you can never revise your choices systemically.
• There is no good way to deal with these issues as it stands, and adding spacing value presets that work like font sizes would solve these problems in a familiar way.

---

Continuing discussion from #38998, I think the biggest point of debate so far is whether the default¹ scale should use numbers (1, 2, 3) or T-shirt sizes (sm, md, lg).

From @landwire in #38998 (comment):

I had not the time to read all of this thread yet, but I would like to see consistency in the naming of the variants of property values, if at all possible and where it makes sense. I find just numbers 1, 2, 3, 4 etc. too abstract, but prefer the T-shirt sizing system that @justintadlock mentioned here: #38998 (comment)

So using a standard set: xxs, xs, s, m, l, xl, xxl or a subset thereof, if less is needed.

On one hand, I think this makes sense for consistency with font sizes, though I'd suggest sizes smaller/bigger than xs/xl be 2xl, 3xl, 4xl, etc, since that's easier to parse at a glance than xxl, xxxl, xxxxl.

On the other hand, I think that most designs could use more spacing values than the basic 5/7 this supports elegantly.

It also feels like only adding new sizes onto the ends of the scale would make it more difficult to support the kind of system described by @mrwweb in #38998 (comment):

Based on your font-weight example and some of @justintadlock's spacing suggestions, it does seem like a system that allows theme authors to omit/combine certain values on these scales would be very helpful. (Although I also think there's a risk of over-engineering here!) The trick is figuring out how to "merge" points on the scale together so that omitted points are rounded to their nearest defined value, maintaining the relationship between user selected values. I think custom property fallbacks could end up being of huge value for doing this, and I built a proof of concept idea of how standardized classes based on optional custom properties could be used for variable scales.

Sizes smaller/bigger than xs and xl could easily fall back to using those, but that likely wouldn't translate well in practice.

There is also the issue of communicating what the "default" gap would be. In font sizes, it's pretty clear that "medium" is probably the theme's default, though the user can't actually see the word "medium" very easily with the current design and stock font sizes, and resetting to the default is extremely confusing:

Personally, I've implemented this sort of system in ACF blocks using a range slider, which felt appropriate and fits a numeric system better:

It's also worth considering that Bootstrap and Tailwind use numbers. (Tailwind also includes numbers with decimals by default, which I find very weird.)

---

From @landwire in #38998 (comment):

Not sure if we need an explicit none/zero value for gap, margin, padding?

I would say we do. I often add a "seamless" style to the columns block that removes space between child columns, which is useful if you're adding a background color to all of them.

---

From @glendaviesnz in #38998 (comment):

Do you think it will be a requirement of theme authors to enable/disable both options independently, eg. allow users to select either presets, or, absolute, or both?

It's hard for me to imagine a situation where a theme author that would want to disable presets but allow custom values. It doesn't look like it's possible to do that with font sizes right now, and it would probably make sense to be consistent with that.

This should probably be a separate issue, but the editor also needs to get much better at handling custom values in existing content, as right now it's impossible to tell that a custom font size is attached to a block when custom value entry has been disabled. This will definitely be a problem here since all gap values are currently all custom sizes.

Footnotes

1. As with font sizes, theme authors should be able to throw out the default scale and insert whatever fits their needs. I doubt many will, though, since there will be benefits for using the standard sizes. ↩

[eric-michel]

@cbirdsong

Not sure if we need an explicit none/zero value for gap, margin, padding?

I would say we do. I often add a "seamless" style to the columns block that removes space between child columns, which is useful if you're adding a background color to all of them.

I completely agree. I regularly want to set margin to zero on things like two group blocks with background colors when I want to have no gap between them. Or (same as you) want to have no gap between columns in the columns block.

[mrwweb]

@cbirdsong amazing writeup. Thanks for that!

Do you think it will be a requirement of theme authors to enable/disable both options independently, eg. allow users to select either presets, or, absolute, or both?

It's hard for me to imagine a situation where a theme author that would want to disable presets but allow custom values. It doesn't look like it's possible to do that with font sizes right now, and it would probably make sense to be consistent with that.

I agree that following the existing options supported by Font size makes sense since that is the closest existing system to what's proposed here. It should definitely be possible to only use the scale and not enable custom values.

---

The main purposes of adding this feature are:

1. Increase consistency from page to page by making it easier to select consistent spacing settings
2. Maintain editor intent when switching themes and increase content portability
3. Expose spacing values to plugins and core

Notably, the goal is NOT to support a theme's full spacing needs. I think this needs to weigh into how many values are in the standardized spacing scale. While themes might well want more than 5-7 values for spacing in custom CSS, I wonder how valuable it is to go beyond that for block settings.

---

It seems to me that in order for this feature to move forward, the following questions need to be answered. I offer them to hopefully stimulate further conversation!

1. Is a single spacing scale sufficient or do gap/margin/padding/etc. need separate scales?
2. How many points on are on the spacing scale, and can themes go beyond the required points. If so, how? How does that work when switching themes?
3. What naming scheme should the scale use? (Leading contenders: sequential numbers or "t-shirt sizes" i.e. xs, s, m, l, xl)
4. Could scales be derived from a single spacing value and a multiplier or should each point be individually defined?
5. Should there be default values for the spacing provided by core? (If following the path of font size settings, the answer is almost certainly yes)
6. How are the scale values exposed to themes, patterns, and plugins for use? (This is where the issue of the style engine comes in on Improving our saving/rendering of block styles #37495)

---

Finally, I have a question about implementation. Do we need the block settings to be implemented before the scale itself is finalized as a standard? I wonder if it would be better to define the scale and expose it in code one release before any settings are added to allow for a bit more flexibility on the final feature and move this issue forward faster.

[cbirdsong]

3. What naming scheme should the scale use? (Leading contenders: sequential numbers or "t-shirt sizes" i.e. xs, s, m, l, xl)

I would also throw in the sequential numbers variant of 10, 20, 30, which leaves a natural place for additional spacing values to be added.

[eric-michel]

@mrwweb I really like your list of questions and think it's a great place to start. If this were only a discussion of adding preset spacing options, it would be pretty simple - do it like we do font sizes. Full list of options, custom naming and values, WP just generates the classes based on that (has-[name]-font-size just becomes has-[name]-margin or maybe something shorter like m-[name] etc).

With the added wrinkle of standardization of tokens (for at least a limited number of spacing options), we have to balance between flexibility and standardization.

Is a single spacing scale sufficient or do gap/margin/padding/etc. need separate scales?

This is a tough one. A single scale is certainly sufficient for the way we operate. But maybe we should err on the side of greater flexibility for folks who would want it.

It could be that there is a spacing.sizes value that is universal, but gets overridden by spacing.margin.sizes, spacing.padding.sizes, and spacing.gap.sizes. Or alternatively, define a spacing size and optionally allow for multiple values based on property. Something like:

"spacing": {
	"options": [
		{
			"slug": "xs",
			"baseSize": "0.25rem",
			"marginSize": "0.5rem", //optional value, overrides baseSize for margin only
			"name": "XS",
		},
		...
	]
},

How many points on are on the spacing scale, and can themes go beyond the required points. If so, how? How does that work when switching themes?

I think 5 or 6 standard options should be sufficient. But I do think it's really important that themes be able to go beyond the required options to avoid the "bootstrap effect" that @Luehrsen mentioned in the main thread.

In terms of defining those options, simply listing whatever values you want (including both required and your own options) seems the simplest. Let's say the standard sizes are sm, md, lg, xl, and 2x. If I also wanted to have a mdlg option, the following seems intuitive to me:

"spacing": {
	"options": [
		{
			"slug": "md",
			"baseSize": "1rem",
			"name": "MD",
		},
		{
			"slug": "mdlg", //this is a nonstandard option, but gets defined along with the standard ones
			"baseSize": "1.5rem",
			"name": "MDLG",
		},
		...
	]
},

For theme switching, I wonder if we should just do nothing. Maybe we add an alert when activating a theme that uses nonstandard options that warns the user that content from this theme may not be portable to other themes. This allows for flexibility at the expense of portability when desired. Many theme creators will likely stick to the standard set of options. And there will still be enormous value on the plugin side regardless, because the standard options will be available for plugins to take advantage of even when custom options are created by the theme as well.

What naming scheme should the scale use? (Leading contenders: sequential numbers or "t-shirt sizes" i.e. xs, s, m, l, xl)

Originally I was favoring the t-shirt sizing scale, but if we're looking to offer the flexibility of any amount of custom options on top of the standard ones, maybe @cbirdsong's idea of sequential numbers in 10s is the way to go.

Could scales be derived from a single spacing value and a multiplier or should each point be individually defined?

I think each point should be individually-defined for sure. Better to give more flexibility.

Should there be default values for the spacing provided by core? (If following the path of font size settings, the answer is almost certainly yes)

I'd say yes as well. I think following the example of the font size settings is ideal here (except for the added wrinkle of standard tokens).

How are the scale values exposed to themes, patterns, and plugins for use? (This is where the issue of the style engine comes in on #37495)

Perhaps this is overkill, but I'd love to see the generation of both utility classes and custom properties, similar to the way font size classes and custom properties are currently generated.

Something like:

"spacing": {
	"options": [
		{
			"slug": "30",
			"baseSize": "1rem",
			"name": "MD",
		},
		...

would generate:

:root {
	--wp--preset--gap-size--30: 1rem;
}
.m-30 {
	margin: var( --wp--preset--gap-size--30 );
}
.mt-30 {
	margin-top: var( --wp--preset--gap-size--30 );
}
etc etc

.p-30 {
	padding: var( --wp--preset--gap-size--30 );
}
etc etc

Using custom properties would then allow for things like smaller gap values at various viewport sizes (which I think would be beyond the remit of theme.json). For instance, I may want the gap value of 30 to drop to 0.5rem on mobile. In my theme's CSS I can set --wp--preset--gap-size--30 to 0.5rem at my chosen breakpoint, and all of my spacing (margin, padding, and gap) would adjust appropriately. This, of course, assumes that I have not given different values to margin, padding, or gap for size 30.

[cbirdsong]

1. Is a single spacing scale sufficient or do gap/margin/padding/etc. need separate scales?

Thinking about this more, I don't think the difference between these would be easily explainable to users, which would mean that they need to be based on the same scale. For instance, in the case of gap and margin, choosing between the two is often an implementation detail, and if the defined gap and margin values differ then the choices presented to a user would vary by block in a seemingly arbitrary way.

For theme switching, I wonder if we should just do nothing.

This is probably fine, as that's how custom font sizes work.

Perhaps this is overkill, but I'd love to see the generation of both utility classes and custom properties, similar to the way font size classes and custom properties are currently generated.

I'm also not sure utility classes are the best idea considering how quickly they could multiply. A simple .wp-gap-whatever class/token would let theme authors have more flexibility to take the token and use it in a way that fits their design without dictating how. For instance, I often apply what would normally be padding as margin with the column blocks so that a child block can optionally span the full width of the content. Demo: https://codepen.io/cbirdsong/pen/VwymdvO

[eric-michel]

Is a single spacing scale sufficient or do gap/margin/padding/etc. need separate scales?

Thinking about this more, I don't think the difference between these would be easily explainable to users, which would mean that they need to be based on the same scale. For instance, in the case of gap and margin, choosing between the two is often an implementation detail, and if the defined gap and margin values differ then the choices presented to a user would vary by block in a seemingly arbitrary way.

That's a good point. Using a single scale for all spacing would certainly make things simpler all around.

I'm also not sure utility classes are the best idea considering how quickly they could multiply. A simple .wp-gap-whatever class/token would let theme authors have more flexibility to take the token and use it in a way that fits their design without dictating how.

Without utility classes, what are you thoughts on how customizations would be applied? Right now, blocks can have top and bottom margins customized independently (albeit with fully custom units) and top, bottom, left, and right padding customized independently:

My thought is that you'd need a utility class for each of those directions and for each spacing size in order to apply those customizations in a portable way. Or are you thinking it would be handled inline styles and custom properties? Like I could imagine applying a 30 padding left and right and 50 padding top and bottom might output like this:

style="padding-left: var( --wp--preset--gap-size--30 ); padding-right: var( --wp--preset--gap-size--30 ); padding-top: var( --wp--preset--gap-size--50 ); padding-bottom: var( --wp--preset--gap-size--50 );"

Is that what you're thinking?

[cbirdsong]

Hmm, yeah, I'd like no more inline styles than is absolutely necessary, which leaves us with utility classes.

My lack of post-theme.json theme experience is showing – is it possible to disable padding/margin values for individual directions, leaving only a single control for all sides or pair of controls for horizontal/vertical? If so, that could be taken into account and cut down on the number of utility classes generated.

In the case of margin, I think it would be best to encourage a default of layout composition being controlled by the container using gap or margin-based stacks instead of running around adjusting spacing on individual elements.

[eric-michel]

I know from my perspective, having independent control over all 4 directions of both margin and padding is really important.

Our parent theme contains some utility classes for margin and padding that I use all the time since spacing is not currently a feature in Gutenberg. These utility classes allow me to set 5 standard spacing amounts (plus 0) for margin and padding. I can set those spacing amounts for all 4 directions, top/bottom, left/right, or any individual direction.

The total size for these utility classes (including !important flags, which unfortunately is like a third of the overall character count) is only 3.58KB uncompressed. Here they are in their entirety:

.p-0{padding:0 !important}.py-0{padding-top:0 !important;padding-bottom:0 !important}.px-0{padding-left:0 !important;padding-right:0 !important}.pt-0{padding-top:0 !important}.pb-0{padding-bottom:0 !important}.pl-0{padding-left:0 !important}.pr-0{padding-right:0 !important}.m-0{margin:0 !important}.my-0{margin-top:0 !important;margin-bottom:0 !important}.mx-0{margin-left:0 !important;margin-right:0 !important}.mt-0{margin-top:0 !important}.mb-0{margin-bottom:0 !important}.ml-0{margin-left:0 !important}.mr-0{margin-right:0 !important}.p-xs{padding:0.25rem !important}.py-xs{padding-top:0.25rem !important;padding-bottom:0.25rem !important}.px-xs{padding-left:0.25rem !important;padding-right:0.25rem !important}.pt-xs{padding-top:0.25rem !important}.pb-xs{padding-bottom:0.25rem !important}.pl-xs{padding-left:0.25rem !important}.pr-xs{padding-right:0.25rem !important}.m-xs{margin:0.25rem !important}.my-xs{margin-top:0.25rem !important;margin-bottom:0.25rem !important}.mx-xs{margin-left:0.25rem !important;margin-right:0.25rem !important}.mt-xs{margin-top:0.25rem !important}.mb-xs{margin-bottom:0.25rem !important}.ml-xs{margin-left:0.25rem !important}.mr-xs{margin-right:0.25rem !important}.p-sm{padding:0.5rem !important}.py-sm{padding-top:0.5rem !important;padding-bottom:0.5rem !important}.px-sm{padding-left:0.5rem !important;padding-right:0.5rem !important}.pt-sm{padding-top:0.5rem !important}.pb-sm{padding-bottom:0.5rem !important}.pl-sm{padding-left:0.5rem !important}.pr-sm{padding-right:0.5rem !important}.m-sm{margin:0.5rem !important}.my-sm{margin-top:0.5rem !important;margin-bottom:0.5rem !important}.mx-sm{margin-left:0.5rem !important;margin-right:0.5rem !important}.mt-sm{margin-top:0.5rem !important}.mb-sm{margin-bottom:0.5rem !important}.ml-sm{margin-left:0.5rem !important}.mr-sm{margin-right:0.5rem !important}.p-md{padding:1rem !important}.py-md{padding-top:1rem !important;padding-bottom:1rem !important}.px-md{padding-left:1rem !important;padding-right:1rem !important}.pt-md{padding-top:1rem !important}.pb-md{padding-bottom:1rem !important}.pl-md{padding-left:1rem !important}.pr-md{padding-right:1rem !important}.m-md{margin:1rem !important}.my-md{margin-top:1rem !important;margin-bottom:1rem !important}.mx-md{margin-left:1rem !important;margin-right:1rem !important}.mt-md{margin-top:1rem !important}.mb-md{margin-bottom:1rem !important}.ml-md{margin-left:1rem !important}.mr-md{margin-right:1rem !important}.p-lg{padding:2rem !important}.py-lg{padding-top:2rem !important;padding-bottom:2rem !important}.px-lg{padding-left:2rem !important;padding-right:2rem !important}.pt-lg{padding-top:2rem !important}.pb-lg{padding-bottom:2rem !important}.pl-lg{padding-left:2rem !important}.pr-lg{padding-right:2rem !important}.m-lg{margin:2rem !important}.my-lg{margin-top:2rem !important;margin-bottom:2rem !important}.mx-lg{margin-left:2rem !important;margin-right:2rem !important}.mt-lg{margin-top:2rem !important}.mb-lg{margin-bottom:2rem !important}.ml-lg{margin-left:2rem !important}.mr-lg{margin-right:2rem !important}.p-xl{padding:4rem !important}.py-xl{padding-top:4rem !important;padding-bottom:4rem !important}.px-xl{padding-left:4rem !important;padding-right:4rem !important}.pt-xl{padding-top:4rem !important}.pb-xl{padding-bottom:4rem !important}.pl-xl{padding-left:4rem !important}.pr-xl{padding-right:4rem !important}.m-xl{margin:4rem !important}.my-xl{margin-top:4rem !important;margin-bottom:4rem !important}.mx-xl{margin-left:4rem !important;margin-right:4rem !important}.mt-xl{margin-top:4rem !important}.mb-xl{margin-bottom:4rem !important}.ml-xl{margin-left:4rem !important}.mr-xl{margin-right:4rem !important}

Note that this also includes classes like py-md which sets a md padding to top and bottom (the y axis) which would not be needed in WP, reducing the character count. But then again, these are also applying direct amounts (margin-left:2rem for .ml-lg for instance) instead of variables, which in WP tend to be long (like margin-left:var(--wp--preset--gap-size--30) for .ml-30), so that would add to the character count.

I'd love to see fully-independent 4-direction control of padding and margin available directly in the editor. I don't think it would create a particularly onerous amount of CSS in the grand scheme of things.