Maintaining living style guides with Hologram

It is a good thing to maintain style guides. Hologram is a system that may help to keep them alive.

According to Lean UX (Gothelf, 2013), a styleguide is a tool that makes collaborative design easier.

As stated in the book, a style guide:

(…) codifies the interactive, visual, and copy elements of a user interface and system.

So style guides are a very useful instrument in a software project, not only for designers, but also for developers. Gothelf further identifies three important characteristics successful style guides have:

It’s accessible,
it’s continually improved (a.k.a. a living document),
and it’s actionable.

The Ruby Gem Hologram is a style documentation build system that makes it easier to achieve these characteristics (you still have to write and update that documentation though…). I’ll show you how to use it in your project with the nice Github-style theme I’ve created.

Setup Hologram

First, install the Hologram Gem:

$ gem install hologram

You might want to build your own style guide template by using the command hologram init or by looking at the Hologram example repository. There is also a nice theme called Cortana, that is providing an additional category layer and a search feature. I’ve created the very simple hologram-github-theme that is inspired by the Github Styleguide, which we are going to use in this example.

Add the theme to your project with Bower (or simply download and copy it into the project directory):

$ bower install --save-dev hologram-github-theme

Create a hologram_config.yml file defining the paths to your resources:

# Relative path(s) to your source files
source: app/styles

# Relative path where you want the documentation to be built
destination: styleguide

# The path that contains supporting assets for the documentation page
documentation_assets: bower_components/hologram-github-theme

# Category that will be used as the index.html (optional)
index: styleguide

# A list of relative paths to folders containing any dependencies to copy
dependencies:
  - 'styles'
  - 'scripts'

# The CSS files to be included in the styleguide
css_include:
  - 'styles/main.css'

# The JavaScript files to included in the styleguide
js_include:
  - 'scripts/main.js'

# The global title that is displayed at the top of the pages
global_title: Styleguide

Now you can generate the style guide:

$ hologram

In a Grunt workflow, you might want to checkout the grunt-hologram task. For Ruby on Rails there is guard-hologram.

Let’s start documenting!

You can add the style guide documentation to your CSS (or Sass/Less) files using Markdown syntax:

/*doc
---
title: Buttons
name: buttons
category: Base CSS
---
Button styles can be applied to any element. Typically you'll want to
use either a `<button>` or an `<a>` element:
```html_example
<button class="btn btn-default">Click</button>
<a class="btn btn-primary" href="#">Me!</a>
*/

.btn {
/* ... */
}

Checkout this example styleguide which uses the Github-style theme.

The advantage of using Hologram is that the style guide content is at the same place where the style sheets are. Like this there is a bigger chance to have a living style guide. If Hologram doesn’t fit you, there are many more style guide generators you can choose from.

Happy documenting!

Photo: oliver hiltbrunner, CC BY-NC-SA 2.0