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.
{
"settings": {
"color": {
"palette": [
{
"slug": "primary",
"color": "#1a4548",
"name": "Primary Green"
},
{
"slug": "light-gray",
"color": "#f0f0f0",
"name": "Light Gray"
}
]
}
}
}Generated CSS:
body {
--wp--preset--color--primary: <a href='/?search=%231a4548' class='obsidian-tag'>#1a4548</a>;
--wp--preset--color--light-gray: <a href='/?search=%23f0f0f0' class='obsidian-tag'>#f0f0f0</a>;
}How to use it in 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.
"settings": {
"typography": {
"fontSizes": [
{
"slug": "small",
"size": "0.9rem",
"name": "Small"
},
{
"slug": "h1",
"size": "clamp(2rem, 5vw, 4rem)",
"name": "Heading 1"
}
]
}
}The Quirks:
- Slug
smallbecomes--wp--preset--font-size--small. - Slug
h1becomes--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).
"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).
"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 Part 3: Global Styles & Specificity.