Heading into Chicago’s Midcamp, my coworker Andy and I were excited to talk to other front end developers about using style guides with Drupal. We decided to put the word out and organize a BOF (birds of a feather talk) to find our kindred front end spirits. Indeed, we found a small group of folks who have started using them and had a great conversation: tools, workflow and pain points galore! So if you have already been using them or if you are brand new to the idea, read on.
We looked pretty cool riding Chicago’s Divvy bikes to and from the conference!
So what is a style guide?
It can mean different things in different contexts, but for front end development, it means a fully-realized library of elements and components, using clean HTML/CSS/Javascript. I’ve heard them described as “tiny Bootstraps for every client” (Dave Rupert) — a client with a style guide has all the classes and/or markup they need to properly add new elements and components. A living style guide asserts that the style guide is maintained throughout the life cycle of a project.
At Advomatic, we’ve been integrating style guides into our workflow for about a year. We’ve had a few discussions about when it makes sense to have one, and when not. In the past, I’ve even argued against them, in the case of small projects. But at this point, we’ve come to the conclusion that it ALWAYS makes sense to use one. Smaller sites might have smaller styleguides — perhaps just with the the baseline elements included — but with a boilerplate style guide and a compiler in place, the style guide will, in fact, build itself.
So what can you use to build a style guide?
I heard many static markup generators and/or prototyping software mentioned at Midcamp: Jekyll, Pattern Lab, Prontotype, and Sculpin.
At Advomatic, we’ve been using KSS (Knyle Style Sheets), which is more specific to just generating style guides. It uses a Grunt task to compile a style guide from markup (commented out in your Sass files) and the corresponding CSS. This section documents setting up KSS to auto-generate your style guide using KSS. We use the NodeJS implementation of KSS, which, coincidentally, JohnAlbin (the brains behind Zen base theme and Drupal theming in general) has taken the reins on.
If you still haven’t found one you like, here’s a handy list of styleguide generators!
Scared? I hear you. It SOUNDS like an extra layer of work.
Here were my fears moving to style guides:
- It might add another layer of complexity and chance to break things.
- If the markup differs significantly in the style guide and Drupal, we’d have to do the work twice.
- The style guide is not within Drupal, so you cannot write javascript with the Drupal.behaviors convention.
- If your style guide includes components that are layout-dependent, you’ll need to set up your grid system within KSS.
- If the style guide rots on the vine or gets out of sync, it could be a pain to fix.
But let’s look at the pros:
- Clients love to see the style guide, it can be an early, easy win.
- Keeps the front-end decision-making at the beginning of the process, and agnostic of the back end.
- Front end work can happen alongside back end work.
- A HTML/CSS style guide can be a fully responsive document, unlike a PDF.
- A style guide can be a stand-alone deliverable, if the client needs to pause or implement it themselves.
- The modularity of a style guide helps clients think about the site as a system rather than individual pages. The result is flexible when the client wants to add more pages down the line.
- A style guide helps onboard new people coming onto a project or keep consistency among more than one front end dev. A FED can see if a similar component has already been built or if certain styles can be reused or expanded on.
- Helpful for QA testers — something that they can refer back to if something “in the wild” doesn’t look quite right.
- Having the markup embedded in the style guide helps multiple developers produce consistent markup for the front end.
We have found that components that we chose to not prototype in a style guide often ended up taking more time than expected. When the back end devs could see what our preferred markup was, they built our components very closely to what we prototyped. In the end, the pros outweigh the cons.
So what is the holy grail style guide workflow?
We’re still looking for it, but here’s some tips:
- Automate your workflow — style guides should compile every time you make a change to the site. We use Grunt for this.
- Use a boilerplate style guide — you won’t forget to theme anything that way.
- Use Drupal-specific markup in your boilerplate to make the transition easier. Use the Drupal style guide module for boilerplate markup.
- Try not to put too many components on the same page to reduce endless scrolling, ease testing for accessibility by tabbing through components, reduce the amount of javascript and images loading on the page.
- I haven’t yet, but I’d love to incorporate something like Ish to make each component responsive without having to resize the whole browser window when testing responsiveness.
What else would you suggest? Any pain points that you are feeling when using style guides with Drupal?
Or if you are just dipping your toes in, check out these resources for more good information:
Website Style Guides Resources
http://styleguides.io/
Style Guide podcast, Anna Debenham and Brad Frost
http://styleguides.io/podcast/
Front End Styleguides by Anna Debenham
http://24ways.org/2011/front-end-style-guides/
Design Components presentation from JohnAlbin:
http://www.slideshare.net/JohnAlbin/managing-design
Example style guides
http://ux.mailchimp.com/patterns
http://rizzo.lonelyplanet.com/styleguide
http://www.starbucks.com/static/reference/styleguide
http://www.bbc.co.uk/gel
http://primercss.io (Github’s style documentation)
Style guide comparison chart (google doc)
Responsive Deliverables
http://daverupert.com/2013/04/responsive-deliverables
Modularity and Style Guides
http://dbushell.com/2012/04/23/modularity-and-style-guides