Software Engineering in WordPress and Musings on the Deep Life

Exclude a WordPress Theme Style Guide

When it comes to WordPress themes, one of the things that I used to think should be more common was the idea of style guides.

You know what I’m talking about: The documents that are either included with or ship with a theme that guide you on the typography, image sizes, video sizes, and other collateral to make sure that you use the theme exactly as it’s been designed to be used.

In other words, it prevents you from making the theme look ugly.

But are they really needed?

WordPress Theme Style Guides

Generally speaking, I’m a big fan of the idea. I think that given the right tools and guidance, people can make good decisions with the software and the tools that they buy.

This doesn’t always mean they will but it certainly increases their potential.

And if you can help the majority of the people who are buying your product, why not? Not only will it help increase the quality of their presentation, it’ll also speak well of you as a product and/or service provider in that you gave them the product that they needed as well as the guardrails that helped guide them along to building their site.

One of the best examples I’ve seen of someone doing this is Mike McAlister and his team at Array:


Not only do you know what their products look like, you know what you’re getting out-of-the-box. That is to say that you know the font treatments, you know how they will look when used in as headers, quotes, etc., and you know how they stack up with the rest of the elements that can go into a page.

It makes for a really nice experience, doesn’t it?

You Don’t Need a Style Guide

I’ve spoken before about the idea of creating extremely lean, focused WordPress themes that do things well, that are priced accordingly, and that give the user no more than what they need in order to achieve whatever their task may be (given their niche).

Now, this is not to say I’m a designer. Not even close. I just happen to be friends with a few who are really, really good at what they do (as in, I want to be as good a programmer as they are designer at some point).

And when you hang around people like that, you pick up on a few things – at least a few ideas – on how things should look and how there should be no compromises made.

That is to say, the product looks and functions the way that it does, and it does so because these decisions have been made out of  a position of expertise. “Trust us,” they say, “this is how it should look”.

I love this idea.

want themes (and plugins) to work this way. I want users to see our (that is, all of us who create them) products on the proverbial shelves, see that they can download it, install it, perhaps add a background image or a logo, know that they won’t mess up the way that it appears, and then move forward.

I want them to trust us with making sure that they aren’t setup to fail – that we’re on their side, and that we care about how they appear to others.

Or Wait, Maybe You Do

But right now, WordPress themes often provide users something to work with and then users ask

Now how do I change this and that and that thing over here and add that bell and incorporate that whistle?

And on and on it goes and it ends up changing the product that you created, that they bought, and turned it into this weird hodgepodge of something that kinda resembled something that once looked good but now looks like something that’s not so good.

Custom Designed Kitchen

Custom Designed Kitchen

It’s at times like this that you don’t want your brand name in the footer. At the same time, this is something that the freedom of the open web and open source code allows and supports. And I think this is something that’s an important point to be made:

Just because a product affords a particular set of behaviors doesn’t mean we have to follow with them.

You can take this as far as you’d like, but I’m sticking with this in the context of style guides. For now, at least.

Anyway, as far as it comes to creating niche products – specifically, niche themes – I’m not sure if a style guide is worth it. I mean, should the theme just provide said styles out of the box and move forward from there without giving users guidance on how to change things?

I mean, it’s one thing to show a page that includes all of the elements – a page in the demo, that’s great – but to offering up a style guide that helps users deviate in any way from the core design, the one that’s created from a level of expertise, is something I think isn’t worth creating.

There’s Two Sides To This

Of course, a post like this is also deserving a follow-up that looks at the counter-point or the other perspective or whatever on this situation. That is, perhaps we should ship a WordPress theme style guide.

Regardless, all I’ve done in this post is layout one perspective – I’m not necessarily taking sides, yet – but I’m curious to hear your opinions on this.

So in the next post, I’ll talk about why I think themes should have a style guide.


  1. Ryan Duff

    I’m not really sure that just a theme by itself needs a style guide. It makes sense to have a style guide for a project as a whole– because it ensures consistency across anything relevant (biz cards, email, website, etc). I see themes more fluid. I think style guides reside at a higher point in the grand scheme of things. Just my $0.02

    • Tom

      I’m not really sure that just a theme by itself needs a style guide.

      This is something that I’m planning to talk about in the next post. I think there are times where it matters, but I’ll talk about it in a bit :).

      It makes sense to have a style guide for a project as a whole– because it ensures consistency across anything relevant (biz cards, email, website, etc).

      This gets close to the point that I’ll be talking about in a bit. Spot on.

  2. Timothy Brand (@brandgraphics)

    Hands down one of the best freaking articles I’ve read in a long time. I love the thought provoking questions in it.

    I love the idea of a style guide in a WordPress theme. I sincerely hate that so many bloated themes come as a one-size-fits-all. Some of the top selling themes on the market right now state in their description “Multi-Purpose Theme”.

    I’m not a fan of this approach. I think themes, like their users, should be unique. I think a style guide is a great way to do this. It allows the end user their chance to add their flare to it without having to guess where things are or hire someone else to customize it.

    Thanks for the awesome read.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

© 2023 Tom McFarlin

Theme by Anders NorenUp ↑