Mastering theme.json: You might not need CSS

theme.json: A Different Way to Write WordPress Styles

WordPress's theme.json file aims to make theme styling more modular and scalable. It consolidates all global styles, including variations, into a single structured file. Because JSON is easily consumable by JavaScript, it also enables loading only the styles you need, exactly when you need them.

The trade-off is a complete shift in mental model. Instead of writing selectors, you work with a set of objects just to target an element. CSS-like properties appear in the JSON, but they must be camelCased to fit JavaScript conventions. And because feature configuration is mixed directly into the styles, the clear separation between settings and presentation that plain CSS provides is lost.

To be fair, abstracting CSS into JSON has real benefits for the specific use case of theming CMS templates and components. But after years of "CSS-in-JS is the way" hype, the approach is less compelling. Plain CSS remains perfectly capable, whether it lives in the required style.css file or in another generated stylesheet. The catch is that relying solely on CSS means missing out on WordPress features that specifically require styles to be written in theme.json—such as style variations that users can toggle directly from the WordPress admin.

Justin's work on the subject is worth reviewing for a thorough explanation and illustration of CSS-in-WordPress. The complete block theme guide and the theme.json terminology glossary are solid starting points. For deeper dives, the analysis of how WordPress generates classes from JSON and the global styles reference tables serve as practical cheat sheets.