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.
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:
|
1 |
node -v |
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:
|
1 |
gulp -v |
If this command comes back as “command not found”, you’ll need to install Gulp.js globally by running the following command:
|
1 |
npm install --global gulp-cli |
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.
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.
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:
|
1 |
npm install |
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:
|
1 |
gem install hologram |
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:
|
1 |
hologram init |
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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
source: ../scss destination: ./docs documentation_assets: ../node_modules/hologram-github-theme css_include: - '../../processed/css/app.css' code_example_templates: ./code_example_templates code_example_renderers: ./code_example_renderers dependencies: - ../processed index: styleguide nav_level: all exit_on_warnings: false global_title: Styleguide |
Here are a list of changes I made in this file from the default file hologram provides:
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:
|
1 |
gulp |
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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
/*doc --- title: Card name: card category: Components --- Description of what a card should be. ```html_example <div class="c-card">Card</div> ``` */ |
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 |
/*doc --- title: Lists name: lists category: Components --- Contains styling variations of the list component. ## Green list Example of the list component. ```html_example <ul class="c-list"> <li class="c-list__item">List item 1</li> <li class="c-list__item">List item 2</li> <li class="c-list__item">List item 3</li> </ul> ``` ## Purple list Example of the purple list component. ```html_example <ul class="c-list--purple"> <li class="c-list__item">List item 1</li> <li class="c-list__item">List item 2</li> <li class="c-list__item">List item 3</li> </ul> ## Blue list Example of the blue list component. ```html_example <ul class="c-list--blue"> <li class="c-list__item">List item 1</li> <li class="c-list__item">List item 2</li> <li class="c-list__item">List item 3</li> </ul> ``` */ |
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
/*doc --- title: Buttons name: buttons category: Components --- This is an example of how to use ```html_example_table``` to output the code snippet and rendered output next to each other in a table. ```html_example_table <button class="c-btn c-btn--default">Button</button> <a class="c-btn c-btn--default" href="#">Link</a> ``` */ |
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.
Resources
Sign up today to have our latest posts delivered straight to your inbox.
