- March 5, 2014
The Scoop on Our Benjerry.com Style Guide
The web has been all about style guides lately. Everyone from the BBC to Code for America
to Yelp released their guides to the public, and style-guide-automating tools like KSS and Hologram are becoming increasingly popular. At Happy Cog, we’ve been making our clients’ style guides more interactive. Our newer style guides go beyond documenting the design systems we’ve established; they take advantage of their living in the browser to dynamically show how a system’s pieces are built, how it responds at different viewport sizes, and how users can interact with those pieces.
For the recently launched Ben & Jerry’s website redesign, we created one of these “interactive style guides.” It covers everything related to building out and maintaining the new website: design components, page layouts, and even content creation. I chatted with a few of the Cogs responsible for the Ben & Jerry’s style guide about how it came together.
1. What was the process for creating the style guide?
Sophie Shepherd, Designer (SS): I started working in a Google Doc to create an outline, write descriptions, and paste screenshots—though there weren’t many of those since we used live code wherever possible. This allowed the entire team to collaborate on the guide’s writing early.
Cat Farman, Developer (CF): While Sophie was adding content and design notes, I was editing existing notes to add code examples, links to the templates, Sass mixins, class names, and other implementation details. We used the same tools we used in our front-end templates to create the style guide: Sass, Git, and mostly static markup. The Ben & Jerry’s style guide lives inside the project repository on Github and pulls its CSS and JS directly from the project’s assets. We documented markup for each element in the style guide, using LeaVerou’s Prism.js to add syntax highlighting.
Syntax-highlighted code snippets illustrate the markup for each module in the design system.
SS: This was the first time I worked on a style guide that used live code to create visual examples. In the past, we took multiple screenshots for one item to show different states of interaction or responsiveness. It took forever, and it wasn’t even a true representation of the elements on the web. I learned a bunch by digging through templates to find code snippets and felt like this was a true 50/50 collaboration. We both pushed up changes at the same time, and Cat was there to talk me down off the ledge when I had commit errors and thought I broke everything.
2. Aside from including live code snippets, what other new things did you try with this style guide?
SS: Lots of stuff! My favorite was folding our content strategy into the style guide. During the project, our content strategist Steph Hay delivered a lot of documentation around what types of content would be on the new Ben & Jerry’s site, where each type would live, and who would be responsible for editing each bit. We coded this documentation directly in the browser and then were able to cross-link to visual, coded examples of the content types in the style guide.
Chris Cashdollar, VP of Design (CC): Our design system is being rolled out to markets all across the globe. That means the instruction for how our design system is to be used is just as important as the system itself. Content will be used in different ways for varying business purposes—we knew we couldn’t just design 20+ different homepages to solve this problem.
SS: Integrating the content strategy with the design system makes our style guide useful to anyone across Ben & Jerry’s global markets who has to update the website—not just Ben & Jerry’s U.S.-based design and development teams—and also saves teams from having to dig for archived files in Basecamp.
The content document is cross-linked to the style guide, so that content editors can easily learn more about the pieces they will be editing.
3. How did you make sure the guide not only documented, but also helped educate the Ben & Jerry’s team on how to use the design system?
CC: This is a crucial piece of any style guide. If our clients don’t understand the value of our system, we’ve done them a tragic disservice. For the Ben & Jerry’s style guide, we tailored the writing to the skill set of the staff who’d be using the system long after our engagement.
CF: A lot of work went into making the front-end code transparent. We explained the CSS3 behind design elements like transforms, shapes, and transitions, and linked to third party tutorials from sites like CSS-Tricks to give more in-depth resources behind the techniques.
SS: We also tried to incorporate design resources wherever possible. All of our layered PSDs can be downloaded directly. We wrote up directions for how the Ben & Jerry’s teams could access font files, update image sprites, check for color accessibility, and optimize all those fun hand-drawn illustrations using free tools like ImageOptim and ImageAlpha.
4. Our style guides evolved from static documents into living ones. How do you see them evolving from here?
CC: We no longer have to wait until the end of a project for our style guides to start being valuable. The sooner we define and articulate design patterns in our process, the sooner our designers can communicate those details to our clients, and the sooner their implementation teams can ask questions.
SS: I’d also like to see the style guide become a part of our design process earlier. That way, it could be a tool for us to use as we’re creating the site, instead of something that we create as a tool just for clients. I’ve referred back to the Ben & Jerry’s style guide many times to make sure new design elements and pages we’ve been tasked with remain consistent with the system. It’s much easier to understand the workings of a design system in a guide than to boot up Photoshop and look through PSDs.
CF: I can see our living style guides becoming a vital part of the QA process. If we can define markup early on, then build the design layer from the style guide out, we can use our style guide examples to test our designs cross-browser.
Are you using style guides not just document, but educate your clients? If so, tells us why you think they are valuable or how you’ve been customizing them for your own projects. Then find out more about our work with Ben & Jerry’s or check out the new site.