Building a Style Guide
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.
- Node.js: 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.
- Sass: 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 ;)
- 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.
It was time to rip out the existing UI framework and use what we created. The final stretch here took another six weeks and there were times I questioned if we could pull this off.
We started off by doing the most liberating part of the whole project, deleting Bootstrap 2.3. It was liberating for about 15 seconds, until we refreshed our browser and saw our app in shambles. From here we went component by component:
- Replacing old classes with new ones, tons of find and replace here.
- Switching to a fixed grid for some of our pages.
- Completely reorganizing some pages.
- Reimplementing modals, dropdowns, and tooltips with our Angular directives.
During this process, we came across use cases that were missed and we’d have to make tweaks to our style guide project. This was a given though, as our app literally has hundreds of views.
Reviewing code as we went was a big part of this project. There was only two of us, so it was easy to just ping each other for a review as we needed it and move along. We would do a little work, review it, and then merge it in with the rest of the work. In the end, we added 3,500 lines of code and removed 12,791, touching close 693 files. No one was going to read the pull request, but given our review process, I was ok with this.
After some insane QA and bug fixing, we finally launched it on a glorious Friday around 1PM. I didn’t care if it was a Friday. I wanted this project finished, it was draining and it was hard. In the end though, it was worth it and we only had a small handful of bugs that came up. Now, we officially have a style guide that our team of 15+ developers use to build our interface. It’s not perfect and we make tweaks as we need to, but at least now we are all on the same page and have a little more structure.
