Style Guide Generator Roundup

Style guides are a living document of code that detail all the various elements and coded modules of your application. The term “pattern library” is often used when talking about these types of guides—Brad Frost has a great piece on differentiating between the various types of style guides. To learn more about creating style guides see either Creating Style Guides here on A List Apart or Front-end Style Guides by Anna Debenham.

In the past I’ve been quite old fashioned and done the HTML for style guides by hand, but with a new project I wanted to try out a style guide generator. Style guide generators bring at least some automation to the creation of your guide, so that you don’t have to do everything by hand. They may actually create the guide itself using a process built on a task runner, Node, or a particular language. My client requested something straightforward, something that would have some type of auto generation. So, off into the land of generators I went.

Because they generate portions of the guide itself, maintenance is hopefully easier. Generators aren’t a silver bullet, they’re not completely automated, but even just getting part of the process done for you can make life easier down the road.

There are a lot of different kinds of generators out there. Many of them are based on workflows or a particular tool, and some of them have been ported over to several different workflows, so I’m breaking these down by workflow, but you’ll see several mentioned in the various categories.

Node.js

There are several generators that run off of Node, so if you like Node, you have some choices. KSS has a Node version, and there’s also Pattern Primer, StyleDocco, and StyleDown.

Two of these, KSS for Node and Pattern Primer, are just ports of other generators that run on something other than Node. But StyleDocco and StyleDown both were written in Node.

KSS, StyleDocco, and StyleDown all use a combination of comments and markdown that are in your CSS files (or whatever files your CSS uses, such as Sass, etc.). For example:

/**
* Button:
* `.btn` - the main button style
*
*     @example
*     button.btn Button
*/

This is using StyleDown for the generation, just as an example—they all vary a bit in what you put into the files.

I found in my research that all of these were easy to get up and running, the most complicated being Pattern Primer, because you actually break up the HTML into partials, whereas the others use just the comments to guide what markup will be generated in the final file.

Some of these, such as StyleDown and StyleDocco, come with some nice out-of-the-box styling for the guide itself, so you can get something looking quite nice in very little time.

Gulp and Grunt

There are several style guide generators that can be used with Gulp or Grunt task runners to get up and going. Some of these are the very same as mentioned above using Node, so it is just versioned to work with the particular task runner.

So here’s a list of the ones I’ve already discussed, but just made for Gulp or Grunt:

• KSS (Gulp or Grunt)
• StyleDocco (Gulp or Grunt)
• Pattern Primer (Grunt only)

But there are some generators that are unique to Gulp or Grunt and one of them looks quite amazing. Fabricator creates a great looking UI toolkit, so I recommend checking it out if you’re looking for a robust solution and you use Gulp.

Grunt also has several generators that are not on Gulp, so here are some more to check out for that workflow:

• Pattern Lab
• Sassdown
• SourceJS
• Style Prototype

Using a task runner, much like Node, can be great for a quick, lightweight solution. For certain projects, many of these could be a great solution, especially if you’re in client services and will be handing off the code at the end. These (or the Node solutions) would be fairly easy for them to get up and running as well.

Ruby

The generators using Ruby (or PHP for that matter) are often quite robust, generating something more akin to Fabricator, with navigation, nice styling, and flexibility. If you are already working on an app in Ruby, they make even more sense, but the style guides can be done as a stand alone as well.

Hologram was developed by Trulia and has become a great solution for generating guides. It relies on YAML and markdown comments in your CSS to generate a fantastic style guide. It has a great templating system with some basic styles and navigation that makes the generated guide easy to use.

KSS, mentioned above in the Node section, uses the views in whatever your framework of choice is to get the guide generated. Because it is a bit more wrapped up in the framework of the application itself, it may not be as quick to get it up and running, but once you’ve done the work, it could be a great add-on to your current application and help you keep your UI in order.

The Living Style Guide is another tool that runs off a Ruby gem, but uses just Sass and markdown to compile it all together. You write markdown partials of each module, which is then translated into the markup for the guide itself. The gem then takes all the markdown templates and converts it to HTML and creates the guide. It runs off a gem, but it doesn’t have to be used with a Ruby project, it can run in other projects as well and you can also integrate it into Rails.

There is a version of The Living Style Guide in Gulp as well, if you would prefer to try that instead of the Ruby version.

PHP

Unlike many of the other generators already discussed, for these you’ll need to have a local server running to put it all together and see it in action. But some of these solutions have been around for a while and used in great projects.

Barebones, is more than just a style guide generator, but does include one. Using partials and includes, the modules and components can get included on the style guide page.

Pattern Primer runs in a similar way to Barebones. The patterns are partials of HTML and then compiled into the main index page. One nice feature of the Pattern Primer is that the patterns are already in the GitHub repo, so you have a great starting point for all the various different elements you quite possibly would be using in your site or application. In addition, you may have already noticed this, but this concept has been ported over to several other workflows.

Pattern Lab generates a static site of the various patterns and modules used in a site and it is quite robust. It uses mustache templates, with JavaScript for viewing and PHP for building, but once it’s built, it’s static, which is really nice.

Style Guide Boilerplate is another PHP-based generator, but it runs on a server, much like Pattern Primer. There are some initial patterns to help you see how everything works and you can go from there creating your own snippets to include in your final guide.

That’s a lot of different choices for how to generate your style guide. I’m sure there are even more possibilities, so if I missed a tool that you really like, please let us know in the comments. You can also check out styleguides.io for even more information on style guides, and share additional generators or tools you use when creating style guides there via GitHub or on their form if you aren’t comfortable doing GitHub pull requests.

If you are just getting started with style guides, then you should definitely check out styleguides.io. There’s a lot of information there, but the resources with stars are a good place to start. It can seem daunting with all the information there is out there, but just getting started and creating your first guide will show you how wonderful they can be in a workflow—hopefully one of these tools will make generating your first guide just a bit easier.