How a Theme Update Gave Our Custom CSS a Nervous Breakdown

One of the more dreaded notifications we get on our WordPress sites is the one to update the page builder or theme. 

It is not a question of if an update will break the site design, but when.

These are real problems, faced by real people, trying their best to manage real sites. 

Our support channel is full of them, because when all troubleshooting fails, you need backups. But that’s not the point of this article. 

Today, we are going to talk about how theme updates and custom CSS broke our site design—and how we built safeguards to make sure it doesn’t happen again.

What went wrong? 

We updated the theme on the BlogVault site and it caused errors in the design. 

Not obvious errors, mind you. Just small errors that look a bit off when reading an article. We already know how updates can break things so silently, you are unlikely to find out until later. 

Issue 1: Break in code block design

Take this code block in one of our how-to articles. 

The heading an Copy button vanished, leaving a rather ugly blank space of no discernible purpose.

Issue 2: Change in footer links font size

In yet another issue, the footer links became tiny. Completely unreadable. And across the entire site.

But the catch was that it didn’t happen right after the update, but only after someone changed the links in the footer block. Even after that, logged in users didn’t see the change—only site visitors. 

Background

We used staged updates with the additional guardrail of visual regression tests. 

✅ Firstly, the update is tested on a staging site, and only then applied to the live site. 

✅ Secondly, during the update on the live site, our system runs visual regression tests on all key pages. 

So why did the issues escape all these safeguards? 

For the code block issue, the break in design was not on a critical page. It was on blog article pages, and that too, only a handful of pages. Visual monitoring tests are not run on all pages of the site. 

For the footer link font size issue, it was slightly more complicated. 

It didn’t happen immediately after the update, so visual monitoring tests during the update didn’t catch it. Logged in users couldn’t see this change, so site admin didn’t catch it.

Troubleshooting 

As it turned out, it was changes in the theme code that caused all these issues. 

Changing from <span> to <div>

The code block is a necessary part of UX, so that we can add code snippets contextually within an article. Since our site uses the Kadence theme, we used its blocks to create the code block.

Kadence Blocks initially had the base element for the code block wrapped in a <span> with a class name. In a major update, they converted the element to a <div>, but with the same class name.

To convert the base element into a code block, we applied custom CSS, referring to the element like so: span.classname. When the update changed <span> to <div>, the design broke. We didn’t expect them to change their basic framework so much. 

Change in styling application

Our first thought with the footer link issue was caching. Caching is responsible for a lot of design breaks, after all. 

But it wasn’t caching that sunk the footer ship; it was custom CSS yet again. 

The CSS remained as it was, until the footer was opened in edit mode. 

Kadence Blocks had changed styling in the update. The new styling implemented font sizes in small, medium, large format. 

As soon as we opened the footer in edit mode, the text applied the default font size for the block—in our case: small. 

Why didn’t the custom CSS stay intact? Because custom CSS generated by blocks is inline, it overwrites CSS calls from separate files.

Best practices moving forward

We were able to troubleshoot the design issues quickly, because of sustained use of Kadence over the years. Even while developing the site, we kept the theme’s unique quirks in mind.

For example, when you edit pages or posts, you will learn how blocks have changed over time. You may see custom class names added to certain blocks automatically after update. And there are other visible changes in the styling interface, which affect what happens in the backend.

Despite all this, our design still broke, because we didn’t expect there to be such a wholesale change in the framework.

Changes to our update workflow

We did the basics going in: staging, backups, visual regression testing. And yet, there were cracks in the workflow. 

Therefore, there are more automated safeguards to add. 

UpdateLens

Our first port of call is the UpdateLens feature. The code diff panel is an excellent way to see what has changed in an update. We would have been alerted to these issues much earlier if we had had UpdateLens then. 

Visual monitoring

The footer issue would have been caught immediately after it was triggered with visual regression testing. With a 0.01% sensitivity to visual changes on major pages, the tests would have raised an alarm. 

Page content monitoring

The issue with custom code blocks cannot be caught with visual monitoring tests, however we can now set up page content monitoring instead. 

Page content monitoring looks for important phrases and words on a page. If those aren’t found, we get an alert. For different types of pages, we can set up monitors to check if custom styling is rendering as it should. 

Changes to how we implement custom styling

We also evolved in our use of custom styling. We now save customised blocks as patterns, with all required styling and import it wherever required. This eliminates the need to write custom CSS altogether, while keeping the uniform styling we want within the theme. We apply a similar process across other site components as well.

The case for and against custom CSS

One could argue that page builders and advanced themes preclude the need for custom CSS. But the answer is more nuanced than that.

In our case, custom CSS allowed us to manage and style multiple blocks with a single block of CSS code. 

It is more efficient, as we don’t have to implement the same style on each page or post: fonts, colours, line heights, etc. In fact, it helps implement uniform styling across our site that is built with various tools.

Additionally, it gave us more fine-grained control over the design of our site. We want to engage visitors, and the right design and UX is the biggest lever.

On the flip side, as we saw, custom CSS causes issues. It can conflict with existing theme or plugin styles, causing unexpected issues; or future ones. Who knows!

Each site is different with differing needs. A one-size-fits-all approach rarely works. If you cannot eliminate custom CSS, it is fine. But it is crucial to have automated safeguards at every step.