Introduction of presets across padding, margin and block gap

WordPress 6.1 introduces preset values for padding, margin and blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. gap. With those the editor implements consistent spacing of blocks and nested blocks out of the box.

The problem

The block editor design tools allowed users only to add custom values for the spacing around block content, eg. padding, margin, or gap.

Dimensions window for padding, margin and block spacing

This means that theme and pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the Plugin Directory or can be cost-based plugin from a third-party authors had no ability to either limit users to a fixed list of spacing options, or to easily change spacing across all of a site’s content if custom spaces have been set on some blocks.

The solution: spacingScale object

theme.json has been extended to include a spacing sizes preset option, similar to the existing font size presets. By default, the editor will generate a range of seven preset sizes that are shared across padding, margin and block gap.

This range is auto-generated from a spacingScale object in the theme.json settings section:

"spacing": {
	"spacingScale": {
		"operator": "*",
		"increment": 1.5,
		"steps": 7,
		"mediumStep": 1.5,
		"unit": "rem"

In the above case, the three steps on either side of the medium step of 1.5rem are generated using a multiplier of 1.5, which results in the following array of spacingSizes:

  {name: '1', slug: '20', size: '0.44rem'},
  {name: '2', slug: '30', size: '0.67rem'},
  {name: '3', slug: '40', size: '1rem'},
  {name: '4', slug: '50', size: '1.5rem'},
  {name: '5', slug: '60', size: '2.25rem'},
  {name: '6', slug: '70', size: '3.38rem'},
  {name: '7', slug: '80', size: '5.06rem'},

It is possible to generate as many steps as needed, and also to use a + operator instead of * to generate these. If a theme has a spacing scale that can’t be auto-generated, then it is possible to include a static array of values in theme.json settings.spacing.spacingSizes.

The spacing sizes are converted to CSSCSS Cascading Style Sheets. properties in the following format:

--wp--preset--spacing--20: 0.44rem;
--wp--preset--spacing--30: 0.67rem;
--wp--preset--spacing--40: 1rem;
--wp--preset--spacing--50: 1.5rem;
--wp--preset--spacing--60: 2.25rem;
--wp--preset--spacing--70: 3.38rem;
--wp--preset--spacing--80: 5.06rem;

Enable fallbacks on Theme switch

There are three reasons for the choice of slugs in the 10,20,30 format:

  1. It is much easier to sort the sizes from smallest to highest, than if the likes of t-shirt sizes were used
  2. For themes that wish to insert additional values between the CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. ones, e.g. a value between Medium and Large, it is easy to do so with a slug of 55
  3. Allow for cross-theme/site compatibility of content if a theme does not support a spacing preset slug in existing content, e.g., a pattern from the pattern library. Numeric values enable a fall back to the nearest match in the current theme. This is also the reason the spacing sizes are generated on either side of Medium. Having a known Medium slug of 50 can hopefully make these fallbacks as accurate as possible.

In the editor UIUI User interface spacing options default to providing the preset option with a toggle to switch back to custom values:

Spacing presets UI

Disable Spacing Presets

  • Disable the spacing presets option by adding the value 0 to settings.spacing.spacingScale.steps in theme.json.
  • Disable the custom spacing sizes by setting settings.spacing.customSpacingSize to false.

Documentation of all theme.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. settings & styles:

How to Guide: Global Settings & Styles (Theme.json)
Theme.json Reference (v2)

Background information

Finalizing the details around these spacing presets has involved a lot of discussion with both theme authors and Core contributorsCore Contributors Core contributors are those who have worked on a release of WordPress, by creating the functions or finding and patching bugs. These contributions are done through Trac. These discussions can be found at the links:

Props to: @glendaviesnz for writing, @webcommsat and @bph for reviewing.

#6-1, #dev-notes, #dev-notes-6-1, #gutenberg