Disclaimer: This post is about my experience implementing living style guides – not an explanation of what a pattern library actually is… To find out more about pattern libraries, see Brad Frost’s article, Anatomy of a Pattern in a Pattern Library.
Back when I was a baby front-end developer, cramming poorly considered styles into a single stylesheet was my jam. Aside from how terrible I was at writing CSS back then, the generic style.css file would quickly slide into a state of unmaintainable horror. Any poor soul tasked with making changes to my style.css file would probably open it and be all like:
Fair enough. I know it was bad and I’m sorry.
Introducing Pattern Libraries
I like to think I’ve become better at writing CSS over the years, but up until recently, I still lacked experience working on larger projects with larger teams. As I shifted into working on single page apps using Agile processes, it seemed like the perfect time to improve my workflow.
Implementing pattern libraries for our web-based software felt like a step in the right direction. Doing so meant I could provide the developers working on these projects with:
- Proper documentation for existing styles within a project.
- More componentised and consistent styles that can be reused across projects.
Introducing a pattern library for each project also set a precedent for structuring our Sass files in a more modular way and writing CSS in a more consistent manner. Maintainability for the win!
The next step to implementing a pattern library was figuring out where to start…
Knowing Your Audience
When left unmaintained, a pattern library becomes rather useless. The best way to get buy-in from your team is to tailor the pattern library to their specific needs.
I had a few key factors to consider when deciding what would make pattern libraries most useful to our team:
- We currently have one full-time front-end developer (me!) who maintains the styling across all of our apps. However, my workload can fluctuate, so I’m not always available to help.
- Because we’re using Agile processes, the design of components changes frequently as new constraints and requirements manifest. Sometimes components get developed before they get designed (not ideal, but it is what it is).
- Teams usually work to fortnightly sprint deadlines with a client demo at the end of each sprint. Developers are usually flat out getting the functionality built and don’t have a lot of time to spend styling components.
- Developers aren’t as fond of CSS as I am…
After considering the list above, these were my requirements for developing pattern libraries for Media Suite to use:
- Documentation needs to be easy to maintain.
- Styles need to be well named and flexible so reuse is a cinch.
- Easy-to-use layout and helper classes would be needed to keep things tidy if design falls behind implementation.
- Developers shouldn’t have to waste time writing custom CSS for each new component.
Other teams may have different requirements but I felt this was a good place for us to start.
Finding the Right Tools
Now that I’d established that the cornerstone of a successful pattern library is the ease of maintainability, I went in search for what I’d later learn is called a “living style guide”.
The difference between a static pattern library and a living style guide is that while a static pattern library is maintained separately from the project it documents, a living style guide is generated from the comments in the CSS/Sass files.
There are quite a few style guide generators out there but in the end I went with Hologram. With a bit of configuration, you’ll have it spitting out a pattern library documentation site in no time.
I went with Hologram for a few reasons:
- It uses a YAML file for configuration and Markdown for documenting the styles in the comments – both of which we’re familiar with and are easy to work with.
- We’re currently using Ember to build most of our apps and the Ember build tools complement Hologram nicely.
- Because Hologram generates the style guide via the command line, we’re able to ignore the compiled style guide files and just commit the config files to the Github repo. I’ve also added a wee script to the package.json file so that our developers can just run npm run styleguide to compile the style guide and serve it up at localhost:8000 whenever they want to check something.
Document and Maintain. Rinse and Repeat.
As stated above, a large chunk of pattern libraries quickly fall out of date and are simply forgotten about. In order to maintain a successful pattern library, you need to show it the love, even when you’re in a hurry.
If you add or change a component, make sure you take the extra 2 minutes to check the documentation you’ve written is still accurate. You’ll try to convince yourself that you’ll come back to update it later but trust me – you won’t!
Reflect, Assess and Refactor
Once I’d figured out the technical side of getting a pattern library up and running, my main focus was on getting better at writing more modular and dynamic styles. As time goes on, I find myself committing far fewer new styles and relying on existing ones from the pattern library instead.
I’ve started maintaining a boilerplate pattern library as a starting point for new projects and as I figure out better ways of doing things, I make sure I update this boilerplate so that any improvements are being carried over.
One Year On…
It’s been about a year since I ventured into the land of the living style guide. While I’ve learned a lot along the way, I still feel like there’s room for improvement in the lifecycle of the components we’re building.
The life of a front-end developer sometimes feels like a constant struggle between deadlines, budgets, different technologies and evolving requirements. Using pattern libraries has turned out to be a great tool to ease this struggle and focus on what I love doing the most – building awesome things.
And finding cat memes.
Mainly the memes…
Banner image: Photo by The Lucky Neko on Unsplash
