Why do I need a style guide?

Let’s be honest, I code differently than you.  And you code differently than the guy sitting next to you with Cheez-it crumb fingers playing Pokemon Go when no one is looking.  So how can we (front end developers) make sure we are providing consistent high quality code across a team?  Enter the style guide!  This post will walk you through how to setup a build system using Gulp.js, Sass and Hologram to generate a living style guide.

Where we started

When our Brick Factory team first began using style guides they consisted of 4-5 HTML files that we maintained separate from the site itself.  We would set up the style guide statically at the beginning of a project to make sure it contained all of the base components and HTML elements . This was all fine and dandy, but after a few months (or weeks) it became out-of-date simply because it was “separate” from the code we were writing.

I started doing some research on how we could get a style guide that generates automatically, and lives somewhere easily accessible.  There are some great options in this space, but after much deliberation and testing we landed on Hologram by Trulia.

What is Hologram

Hologram is a Ruby gem that parses your Sass and looks for special comments to generate a set of structured HTML files.  This means you no longer have to create HTML files manually and the example code lives right within your Sass.  This was a game-changer for our team simply because it makes keeping the style guide up-to-date much easier.

Now we no longer have this separate ambiguous document that no one dares go near.  We have a living, breathing document that not only shows example code, but can output the code directly in the browser.

Installing dependencies

In order to follow the rest of this tutorial, you’ll need to have Node.js and Gulp.js installed globally on your machine.   Let’s start with verifying you have Node.js installed by running the following command:

If this command comes back as “command not found”, you’ll need to install Node.js globally before moving on.  Download Node.js here for your specific operating system and follow all of the prompts.  Once you finish installing it, run the command above again to verify it installed successfully.

Now that you have Node.js installed, verify that Gulp.js is installed by running the following command:

If this command comes back as “command not found”, you’ll need to install Gulp.js globally by running the following command:

Some of you may have to run sudo  if you run into permission errors. If you have to use sudo there are probably other permission issues on your system, but for the sake of this tutorial just use it if you have to.

Let’s get to the code

I’ve created a quick front end starter kit specifically for this tutorial that uses Gulp.js to compile Sass. We’re going to start by downloading the files from the repo and then we’ll get into installing Hologram.

  1. Download the zip file
  2. Create a project directory somewhere on your computer and extract the zip file into that directory.  Keep in mind the zip file already contains a folder so make sure you’re only moving the contents of the folder into your new project directory.

Installing node packages

Since we are using Gulp to compile Sass we need to install a few node packages to get our build system up and running.  If you open package.json in your project folder you’ll see what packages/plugins I’m including for our system.  To install these packages run the following command via terminal from your project directory:

Installing Hologram

Once you have the packages installed you’ll need to install Hologram (Ruby Gem).  Run the following command to install it on your local machine:

Once the gem is done installing you’ll need to initialize Hologram inside of your project directory.  For this example I created a separate “styleguide” directory because I like to keep my root project folder clean.   To initialize Hologram in your project open your command line tool (iTerm, Terminal, etc).  Change directories into your newly created project directory using the “cd” command.  You’ll then want to “cd” into your “styleguide” directory.   Once inside run the following command:

This will create all of the configuration files you need to get your style guide working the way you want it to.

Tweaking the hologram_config.yml file

Now we have all of the technology we need to compile Sass and generate a dynamic style guide, but first we need to make some configuration changes.  Go into the style guide directory and open hologram_config.yml in the text editor of your choice.  Copy and paste the following code into that file overwriting its existing contents.

Here are a list of changes I made in this file from the default file hologram provides:

  1. Changed the source to use the correct folder name and path
  2. Updated documentation_assets to point to the GitHub theme we downloaded in our packages earlier (theme of style guide)
  3. Added css_include to dynamically add our main site css to our style guide.  For you this could be multiple files, but for this example we’re only compiling one Sass file for demo purposes.
  4. Updated dependencies to include our processed folder needed to dynamically grab the site css.
  5. Changed the index option to use styleguide.md which is located in our scss folder.  This sets the style guide home page.
  6. Added global_title to output the title of the style guide in the top left corner (needed for GitHub theme).

Testing our build system

Now that we have everything installed we want to make sure our build system is working properly without errors. In yor command line navigate to your project directory (if you aren’t already there) and run the following command:

To verify everything is working properly navigate to the processed folder and see if there is a CSS file in there (for this demo you should see processed/css/app.css).  If it’s there you’re in business, if not you’ll need to make sure you followed all of the previous steps.

Add hologram comments to the Sass

I’ve already included a few Hologram comments in the scss/app.scss file for you to take a look at, but here is a breakdown of a basic Hologram comment.

  • Title: Title of the style guide component.  Shows directly above description and and code snippets
  • Name: machine name that dictates how things are ordered
  • Category: This let’s you group style guide components into categories.  It also outputs each category as a main navigation item
  • html_example:  Outputs the code snippet so you can copy and paste it, as well as showing the rendered output.

Adding a variation to the style guide

Open up app.scss and we’re going to add a blue variation to our list.  Starting at line 38 you’ll see the opening comment for our lists component.  Then on lines 47 and 58 we’ve defined two different types of lists, purple and green.  Place your cursor on line 67 hit enter and follow the same syntax as the purple example above.   Make sure you change the title, desc, and the html_example to match the new blue class. Finally add the CSS which makes the list blue using the class c-list—blue.

When complete your code should look like the following:

You can also list the output of the code to the left and the code snippet to the right.  It works great with buttons.  All you have to do is change html_example to html_example_table in your comment.  Each row needs to be separated with a space in order for this to work correctly.  I’ve added an example in app.scss of tabular output and here is the code to achieve that:


You should now have a simple build system that compiles Sass and generates an awesome style guide!  It’s really helped our team write consistent code across the board as well as provided a launching pad for getting new people integrated into projects quickly.  This is not a complete system by any means, but it should get you up and running with some of these new concepts.

Next Steps

There are a few things we are exploring such as dynamically injecting content into our style guide from Drupal and using PhantomCSS to run diffs on the style guide to catch any major changes.  Let us know in the comments or on social media what cool things you’re doing with your style guides.


About the Author
Shane Jeffers
More From Shane Jeffers