Three weeks ago, A List Apart went open source. The markup on the website is something I feel very close to. Over the years, if I’ve been unsure of how to mark something up, I’ve often referenced the HTML on A List Apart to see how it’s been done there because I know the people who work on it really care about semantics.
Uncertain of how I could help, I suggested to the team that A List Apart have its own pattern library. Pattern libraries are something I do a lot for client projects and I thought the site could really benefit from one.
It’s a technique I first saw former Clearlefty Natalie Downe develop for client projects back in 2009, and has been used by Clearleft as a front-end deliverable since. They’ve evolved a lot over time to include things like usage notes and code snippets.
A couple of days later, with some help from Mat “Wilto” Marquis, we had a repository for the pattern library up and running complete with a live preview.
Features of A List Apart’s pattern library
All the pattern files (snippets of markup) are in their own folder, and adding one in there automatically adds it to the library. I’m using some PHP from Paul Lloyd’s Barebones, his own blend of a pattern library, to output the patterns in the right format.
By breaking the site up into patterns, it’s easier to find those bits of markup. I noticed an issue on GitHub about there being no styles for dl, dd, and dt elements, and it took a while to find an example of them being used on the site. With a pattern library, all the elements that appear on the site are in one place so you don’t have to go searching round for them.
It also makes device testing easier because everything is on one page. I made a special patchwork view specifically for this, which is the same as the regular view, but all the patterns are at full width and it excludes the code and usage examples. It’s also quick to see if CSS changes to one pattern affect other patterns.
It’s a work in progress, and the first time I’ve built one after a site has gone live. (Normally I do them during development). There aren’t many patterns there at the moment, but I’ll be adding more. I’d also like to make it a one-stop-shop for grabbing site assets like logos.
Code for America’s Pattern Library
An example of a fully-fledged pattern library is Code for America’s, which I worked on with Clearleft.
The Code for America site is huge, and maintained by many different people. They wanted a redesign of their site, but delivering mockups of template after template would only be a tip of the iceberg and not really help them in the long-term. Templates are like a snapshot in time of a site, and they often can’t take into account when content changes or entirely new sections are created.
Since the project is so out in the open and encourages collaboration from the community, the code had to be documented well too.
We wanted to create a solid foundation that they could build upon, so we built them a system so they could build their own pages, the main deliverable for this being the Pattern Portfolio.
It encouraged a much more modular approach to development, the idea being that any pattern could be used anywhere on a template. Each pattern has its own .scss file, and the file name for that and the pattern’s markup are the same.
Designs for templates were still created to demonstrate how patterns could work together. After the Code for America team said they were thinking of using Jekyll for their site, I started using it (for the first time) to help me prototype these templates. It made code collaboration really easy because there was no database or required knowledge of PHP, so it’s now being used in production.
The site’s still being put together, and you can follow its progress on Github.
More pattern libraries
Some of my favorite examples of pattern libraries in the wild include those of Mailchimp and Starbucks. They’re comprehensive and well documented, they feel like the perfect deliverable because they help maintain code and design standards. They acknowledge that websites change over time and make it easier to make those changes without breaking stuff.
If you’re inspired to learn more, I have a bookmark collection of pattern libraries, and I’ve also written a pocket guide about them. Please chime in with your own favorite pattern library examples or resources in the comments as well.
Love seeing people share more pattern libraries/living style guides they’re working on.
For anyone looking to build their own pattern library/living style guide I’d recommend checking out Style Guide Boilerplate or Pattern Lab.
I love the concept of pattern libraries (and the use of Pattern Lab specifically, as Brett mentioned).
I’m wondering, though, if anyone has a good workflow for iterations and updates to your styles over time. Do you apply the changes to the pattern library first to test compatibility before shipping it to production, or vice versa? It seems like twice the work – though the work pays off in having that extra resource.
I love pattern libraries because they make me so much faster.
I created a project to bootstrap the creation of pattern libraries. Still in it’s infancy, but still worth a look:
https://github.com/resource/fabricator
I love this, Anna! I’m working on my personal blog right now and keep getting bogged down by how something should be marked up. I know at a certain point it becomes more of a personal preference, but this helps so much.
Great article! I’m working on a pattern library for the company I currently work for and this is going to be very useful. LOVE the Code for America pattern library.
Great insights on pattern libraries. This is gone be very useful. Thank you Anna!
A much more professional approach than my personal attempts to a similar system over the years. I’m curious about the maintenance as Josh Larson mentioned above. Sass files can be dynamically read from the actual work files, but what about markup?
Pattern Libraries are a great idea. I keep adding to mine as I work on various projects. http://www.suture.net/framework/components
So while I understand the rationale behind pattern libraries in terms of being able to speed up development by reusing common elements etc. I would really like to understand how to integrate it into my workflow.
I see that a lot of people have a page with all their patterns and I wonder how they work with that in real life. Is pattern library just another word for a collection of snippets?
For instance Rick Cox, how do you apply your framework into daily work?
very good
Hi Johan, the workflow varies depending on the usage. For me the boundaries are a bit blurred between Framework, Snippet Library and Documentation, because I use it on multiple sites.
Ahh I see Ricky Cox, that answer actually helped a lot. You see I also have my snippets, I use them freely in my IDE. But they are all saved in a ‘framework’ css file which i include in all my projects and then build/style on top. Hence I could have myself a pattern library in a matter of minutes. For instance if had to engage other team members or for use as documentation.
Thanks for the clarification
Is the intention that the pattern library would refer to the same stylesheets that the production site uses? I didn’t see anything that deals with having to overwrite styles that are specific to the library but not the site itself. I’m curious about the strategy in finding a way to illustrate patterns for a site built with modules whose styles that are different depending on what part of the template that module lives in. Does the entire template then need to be illustrated within the pattern library?
I dig the idea of Pattern libraries to promote code reuse and maintenance. Thank you! I will checkout your book too.
As always a great read form Anna 🙂
I’ve always found Pattern Libraries very, very interesting but I never quite gotten around to making one from scratch. I always tend to either tweak someone elses or skipping them entirely (the latter I’m sorry to say being most used solution).
Any “Pattern Libraries for Dummies”-tips for guys like me, who really want to start from scratch?
/KR
If you are using Sass and Grunt then I would definitely recommend taking a look at Sassdown. It automatically generates a styleguide (similar to Paul Lloyd’s Barebones) from Markdown comments in the Sass partials. It takes all the effort out of creating a styleguide with the added benefit of well commented code.
Thank you for a nice read and for sharing your experiences, Anna. I feel like lots of designers/developers will integrate some sort of pattern library into their workflow. Did you create the pattern library for Code for America in parallel to the development process or was it sort of a subsequent documentation after the design and development work was (mostly) done?
All the best!
I was wondering, is there a tool for creating atomic design patterns which has the relationship “Used in” and “composed by”? So if I need to update an atom, the change is reflected on the molecules and higher levels immediately. I thing that is missing from the Patterns lab tool.
Hi!
This is awesome. I’m looking for a way to include css and javascript behaviors along with the physical presentation; what would you suggest? This would be to allow (soon to be) hires to reuse the code on new versions of a site (we do approximately 10 rebuilds/versions of a site per year).
@Euge,
I’m in the process of building a pattern lib for my company and am running into the same issue. I can put it all in a wiki allowing me to cross reference, but that doesn’t allow me to have inline examples, which I see as important.