How to style block themes without using JSON

[bph]

Discussed in https://github.com/WordPress/developer-blog-content/discussions/327

^{Originally posted by justintadlock October 30, 2024} There's a lot of confusion around the theming community that I've observed about the necessity of using JSON for styling block themes. There are many good reasons to utilize JSON methods of styling, as described in Mastering theme.json: You might not need CSS. But what and how much you style via JSON is entirely opt in.

This topic proposes:

• Discussing reasons why developers may opt out of JSON (theme.json, global styles, block styles, etc.) and rely on CSS/SCSS instead.
• It will cover the methods for doing this that work best with the block editor (e.g., specificity, selectors in CSS and enqueuing).
• Best practices for performance (e.g., enqueueing block styles vs. giant stylesheets).

There are developers out there who much prefer their own styling systems, and that's an audience that we're not talking too enough when discussing block themes. The goal is still to get them to opt into using the standard tools, but there is more than one way to crack an egg (so to speak).

The primary audience for this article would be developers building bespoke sites where they are not using the Site Editor or giving their clients access to it. For those cases, there are no absolute needs for JSON integration. And, frankly, the JSON method is not everyone's cup of tea, especially when you're almost always doing both JSON and CSS in a theming project (it can be tough to track where things are styled when they're split).

It is worth noting that this is specifically talking about styles rather than settings, which can both be handled via JSON. But the topics are related because the folks most likely to do this would also want to lock down specific design tools in the interface and rely much more heavily on classes (e.g., block style variations). Something to mull over anyway. Regardless, the primary pain point that I've seen is around styles in JSON and not settings.

[troychaplin]

Would love to do a 1st or 2nd review on this one and continue learning more about block themes

[marybaum]

@justintadlock are you in a position to work on this, or does it now need a writer?

[justintadlock]

I have a partial draft here that I'll be working on: https://docs.google.com/document/d/1LZcO7i88rYe_P5rau7GLCc_CAw_OgN4WoO8k6DaR3jQ/edit?usp=sharing

[troychaplin]

@justintadlock tag me when ready for a review, easier for me to make time for that in the next couple week than it is to write a full piece.

[justintadlock]

This is ready for review: https://docs.google.com/document/d/1LZcO7i88rYe_P5rau7GLCc_CAw_OgN4WoO8k6DaR3jQ/edit?usp=sharing

[troychaplin]

I should be able to review this tonight

[troychaplin]

This is ready for review: https://docs.google.com/document/d/1LZcO7i88rYe_P5rau7GLCc_CAw_OgN4WoO8k6DaR3jQ/edit?usp=sharing

I reviewed this, I actually read it twice! It’s a great article, and I don’t have any direct feedback. But I do have a question that might be worth touching on, depending on how deep you want to go:

Some themes offer style variations that let users switch between different palettes, fonts, and other design options. What are the implications of using block stylesheets in that context? For example, would those stylesheets apply consistently across all variations, or could they conflict with or override the intended styles of a particular variation?

Just curious if that’s something worth exploring in this piece, or maybe a follow-up.

[justintadlock]

Thanks, @troychaplin!

Style variations would work the same way as theme.json in this case. You could still use settings but not styles. Depending on how you've put together your design system, that may be all that's needed. For example, you could define a different color palette via settings.color.palette.

But I also think that the audience for this post is probably naturally opting out of using some of the theme.json-enabled features (like style variations) when going this route.

It's certainly worth exploring in more depth, perhaps in a followup piece. Whenever I put together my design system article/series, one of the things I plan to do is explore effectively using style variations. I actually think there's some overlap with this question (more around the architecture of creating a design system, which could be applied via stylesheets or JSON).

[bph]

I just had a couple of suggestions and a comment. It should be ready to publish.

[github-actions[bot]]

Pre-publishing checklist

• [x] Post Title and subheaders in sentence case
• [x] Are Category or Categories selected?
• [x] Are Tags identifies?
• [x] Is there an explicit Excerpt?
• [x] Are all images files uploaded to the media library
• [x] Do all images have an alt-text?
• [x] For TOC us the Pattern under Developer Blog > Table of contents
• [x] Assign or upload a featured image
• [x] Props added? (See Guidelines)
• [ ] add copy for a social post as comment to this issue (example) 🙌 Publish! 📗

Post-publishing checklist

• [ ] add Props for reviews to #props channel in WP Slack (Example) (use Slack handles)
• [ ] Add the label "post to social" to the issue
• [ ] close the issue with a comment to link to the published post
• [ ] close the accompanying discussion with the link to the published post.

[justintadlock]

Thanks, @bph!

[justintadlock]

Published! https://developer.wordpress.org/news/2025/07/you-dont-need-theme-json-for-block-theme-styles/