WordPress Themes Are Architectural Debt

Mangesh Yadav — Mon, 11 May 2026 13:40:00 +0000

I have been building websites since the early 2000s.

Over the years I have worked through table layouts, inline styles, early CSS frameworks, jQuery-heavy themes, page builders, shortcode ecosystems… all the way to Gutenberg.

And honestly, Gutenberg felt like a clean slate for WordPress.

For the first time, WordPress did not feel like a collection of templates stitched together with plugins. Blocks made sense. Reusable components made sense. Structured editing made sense.

It finally felt like WordPress could evolve into a proper publishing system.

But while building real projects with Gutenberg, I kept running into the same issue again and again.

The blocks were modern.

But the architecture around them was still fighting the past.

Themes were still controlling too much:

layouts
spacing
typography
rendering behavior
CSS overrides
responsive logic
plugin styling

The deeper I built with Gutenberg, the more I realized something important:

The problem was not Gutenberg.

The problem was that WordPress still had no governing contract between themes, blocks, plugins, and layouts.

Every plugin shipped its own styles. Every theme shipped its own assumptions. Every builder tried to control rendering differently.

And slowly every project started drifting into chaos.

I started calling this design entropy.

Design entropy is what happens when every part of the system starts making its own design decisions without governance.

At first the website looks clean.

Then:

another plugin gets added
another developer touches the project
custom CSS starts piling up
different block libraries get mixed in
WooCommerce gets customized

And eventually consistency disappears.

Buttons stop matching. Typography drifts. Spacing becomes random. Performance becomes unpredictable.

The more I worked on projects, the more I kept thinking about this system.

Not for weeks.

For years.

That thought eventually became wpTruss.

We Did Not Start With a Big Vision

Initially we simply started building Gutenberg blocks.

Then we realized every block repeated the same design logic again and again:

colors
spacing
typography
shadows
sizing

Everything was scattered.

So we moved towards design tokens.

Initially it was just a JSON-based token system. Later it evolved into a full token registry where blocks consumed centralized design values instead of making their own styling decisions.

That changed everything.

Consistency improved immediately.

Then Came The Bigger Realization

Almost everything on a website could be treated as blocks:

headers
footers
layouts
reusable structures
entire page sections

So instead of themes controlling everything permanently, we started building a structure system around blocks themselves.

And honestly, that was the turning point.

Because once structure itself became governed through blocks, themes stopped being the center of the architecture.

They became containers.

Disposable containers.

Themes Became The Wrong Abstraction Layer

I don’t think themes are “bad”.

But modern WordPress systems ask themes to handle responsibilities they were never designed to own.

Today themes are expected to manage:

design systems
layouts
performance
responsiveness
structure
plugin compatibility
rendering consistency

That is too much responsibility for one layer.

And most performance problems today are actually architecture problems disguised as optimization problems.

Most developers optimize pages.

But the real issue is usually architectural fragmentation underneath the page itself.

What wpTruss Is Trying To Solve

That is what wpTruss is trying to solve.

Not by replacing WordPress.

Not by replacing Gutenberg.

But by introducing governance:

design tokens
governed blocks
shared structure systems
reusable layouts
centralized rendering logic

The future of WordPress, at least to me, feels less like uncontrolled customization and more like governed composition.

Gutenberg opened that door.

wpTruss is simply an attempt to continue walking in that direction.

Have you experienced similar issues while building large WordPress projects with themes and plugins?

Do you think themes still make sense as the center of WordPress architecture?

How are you currently handling design consistency and structural governance across Gutenberg projects?

Would love to hear how other developers are approaching this.

View complete article here: WordPress Themes Are Architectural Debt

DEV Community: Mangesh Yadav

WordPress Themes Are Architectural Debt

We Did Not Start With a Big Vision

Then Came The Bigger Realization

Themes Became The Wrong Abstraction Layer

What wpTruss Is Trying To Solve