Confessions of a theme developer who has read the theme review guidelines more times than his own wedding vows. Well — except that one time. This is about that one time.
The email
A few weeks ago, I submitted a block theme to WordPress.org.
Some context: I've been building WordPress things for about ten years. Themes on ThemeForest. Plugins on WordPress.org. I've watched this platform grow, argued with it, made a living from it, and honestly — loved it. Ten years is long enough that you stop reading the rulebook before every submission. You are the rulebook. Or so you think.
So when I built this block theme, I did what any veteran does: I poured a decade of accumulated solutions into it. The patterns that worked. The options users always ask for. The little conveniences I'd refined across dozens of client projects. My greatest hits album, remastered for the block era.
Then the reviewer's feedback email arrived.
I'm not going to pretend I read it calmly. I read it the way you read a text that starts with "we need to talk." Item after item, the things I was proudest of — the experience — flagged as things a theme is no longer allowed to do. Not because they were broken. Not because they hurt users. Because they were functionality, and functionality belongs to plugins now.
Ten years of knowing WordPress, and WordPress looked at my work and said: and who are you, exactly?
That sting is what this post is about. Because after the ego bruise faded, I realized my rejection email wasn't really about my theme. It was a symptom of something bigger.
The setup
Ten-ish years ago, building a WordPress theme felt like being handed a Swiss Army knife and a shrug: "Go make something people love."
And we did. Sure, the ecosystem got messy — themes that bundled seventeen sliders, a page builder, a coffee machine, and somehow also your uncle's SEO plugin. WordPress.org looked at this chaos and said, reasonably: "Themes should handle presentation. Plugins should handle functionality."
Great principle. I genuinely agree with it. Write it on a whiteboard and I'll applaud.
Then they enforced it like a homeowners' association that measures your grass with a laser.
The punchline nobody laughs at
Here's the beautiful irony of the modern block theme era, and the exact trap my rejected theme walked into:
The rules exist to stop themes from doing plugin things. The result? Every serious block theme now ships with a companion plugin.
Theme wants custom blocks? Plugin. Theme wants a real settings panel? Plugin. Theme wants to do literally anything interesting beyond arranging theme.json tokens like feng shui? Believe it or not — plugin.
Which means my path to compliance is clear: take the features the reviewer flagged, move them into a companion plugin, and resubmit. Same code. Same user experience. Same dependency. Different folder. The review process will smile and wave me through.
So the end user, the person all of this was supposedly for, goes from:
Before: Install theme → done
to:
Now: Install theme
→ "This theme recommends Theme-Name-Core"
→ Install companion plugin
→ "For best results, install Theme-Name-Blocks"
→ Install block library
→ (optional) cry
We didn't kill lock-in. We just gave it a costume change. Delete the companion plugin today and your site collapses exactly like deleting a classic theme did in 2015 — except now the wreckage is distributed across three separate things in your admin panel. Progress! The dependency is the same; it just has better paperwork.
Gutenberg: the rocket we built and then parked
This is the part that actually stings as a developer — more than the rejection email did.
Gutenberg is arguably the most ambitious, resource-hungry, tear-soaked project in WordPress history. And the Block API underneath it is genuinely powerful — custom blocks, variations, InnerBlocks, server-side rendering, the Interactivity API. It's a rocket.
But if you're a theme developer on the official repo, most of that rocket is behind a velvet rope. The rules that govern the repo effectively say: you may look at the rocket, you may describe the rocket in JSON, but flying the rocket is a plugin's job.
Here's what a decade in this ecosystem makes painfully visible: the most powerful tooling WordPress ever built is fully usable... everywhere except by the themes in WordPress's own directory. Commercial themes outside the repo? They use everything. Companion plugins? They use everything. Repo themes? Here's your theme.json, champ. Make the spacing scale sing.
The ceiling imposed by the rules sits lower than the ceiling of what developers can actually build. My rejection email was just me bumping my head on it.
"But the users love it!" — do they, though?
Look at what people actually install. The most popular themes on the planet are still, overwhelmingly, classic themes — Astra, GeneratePress, OceanWP, the usual suspects, with millions of active installs between them. Users vote with their clicks, and the vote so far reads less "revolution" and more "polite golf clap."
And honestly? Fair. From an end user's perspective, block themes traded a familiar problem (theme lock-in) for an unfamiliar one (theme + plugin + block library lock-in), added a new editor to learn, and delivered... slightly cleaner HTML. That's not nothing! But it's not a reason to switch, either.
The theme was supposed to get simpler. Instead it got legally simpler and practically more complicated.
The uncomfortable "they might be right" section
Now, because I'm a solutions person and not just a guy yelling at CMS-shaped clouds — and because ten years here has taught me that WordPress usually plays a longer game than its critics do:
The direction is probably correct. Separating presentation from functionality is the right long-term architecture. Portable content, swappable themes, no more "change theme, lose everything" horror stories — that's a future worth wanting. If I'm honest, some of what my reviewer flagged was stuff that, in an ideal world, shouldn't live in a theme.
The problem isn't the destination. It's the sequencing. The rules got enforced before core was capable enough to make rule-following painless. If the Site Editor and Block API could already do 95% of what theme developers want, nobody would be jumping fences — there'd be nothing on the other side. Instead, the fence went up first, and the good stuff is still visibly on the other side of it.
Rules should trail capability. Here, they lapped it.
What I'd actually want (the boring, practical wishlist)
- Let repo themes use more of the Block API. If WordPress built it, WordPress themes should get to use it. Radical, I know.
- First-class support for theme-scoped blocks — blocks that live in the theme, degrade gracefully when the theme changes, and don't require a plugin chaperone.
- Judge outcomes, not architecture. Does deactivating the theme leave content intact? Great, approve it. Stop measuring the grass.
- Watch the market signal. If commercial themes outside the repo keep winning on quality and revenue for another few years, that's not developers being stubborn. That's the market grading the rules.
Closing
I don't think WordPress is wrong about where it's going. I think it confiscated everyone's car before the trains were running.
As for my theme — yes, I'm refactoring it. The flagged features are moving into a companion plugin, exactly as the rules intend and exactly as the irony demands. Ten years in, WordPress can still make me feel like a junior dev reading guidelines at 2 AM.
Maybe that's not entirely a bad thing. But somewhere in a WordPress.org inbox is a reviewer who has no idea their template email sent a grown developer through all five stages of grief — and then straight to his text editor to write this post.
Three repos to comply with a rule about keeping things in one place. If that's not the most WordPress thing ever, I don't know what is. 🙃
Fellow theme devs — have you gotten The Email? How are you handling the theme/plugin split: full block theme, hybrid, or hiding in classic-theme land with the other millions of installs? Tell me in the comments.
Top comments (0)