Boost your efficiency with a styleguide

A styleguide provides a branded look and feel to anything you produce. However, a web page is affected by many factors, including different devices, browsers, and screen sizes. We need a more robust guide for describing web creations

Bring on pattern libraries

We have a need for modularity in web design, so rather than static definitions we describe patterns. Patterns are commonly used in the clothing industry and are used to create clothing from paper representations.

Just as a clothing designer can choose different fabrics or colors, a web designer can modify the look and feel of a module while maintaining the same shape and components. Example pattern libraries can be found around the internet. Such as, Pattern Lab, SMACSS, Twitter Bootstrap, and BBC’s GEL, to name a few.

How can a styleguide improve efficiency?

Good question, let’s go over its benefits:

View all your styles in one place

Imagine your designers hand you a comp filled with form elements and it’s your job to apply the styles to the site. Each type of input, button, textarea, have to be styled. Is there one place on your site where you can see all these items? How will these changes affect your search and login forms? The pattern library provides you with a view of all your headings, form elements, and more, allowing you to quickly spot problems.

Reference for designers and programmers

When a designer needs colors, fonts, or even an example module for a design they’ll have a place to get it. Same with a programmer who is looking for specific class names or HTML structures. You can also provide quick references to other curious coworkers.

The key to building your own site is to build it fast. Before you can change your mind. Once you have something up you can continue to improve on it.

Share with partners

Your brand may have product web pages separate from your main site, or you may have business partners that need to create a site based on your brand. The pattern library provides all the information to build a site using your brand.


The sandbox is where you’ll be doing the bulk of your work. Build your HTML comps, demo functionality, incorporate new features, or just experiment.

Present interactive designs

Client comments on design are such an industry standard that they’ve been immortalized as posters and comics. In design meetings it’s often hard to keep a client focused on a relevant topic. As a front-end developer, you can help your design comrades by building interactive mock-ups.

When presenting a fully functional HTML mock-up, clients tend to focus more on the topics you want them to. An HTML mock-up has more capability than an image as well. You can showcase responsive design, articulating states, web fonts, and JavaScript.


You’ve just read an article about CSS animations and you want to create some scrolling effects. Here’s the perfect place for experimenting on your site. The sandbox also provides a method to collect useful snippets for potential use in later projects.

This seems like a lot of work

You’re right, writing a styleguide is a lot of work, but in the long run it will save you hours of “wasted” time and provide you with an intimate knowledge of your code. Having this knowledge allows you to solve problems much faster, and the sandbox provides you instant feedback while writing code.

Let me share with you how I became more efficient by building a styleguide and improving my workflow. Then, how to completely automate the process of building the styleguide as you write new code.

My old workflow

At my workplace it’s really difficult to get something from an idea to production. The design process is pretty standard. We have a goal and some guidelines. We produce wireframes and design comps, but to take it any further we need our information technology department (IT) to step in.

chart of workflow

We have a Java based environment and portal software. We use git for version control, a package manager, and several environments for publishing.

The IT department supplies us with a git repository and incorporates it into the portal system. Then using a Java IDE we work locally on a copy of the website before publishing, and we notify IT when we’re ready to publish. If they approve, they’ll notify us when they’ve scheduled a build.

All the while, we wait anxiously at our computer to see the fruits of our creativity. When the time arrives we hit refresh in our browser, with the URL already entered, and watch as pixels of colored light render our carefully designed and coded web page.

First we check that our changes made it into the build. If they haven’t, we notify IT and they rerun the process. Next, we evaluate if the update fixed the problem.

Let’s say we modified a wrapper in the portal to have 20px of padding:

