Deciding that your team needs a style guide is daunting, finding the right time is tough, but it was that time for us. Read my previous article, “When is it time for a style guide?”, for a little insight on why we did it. It’s a ton of work that normally takes several people to accomplish. Ultimately at the end, your customers don’t get anything new, that is unless you’re redesigning at the same time. We recently decided it was time for one at CallRail. Being my first time doing this I thought I’d share how we accomplished it without burning hundreds of hours for nothing.

First and probably one of the most important pieces is auditing your current application. This was our lead designer’s job and it took her about three weeks to do it. She went through every single page of our application documenting the current patterns and components we used. She identified common patterns and special cases. Colors, typography, icons, forms, headers, etc. all had to be accounted for. The result of this process was a series of documents and spreadsheets (using Google Docs) that documented our current interface.

Now that we had it on “paper,” our designers took to Sketch, a piece of software similar to PhotoShop, building a pixel perfect kit of components that make up our interface. Since this wasn’t a redesign project, only a few decisions had to be made during this phase. We used Zeplin, a “Collaboration app for UI designers and frontend developers”, to share the Sketch files. Using Zeplin allowed us to not bother with learning Sketch, but instead concentrate on simply viewing the components and inspecting pixel measurements, font sizes, and colors when needed.

This is where the fun starts; it’s time to write some code. We spent about six weeks building the style guide. The idea here was to ignore the current state of the main application and produce a stand alone app showing all of our components and documenting how to use them. Here’s what we used:

Angular.js 1.5: Used for building components like our audio player, dropdowns, and modals. We also used it for our basic navigation in the style guide app too.

Used for building components like our audio player, dropdowns, and modals. We also used it for our basic navigation in the style guide app too. Node.js: This serves our style guide app locally, runs specs, and builds our source files.

This serves our style guide app locally, runs specs, and builds our source files. Gulp : A series of gulp tasks compile our SCSS, JS, and run our specs. The output of our build task was a ui.js and ui.css file.

: A series of gulp tasks compile our SCSS, JS, and run our specs. The output of our build task was a ui.js and ui.css file. Sass: A CSS extension language that makes writing CSS a lot more pleasurable.

A CSS extension language that makes writing CSS a lot more pleasurable. Sass-lint: This is a node module for linting SASS. We came up with some basic syntax rules to help keep us consistent. Every pull request that’s open on GitHub runs this and will complain if you’ve ventured off. Check out our rules, but keep in mind every team has different opinions and I highly suggest you figure your own out ;)

This is a node module for linting SASS. We came up with some basic syntax rules to help keep us consistent. Every pull request that’s open on GitHub runs this and will complain if you’ve ventured off. Check out our rules, but keep in mind every team has different opinions and I highly suggest you figure your own out ;) GitHub Pages: Turns out you can serve static files on GitHub pages pretty easily. All of our files being served by Node are in the public folder. So, with the following Git commands we were in business.

git checkout master # create a local gh-pages branch w/ the splitted output folder

git subtree split — prefix public -b gh-pages # force push the gh-pages branch to the remote gh-pages branch

git push -f origin gh-pages:gh-pages # delete the local gh-pages

git branch -D gh-pages

With our easily accessible style guide we were feeling pretty good, but honestly the hardest part was still to come.