Journey of a Programmer

Basic Style Guides in WordPress

I have built or maintained a number of custom WordPress themes over the last few years and I’m big on making testing/validation as easy as possible. I’ve had some experience with unit testing through my Symfony and Python work and I wanted to do the same with WordPress. However, testing the look and feel of a website doesn’t easily fall within the scope of unit tests. When I first heard people talking about style guides, it felt like an intriguing and natural solution to this problem… But how to make use of it?

Style Guide Pages

My initial starting point with WordPress was to manually create pages and posts to explicitly collect all the different types of content chunks from basic HTML elements on up. On test sites, I’ll add these to my primary navigation menu so they are easily accessible. If you don’t have a test site, you can always publish them as private which will require you to login in order to view them. If your theme makes use of page templates, make a page for each template and make sure you give them descriptive titles to match.

From there, you can add any other sample content that is representative of content as a whole. Do you make extensive use of Gravity Forms? Put together a sample form with all the different input types you use and include that. Have you made custom short codes? Add those as well with all the different attribute variations so you can see them in action. Yes, this is a manual process, and I acknowledge that this is not my ideal solution. However, even if you want to invest time in a tool of some kind, you will still need to assemble your examples. You have to start somewhere.

Style Guide Shortcode

While following this pattern, I found myself copying some of the same markup around from post to page across the different sites I was working on. Much of it was just so I could see how basic HTML elements were being styled and quickly confirm that base styles hadn’t changed. That lead me to extract some of this sample content into a shortcode that lets you easily drop in stock HTML to any WYSIWYG editor. I’ve extracted the shortcode into a plugin that can be found here: https://github.com/cambot/simple-html-styleguide.

Final Thoughts

I find the exercise of creating style guide pages and posts invaluable. It helps at the start of a project when I’m setting up custom theme styles. It also has benefits later on if you find yourself refactoring your style sheets or are iterating towards a new design.

Fortunately, testing is more about feedback rather than the specific tools you use. If you don’t have the time or flexibility to invest in a style guide tool of some kind, starting with a manual process like this is a good starting point. I’m looking forward to the day when I can take this to the next level.