theme.json is the real styling API
Full Site Editing lives or dies on theme.json. A tour of the settings that actually matter and the mistakes that leak CSS everywhere.
theme.json is where a modern WordPress theme declares its design system. Get it right and blocks style themselves; get it wrong and you fight specificity wars in a style.css nobody wants to touch.
Settings gate the UI
The settings key decides which controls users even see. Turn off custom colors and padding you don't want, expose the palette you do, and the editor UI matches your design system automatically.
{
"version": 3,
"settings": {
"color": { "custom": false, "palette": [
{ "slug": "brand", "color": "#4f46e5", "name": "Brand" }
] },
"spacing": { "customSpacingSize": false, "units": ["rem"] }
}
}Styles cascade through CSS variables
Everything under styles compiles to CSS custom properties with a --wp--preset prefix. Reference those variables in your own CSS instead of hard-coding hex values, and a single palette edit repaints the whole site.
Common leaks
- Hard-coded colors in block CSS that ignore the palette — theme switches won't reach them.
- Enabling custom spacing then complaining about inconsistent margins.
- Forgetting version 3, so newer settings are silently ignored.
Treat theme.json as the contract between your design and the editor. When it's the source of truth, the CSS you write shrinks to almost nothing.