Living breathing style guides:

a workshop in Grunt and Hologram

Who am i?

Front-end engineer & designer at Vox Media (publisher of Vox, SB Nation, The Verge, Polygon, Curbed, Eater & Racked)




Co-host of the DC Sass Meetup




who are you?

Part one:

style guides

the problem

What is a style guide?

  • Pattern library
  • Brand guidelines
  • Development guidelines
  • Tone/Voice guidelines

why style guides?

  • Internal guidelines
  • Onboarding
  • Maintaining brand

Some really cool style guides

Mail chimp

mail chimp

mail chimp

mail chimp

Mail Chimp

Sales force

Sales Force

Sales Force's not easy

The bad parts

  • Bandwidth to create them
  • Maintaining them
  • Following them

tools to help!

Style guide Generators

  • Create pattern libraries
  • Generate CSS/JS Docs
  • Maintaining style guide = maintaining css

there's a lot

But how do I choose?

EValuate what you're looking for

  • Visual Guides?
  • Code documentation?
  • Little effort?
  • Customization?

why I like hologram

  • Simple
  • No bloat
  • Easy to modify
  • Open source!
  • Trulia team is pretty great

part two:


What is hologram?

Hologram is a Ruby gem that parses comments in your CSS and turns them into a beautiful style guide.


title: Buttons
name: button
category: Base CSS

Button styles can be applied to any element. Typically you'll want to
use either a `<button>` or an `<a>` element:

<button class="btn btnDefault">Click</button>
<a class="btn btnPrimary" href="">Trulia!</a>


Supported Languages

  • Sass (.scss, .sass)
  • Less (.less)
  • Stylus (.styl)
  • Vanilla CSS (.css)
  • Javascript (.js)
  • Markdown (.md, .markdown)


  • Guard Hologram 
    • a gem that uses guard to monitor changes to your hologram project and rebuilds your style guide as you make changes
  • Grunt Hologram 
    • a grunt task that will generate your hologram style guide

Bad parts

  • Ruby

part three:

automation (aka grunt)

So wtf is grunt

  • A JavaScript Task Runner
  • Sass Compiliation
  • Image Optimization
  • Browser Refresh
  • JS Lint


module.exports = function(grunt) {

    pkg: grunt.file.readJSON('package.json'),

    //tasks go here
    sass: {
      dist: {
        files: {
          // Project Scss
          'css/*' : 'scss/*'

  grunt.registerTask('default', ['sass']);


hologram + grunt

  • Set up Hologram
  • Create Grunt tasks
  • ???
  • Profit

Style Guide Generators aren't perfect!

  • Can't generate visual guidelines
  • Still takes time and effort to create a useful style guide
  • Generators are best for generating code documentation





Living, breathing styleguides: A workshop in Grunt and Hologram

By allypalanzi

Living, breathing styleguides: A workshop in Grunt and Hologram

Styleguides are important for countless reasons: maintaining code, reusability, on-boarding, and keeping a consistent brand. What is difficult about styleguides, is curation and keeping it up to date. However, there are tools for that! This talk will teach you how to automate styleguide generation and incorporate it into your front-end workflow.

  • 3,689