WordPress Spacing System Generator

WordPress spacing presets

Spacing presets are the named sizes a block theme defines in settings.spacing of its theme.json. The block editor offers them in the padding, margin and block spacing controls, so a site uses a small, consistent set of sizes instead of whatever anyone types.

WordPress turns every preset into a CSS custom property, such as --wp--preset--spacing--50, and blocks store a reference to the preset rather than its value. Change the preset in theme.json and every block that uses it follows.

spacingScale or spacingSizes

spacingScale describes a scale with five settings, and WordPress generates the presets from them. This is WordPress’s own default:

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

• 20 2X-Small: 0.44rem
• 30 X-Small: 0.67rem
• 40 Small: 1rem
• 50 Medium: 1.5rem
• 60 Large: 2.25rem
• 70 X-Large: 3.38rem
• 80 2X-Large: 5.06rem

Medium is written exactly as given; every other size is rounded to two decimals, as WordPress does. With a multiplier below 1, WordPress divides where it would multiply, so 0.5 gives the same scale as 2.

spacingSizes lists every preset yourself: a name, a slug and any CSS size, including clamp(). That is what the Fluid Spacing System writes. If a theme.json has both, WordPress merges them in theme.json version 3, and a spacingSizes preset replaces a generated one with the same slug.

Why slug 50 is Medium

WordPress gives the middle of a spacing scale the slug 50 and steps the other slugs by 10: 40, 30 and 20 below, 60, 70 and 80 above. A scale of up to 10 steps fits between 10 and 100 without renaming anything, and because every slug is a number, the editor can sort the presets by size. With an even number of steps, the extra preset goes above Medium.

Slider or dropdown in Gutenberg

The editor’s spacing control lists None followed by the presets. With 7 or fewer presets it is a range slider that steps through them by name. With more, the slider would get crowded, so the editor switches to a dropdown that also offers Default. A single preset gives the slider nothing to choose between, so the editor shows its custom value field instead.

The count includes WordPress’s default presets whenever they are switched on, which is why defaultSpacingSizes can turn a slider into a dropdown.

Fluid spacing with clamp()

A fluid preset grows in a straight line between two viewport widths and holds its size outside them. The tool sets Medium’s size at the minimum and maximum viewport, multiplies by the scale ratio for each step, and writes each preset as clamp(minimum, preferred, maximum), with the preferred value in rem plus vw. The default Medium preset is:

clamp(1rem, 0.8571rem + 0.7143vw, 1.5rem)

It is 16 px at 320 px and narrower, 19.2 px at 768 px, and 24 px at 1440 px and wider. The rem values assume the root font size set in the tool, 16 px by default; the preview and the readouts use the same rounded numbers as the copied CSS.

Font sizes can follow the same approach: CSS Clamp / Fluid Typography Generator writes a fluid type scale as CSS or as theme.json font size presets.

What defaultSpacingSizes does

WordPress ships its own seven spacing presets, slugs 20 to 80. In theme.json version 3, defaultSpacingSizes decides whether the editor offers them:

• true, the default when it’s left out: WordPress’s presets stay, and a theme preset with one of their slugs is dropped. Presets with other slugs appear alongside them.
• false: the editor offers only the theme’s presets. This is the usual choice when your scale replaces WordPress’s.

Either way, the page’s CSS still defines the default variables for slugs your presets don’t use. When WordPress upgrades a version 2 theme.json that has spacing presets, it sets defaultSpacingSizes to false.

Using the spacing variables in CSS

WordPress adds the preset variables to every page, so your theme’s CSS can use them directly:

.section {
  padding: var(--wp--preset--spacing--50);
}

In theme.json styles and in block markup, refer to a preset with the var:preset form. WordPress writes it out as the CSS variable:

"padding": {
  "top": "var:preset|spacing|50"
}

What importing theme.json does

Import reads only settings.spacing from pasted text or a local file, in your browser. Nothing is uploaded or stored, and nothing else in the file is read.

A spacingScale loads into Native WordPress Scale exactly as written; missing settings are filled from WordPress’s defaults, as WordPress does. spacingSizes are kept exactly as written and copied back unchanged: the tool doesn’t guess generator settings from arbitrary CSS. Only when its fluid generator reproduces every preset character for character are those settings restored for editing. Values it can’t measure, such as var() or em sizes, are kept but shown without a bar.

Importing never changes your file. The output is a fragment to merge into theme.json yourself. To build or validate the complete file, use WordPress theme.json Generator.