DEV Community: Mangesh Yadav

What wpTruss Installs on Every Site and Why

Mangesh Yadav — Tue, 09 Jun 2026 21:23:49 +0000

For a long time, building a website with WordPress meant making a lot of small choices that were hard to change later. If you wanted to change a color or a font size, you often had to look through thousands of lines of code. This is because most WordPress themes keep their design rules inside their own files. When you change your theme, you lose your design rules. When you hire a new developer, they might write code that does not match what the first developer did. This creates what many experts call architectural debt. It is like building a house where the paint is mixed into the concrete. You cannot change the color without breaking the wall.

The wpTruss system changes this by moving the design rules out of the theme and into a central brain. This brain is a plugin. The most important part of this brain is a list of 141 design tokens. These tokens are like a master set of rules for how your website should look. In this article, we will look at what these 141 tokens are and why they are the key to a better way of building websites.

What is a Design Token
Before we look at the specific list, we need to understand what a design token is. In simple terms, a design token is a name for a design choice. For example, instead of saying a button is blue, we give it a name like primary color. In the code, this looks like a CSS custom property. It might look like var(–wpt-color-primary).

The reason we do this is for consistency. If every part of your website uses the name primary color, you only have to change the definition of that name in one place to update the whole site. If you decide that blue should now be purple, you change it once in the admin panel. Every block, every heading, and every button updates immediately. You do not have to hunt for hex codes or write new CSS. This is why wpTruss installs 141 of these tokens on every site.

The Problem with the Snowflake Site
Most agency owners know the pain of the snowflake site. This is a site where every page was built as a unique item. There are no shared rules. One page uses a 20 pixel margin while another uses 15 pixels. One developer used a specific shade of gray for text, but another developer used a slightly different one. Over time, the site starts to look messy.

When you have 141 tokens installed by default, you stop building snowflakes. You start building a system. These tokens cover every visual detail that matters. By having a fixed list of 141 tokens, wpTruss ensures that every developer on your team is using the same vocabulary. They are not guessing which font size to use. They are choosing from the tokens that are already there.

The Breakdown of the 141 Tokens
The 141 tokens are not random. They are organized into groups that cover the entire visual language of a brand. Let us look at these groups in detail.

The Color System
Color is usually the first thing people think about in design, but wpTruss goes much deeper than just picking a brand color. The color system includes several sub-groups.

First, there are the Canvas tokens. These control the background of the page itself. There is a default background and an alternate background. This is useful for making sidebars or sections that stand out from the main page.

Next are the Brand colors. These are the primary, secondary, and accent colors. But we also include tokens for dark, light, surface, muted, and border colors. Surface colors are very important. They are the background colors for cards, panels, and sections. By having a specific surface token, you can change the look of every card on your site by changing one setting.

We also include Status colors. These are colors for success, danger, warning, and info. If a user fills out a form correctly, the success color shows up. If there is an error, the danger color shows up. By making these tokens, we ensure that every error message on the site looks the same.

Finally, there are Accessibility and Text colors. This includes specific tokens for text on primary backgrounds versus text on dark backgrounds. It even includes the color of the focus ring that shows up when a user clicks through the site using a keyboard. This makes sure your site is easy to use for everyone.

The Typography System
Typography is more than just picking a font. The 141 tokens include rules for three different font families: headings, body text, and monospace text for code.

But the tokens also control sizes. There are 11 different font size tokens. They range from very small text for captions to large display text for hero headlines. We use names like xs, sm, base, lg, and up to 6xl. This means you do not have to remember if a heading is 32 pixels or 36 pixels. You just use the 4xl token.

We also have tokens for font weights, like light, regular, medium, and bold. There are tokens for line height, which is the space between lines of text. We even have tokens for letter spacing, which is the space between letters. All of these details are locked into the token system.

The Spacing System
One of the biggest reasons websites look messy is inconsistent spacing. If the gap between a title and a paragraph is different on every page, the site feels unprofessional. wpTruss installs 8 specific spacing tokens. They go from xs to 4xl.

These tokens are used for padding, which is space inside an element, and margins, which are spaces between elements. Because these are tokens, the spatial rhythm of the site is built-in. If you want more space across the whole site, you can adjust the spacing tokens in the admin panel, and the whole site will breathe better instantly.

Layout and Navigation
The list includes tokens for layout, such as the width of the main content area. There are tokens for narrow, default, and wide containers. This ensures that your content never gets too wide to read easily.

There are also 10 tokens dedicated just to navigation. These control the header height, the header background, and the footer colors. They also control how links look when you hover over them in the menu. Usually, these settings are hidden deep in theme options. In wpTruss, they are standard tokens that any block can see and use.

