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.
So what is a style guide?
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?
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.
- 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.
- 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
Style Guide podcast, Anna Debenham and Brad Frost
Front End Styleguides by Anna Debenham
Design Components presentation from JohnAlbin:
Example style guides
http://primercss.io (Github’s style documentation)
Style guide comparison chart (google doc)
Modularity and Style Guides