---
tags:
  - wordpress
  - fse
  - typography
  - colors
  - presets
title: The Preset Engine: Registration and Sanitization Quirks
---

# The Preset Engine: Registration and Sanitization Quirks

In `theme.json`, the **Settings** section is where you register your design tokens (colors, fonts, gradients, shadows, spacing). WordPress takes these raw values and generates CSS Custom Properties (Variables) for you.

However, WordPress applies a strict **sanitization process** to the names (slugs) of these presets. If you don't understand this process, you will try to use a variable that doesn't exist, leading to broken styles.

## 1. The Variable Generation Formula

The general formula for a generated variable is:
`--wp--preset--{category}--{slug}`

### The Sanitization Trap (The "Kebab-Case" Rule)
WordPress converts your `slug` to kebab-case (lowercase, separated by hyphens) and removes invalid characters.

**Crucial Example:**
If you register a font size with the slug `h2`, WordPress sees a number inside a string and hyphenates it.
*   **Input Slug:** `h2`
*   **Output Variable:** `var(--wp--preset--font-size--h-2)`  <-- Notice the dash between h and 2.
*   **Wrong Guess:** `var(--wp--preset--font-size--h2)`

## 2. Color Palette Registration

Define your brand colors under `settings.color.palette`.

```json
{
    "settings": {
        "color": {
            "palette": [
                {
                    "slug": "primary",
                    "color": "#1a4548",
                    "name": "Primary Green"
                },
                {
                    "slug": "light-gray",
                    "color": "#f0f0f0",
                    "name": "Light Gray"
                }
            ]
        }
    }
}
```

**Generated CSS:**
```css
body {
    --wp--preset--color--primary: #1a4548;
    --wp--preset--color--light-gray: #f0f0f0;
}
```

**How to use it in CSS:**
```css
.my-button {
    background-color: var(--wp--preset--color--primary);
}
```

## 3. Typography and Fluid Sizing

You can define fixed sizes or use `clamp()` for fluid typography.

```json
"settings": {
    "typography": {
        "fontSizes": [
            {
                "slug": "small",
                "size": "0.9rem",
                "name": "Small"
            },
            {
                "slug": "h1",
                "size": "clamp(2rem, 5vw, 4rem)", 
                "name": "Heading 1"
            }
        ]
    }
}
```

**The Quirks:**
1.  **Slug `small`** becomes `--wp--preset--font-size--small`.
2.  **Slug `h1`** becomes `--wp--preset--font-size--h-1`. (Again, the number sanitization).

## 4. Spacing Scale

By default, WordPress provides a spacing scale. You should override this to match your design system's grid (e.g., a 4px or 8px grid).

```json
"settings": {
    "spacing": {
        "spacingScale": {
            "operator": "*",
            "increment": 24,
            "steps": 0,
            "mediumStep": 1.5,
            "unit": "px"
        },
        "spacingSizes": [
            { "slug": "10", "size": "1rem", "name": "Step 1" },
            { "slug": "20", "size": "2rem", "name": "Step 2" },
            { "slug": "30", "size": "clamp(2rem, 5vw, 5rem)", "name": "Step 3" }
        ]
    }
}
```

**Generated Variables:**
*   `--wp--preset--spacing--10`
*   `--wp--preset--spacing--20`
*   `--wp--preset--spacing--30`

**Note:** Unlike `font-size`, spacing slugs often handle numbers better if they are pure digits, but always check the browser Inspector to be sure.

## 5. Disabling Core Presets

Often, you want to prevent users from using the default WordPress colors (the "Default" palette).

```json
"settings": {
    "color": {
        "defaultPalette": false,
        "palette": [ ... ]
    },
    "typography": {
        "defaultFontSizes": false
    }
}
```

## 6. Next Steps

Now that you have your variables registered, you need to apply them to HTML elements globally.

Proceed to [[wordpress-fse-03-global-styles|Part 3: Global Styles & Specificity]].