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)

 

Sassvocate

 

Co-host of the DC Sass Meetup

@DCSassMeetup

sassydc.github.io

 

 

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

but...it'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:

Hologram

What is hologram?

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

/*doc

---
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:

```html_example
<button class="btn btnDefault">Click</button>
<a class="btn btnPrimary" href="http://trulia.com">Trulia!</a>
```

*/ 

Supported Languages

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

Extensions

  • 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

gruntfile.js

module.exports = function(grunt) {

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

    //tasks go here
    sass: {
      dist: {
        files: {
          // Project Scss
          'css/*' : 'scss/*'
        }
      }
    },
 
  });

  grunt.loadNpmTasks('grunt-contrib-sass');
  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

questions?

demo!

github.com/allypalanzi/codeherconf

THANK YOU!

github.com/allypalanzi/codeherconf

slides.com/allypalanzi/codeherconf

@mylifeasalllly