Borders, Radius, and Shadows
To make a site feel modern, you need control over corners and depth. The system includes 6 tokens for border radius. This controls how rounded the corners of your buttons and cards are. You can go from no radius (sharp corners) to full radius (pill shapes).

There are also tokens for shadows and elevation. Shadows give the user a sense of what is important. An elevated element looks like it is floating above the page. By using these tokens, you make sure that every card on your site has the same level of depth.

Advanced Tokens: Opacity and Interaction
The 141 tokens also cover things that most people forget. There are 6 opacity tokens for making things semi-transparent. There are also 7 interaction state tokens. These control how an element looks when a user hovers over it or clicks it. This includes things like the background color change on hover and the shadow change when an element is focused.

Z-Index and Layers
If you have ever had a menu hide behind an image, you know the frustration of z-index issues. wpTruss includes 7 z-index tokens. These define the stacking order of the site. There are levels for the base page, sticky headers, dropdown menus, modals, and tooltips. By using these tokens, you never have to guess a number like 9999 to make something show up on top. You just use the modal token.

Why wpTruss Installs These 141 Tokens
You might ask if 141 tokens is too many. Why not just have 10 or 20? The answer is about coverage and governance.

Complete Coverage
If you only have a few tokens, developers will eventually need to hardcode a value. If there is no token for a small border or a specific shadow, they will write a hex code or a pixel value into the CSS. Once that happens, your design system is broken. By providing 141 tokens, wpTruss covers almost every visual situation a developer will run into. This prevents them from needing to make up their own rules.

De-coupling from the Theme
The most powerful reason for these tokens is that they do not belong to the theme. In the old way of working, if you wanted to change your theme, you had to re-do all your design settings. With wpTruss, the 141 tokens live in the plugin. The theme is just a container that displays the content.

This means you can switch from one theme to another and your brand stays exactly the same. Your primary color, your typography, and your spacing do not move. This makes your website future-proof. You are no longer trapped by a theme developer’s choices. You own your design system.

Block Governance and Quality Control
wpTruss includes a block validator. This is a system that checks every custom block before it is allowed on the site. One of the most important rules is that a block cannot use hardcoded colors or spacing. It must use the tokens.

If a developer tries to upload a block that uses a specific hex code like #1a1a1a, the validator will stop them. It will tell them they must use a token like var(–wpt-color-dark) instead. This is called governance. it ensures that the site stays clean and professional no matter who is working on it. It stops technical debt before it starts.

Performance and Scaling
Using 141 tokens is also very good for performance. All these tokens are injected into the page as CSS custom properties. This means the browser only has to load the definitions once. Because the CSS files for the blocks only reference the tokens, those CSS files stay very small. They do not change when the design changes. This leads to better browser caching and faster page speeds.

The Business Value for Agencies
For a WordPress agency, time is money. Fighting with CSS is a waste of time. When you use a site with 141 design tokens, you are protecting your profit margins.

Imagine a client asks for a rebrand. They want to change the brand colors and make all the buttons more rounded. On a normal site, this might take a developer a full day or more to find every instance and update it. With wpTruss, it takes about five minutes. You change a few settings in the admin panel and the work is done.

This also makes it easier to manage many sites. If every site your agency builds uses the same 141 tokens, your developers can move between projects easily. They do not have to learn a new system for every client. The vocabulary is always the same.

The Role of AI in the Token System
We are moving into a world where AI agents will help build websites. AI works best when there are clear rules and structured data. Because wpTruss uses a fixed list of 141 tokens, it is very easy for an AI to understand how to build a block for your site.

wpTruss has a special feature called a capabilities manifest. This is a document that tells an AI exactly which tokens and rules are available. An AI agent can read this list and then write code that follows your design system perfectly. This is something that is not possible with traditional themes. By installing these 141 tokens, you are making your site ready for the future of AI development.

The 141 design tokens in wpTruss are more than just a list of settings. They represent a new philosophy for WordPress development. They move the design logic away from the theme and into a central, governed system.

By covering everything from basic colors to advanced interaction states, these tokens ensure that your site stays consistent and professional. They eliminate the need for hardcoded CSS and stop the growth of technical debt. Most importantly, they give you the freedom to change your site’s look or even its theme without starting from scratch.

Whether you are an agency owner looking to save time, or a developer looking to build better systems, the 141 tokens are the foundation you need. They provide the structure that allows creativity to flourish without creating a mess. One admin panel, zero CSS fights, and a design system that survives forever. That is the power of the 141 design tokens.

Visit: https://wptruss.com/

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