.portal-wrapper {
  padding: 20px;

As we view it on the newly rendered page we see that it fixes the problem perfectly. However, a page with a special layout is completely broken. It’s an easy fix, let’s just remove the padding on the special layout:

.special-layout .portal-wrapper {
  padding: 0;

Now we need to get IT to do another build, but they can’t. It’s the end of the day and the administrator left to pick their child up from school. We’ll have to wait until next week, since today’s Friday. It might be an easy fix, but we have no control in fixing it.

Ron Burgundy saying that doesn't make any sense

If only I had known about the unique page layout before committing the style. We do have a way of fixing it, but it feels dirty, like I need to take a shower afterwards. The change is part of a larger build that has to go out for the weekend. So, I log into the portal admin tool and add an inline style to the unique page. It works, but to our detriment, as it may create a problem later.

This whole process felt tedious and disjointed, which led me to find a better way…

In the following section I’ll show you how to:

  • Automatically generate a styleguide
  • Use a static templating system
  • Preprocess, minify, and concatenate your CSS and JS
  • Accurately recreate your company’s site to fully test pages before you commit
  • Perform this whole process in seconds

Let’s grunt!

No, this isn’t an onomatopoeia for a pig or an exclamation of manliness. Grunt is a task runner, and it is the industrial revolution of front-end development. You can now run every process of development, on your own computer, in seconds. You control every detail of minifying, linting, concatenating, preprocessing, and much more.

Like any factory, Grunt is nothing without some machines to configure. Let’s say you’re making peanut M&M’s. You’ll need to coat peanuts in chocolate and a candy shell, color them, and print them with an “m”. Then package and distribute them. Every bag produced by a set of machines that have been calibrated based on user expectations.

Websites are very similar. Every aspect of development can be broken into a task and fine-tuned to obtain the results you want.

A living document

Whenever I wrote a styleguide there was a limited amount of time it was relevant. I often found myself saying, “It’s a little outdated.” That’s because as a developer, I was always trying to perfect my code, and I found myself putting off updating the styleguide until I was done. But I was never done, there was always some new feature, or optimization to keep me busy.

Having a living document means that your styleguide updates automatically when you update your code. The HTML is constructed based on a template, and the generated examples even have syntax highlighting!

shocked owl

A good example of this is Github’s styleguide. They use a tool called KSS, or Knyle Style Sheets, to automatically generate pages containing style definitions and examples. While KSS is awesome, it’s only a small part of your factory.

Meet Jekyll

Jekyll, “Transforms your plain text into static websites and blogs”. If this doesn’t sound like a big deal to you, then you haven’t used it yet. Github uses this tool to generate web pages. Are you familiar with Twitter Bootstrap? That’s built with Jekyll.

So, what does that mean for your styleguide? It means you can set up your site the same way you would in a dynamic environment. Build templates and include files based on conditions and variables. Jekyll uses the Liquid templating system, developed by Shopify, which gives you the ability to use operators, logic, loops, and more to build your pages.

With Jekyll, you can:

  • Create static pages in a dynamic way
  • Pass conditions during the build process
  • Use the same includes as your production environment
  • Use the same layouts as your production environment
  • Create mock includes and layouts for testing and experimenting
  • Create pages exactly like your production environment or as different as you want, all from the same folder

New improved workflow

Thanks to Grunt and KSS, designers and developers can be confident that your styleguide is an up-to-date reference. Greatly enhancing research and discovery by the design team. Your developers will also have a better resource when building the latest feature, and will be able to update the styleguide as easy as you.

In addition, because of Jekyll you have a factory at your fingertips to generate HTML mock-ups that better help your clients understand new designs. Additional Grunt packages allow access to preprocessors, linters, and more. There’s even a web server to more accurately display your web pages as they were meant to be seen.

With these tools at your disposal you can mimic your production environment with as much detail as you want. Thereby eliminating the reliance on a third-party for accurate previews. Without being tied to an IDE, you can also use your favorite text editor to write code.

final workflow chart

In the following section you’ll find links that will help you get started on building styleguides and working with Grunt. I’ve also included a generator that that installs everything you need to get started.

Further reading

If you’ve enjoyed my writing up to this point, then you may want to review these other resources.

My styleguide generator

Styleguide resources

Pattern libraries

Let these examples inspire your own guide.

Task runners

Use grunt or gulp to automate your tasks.


Build style sheets from you CSS comments.

Yeoman, Jekyll

Build HTML from templates and Liquid coding.


Use a package manager to keep your resources up to date.

Back to Resources