---
tags:
  - wordpress
  - fse
  - theme.json
  - spacing
  - variables
title: Understanding Spacing Presets vs. Raw Values in theme.json
---

# Understanding Spacing Presets vs. Raw Values in theme.json

In WordPress FSE, spacing (padding, margin, blockGap) is handled by a "Scale" system. Unlike `settings.custom`, spacing variables are strictly tied to the **`settings.spacing.spacingSizes`** array.

## 1. The Mapping Logic

When you define a spacing size, WordPress generates a CSS variable based on the `slug`. 

**Syntax Formula:**
`--wp--preset--spacing--{slug}`

### Example Configuration

```json
{
    "version": 3,
    "settings": {
        "spacing": {
            "spacingSizes": [
                { "name": "Small", "slug": "20", "size": "1.5rem" },
                { "name": "Medium", "slug": "40", "size": "2.5rem" },
                { "name": "Large", "slug": "60", "size": "4rem" }
            ]
        }
    }
}
```

## 2. Generated CSS Output

WordPress automatically registers these in the `:root` or `body` of both the frontend and the editor:

```css
:root {
    --wp--preset--spacing--20: 1.5rem;
    --wp--preset--spacing--40: 2.5rem;
    --wp--preset--spacing--60: 4rem;
}
```

## 3. Usage: Preset vs. Raw

You have two ways to apply spacing in the `styles` section of your `theme.json`.

### A. Using the Preset (Recommended)
This keeps your design locked to your defined scale. If you update the "40" slug in settings, every block using it updates automatically.

```json
"core/group": {
    "spacing": {
        "padding": { 
            "top": "var(--wp--preset--spacing--40)", 
            "bottom": "var(--wp--preset--spacing--40)" 
        }
    }
}
```

### B. Using Raw Values (The "Wild West")
You can bypass the scale entirely by passing a direct CSS value (px, rem, em). This is useful for one-off layouts that don't fit your standard scale.

```json
"core/group": {
    "spacing": {
        "padding": { 
            "top": "100px", 
            "bottom": "5vh" 
        }
    }
}
```

## 4. The `spacingScale` Gotcha

If you define a `spacingScale` (e.g., `"steps": 5`) but also provide a manual `spacingSizes` array:
1. **Manual wins:** WordPress will only generate variables for the slugs you explicitly listed in the array.
2. **Missing Slugs:** Referencing a variable like `--wp--preset--spacing--50` will fail if "50" isn't in your manual list, even if your scale says it should exist.

## 5. Summary Table

| Method | Syntax | Pros | Cons |
| :--- | :--- | :--- | :--- |
| **Preset Variable** | `var(--wp--preset--spacing--40)` | Scalable, centralized, theme-aware. | Fails if slug is missing in settings. |
| **Raw Value** | `2.5rem` or `40px` | Fast, works anywhere, no setup. | Harder to maintain; bypasses global design rules. |

---

Would you like me to update your actual `theme.json` with a more complete 10-step spacing scale so you have more presets to choose from?