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





Made with