Component libraries are living inventories of user interface elements (components). Also known as style guides or pattern libraries, they serve as a canonical design and development guide for every digital property within an organization. Referencing and reusing their code then makes building each new experience easier, faster, and more consistent.
Chromatic recently embarked on rebuilding the front end of a client's online presence. Fortunately, the client was quick to understand the importance of starting with a component library. I hadn't yet built one for a client, but I'd heard of a few tools used to do so while following the chatter around them. What I didn't realize was just how many helpful tools there were.
The most valuable starting point I found was styleguides.io, built primarily by Anna Debenham and Brad Frost (the authors of the recently released Front-end Style Guides and Atomic Design, respectively). After browsing a few examples, I started digging into the extensive list of tools. It didn't take long to realize that there were no obvious, one size fits all solutions.
A bit overwhelmed, I realized I needed to first define what I considered most important for this specific project. I could then use those considerations to evaluate each tool. I settled on the following list, which I share with hope that it helps others make a similar decision.
What to consider when evaluating tools
Popularity and community support
The relative popularity and support of open source projects is extremely important to me. I start by glancing around the GitHub repository: the number of stars, forks, commits, contributors, and issues. I want it to be battle tested. I also want to see recent commits and releases. I don't want to bet my client's money on a project that isn't mature, or perhaps it is, but has sat idle for a few years (an eternity on the web). If I find and/or fix a bug, I want to be able to expect a response, and to know that any shortcomings may still be a work in progress.
Integration with the specific project
As mentioned in On Building Component Libraries by Mark Perkins (another thought leader on this topic), "Integration is hard, so figure it out first." I don't want to pick a tool that adds too much complexity to the client's existing workflow and infrastructure. I want to find the tool that provides the least amount of friction and provides value far into the future. Maybe even find the Holy Grail, where a website's front end can use the same CSS, JS, and/or template files as the library.
Developer experience and documentation
Even if a tool fits well within the client's workflow, developers will not maintain it if it isn't easy to do so. The development team must be the champions of a component library. As developers roll on and off the project, they will not fight to keep it if they only consider upkeep a burden. It shouldn't take hours of internal READMEs to understand the library's directories and files. There should also be a wealth of documentation online. Modifying and extending the library should be anything but a mystery.
Aesthetics and user experience
The component library should become a useful resource for many throughout the client's organization. If it becomes a complex interface built by developers for developers, it won't be easy to reference, and it will not be widely adopted. Additionally, like many before us, we intend to one day make it publicly accessible. This means that it needs to represent the client's brand and, quite frankly, look good while doing it. Bonus points for being able to integrate the client's branding.
The ability to build and preview page prototypes
Along with listing the components, we want to use the tool to construct and preview page prototypes. These prototypes, ideally free of the cruft that creeps in to slow a website down, will inform performance benchmarks and budgets. We will then measure against these budgets as we integrate the components into the production website. This will also make it much faster to preview (in the browser) what a new type of page will look like before implementing it.
The ability to house additional documentation
We hope for our component library to evolve into a bit more than a reference for code snippets and styles. Brand guidelines is a good example. Regardless, we want the flexibility to add pages of textual documentation. Many component library tools include this feature, but not all do. Sure, one could argue that is beyond the scope of a component library. But using one less tool and having one less place to reference is a win in my book.
Tools we evaluated
While this post isn't about what we landed on, I'd imagine some folks are curious. So with those criteria in mind, we narrowed down our list to 3 tools built with NodeJS (easiest to introduce into the client's workflow). Those tools were Pattern Lab, Fractal, and Astrum. All are impressive tools, but each had strengths and weaknesses when it came to our needs.
Pattern Lab
With roots in Brad Frost's Atomic Design, Pattern Lab is easily the most popular tool and receives the most support. It is flexible and has great documentation. While its toolbar has great responsive preview functionality, I wasn't excited about the aesthetics of it. Pattern Lab also didn't fulfill our need for additional pages of documentation.
Fractal
Brainchild of Clearleft's Mark Perkins, Fractal has an extremely simple directory and file system. It is also flexible, has great documentation, and a great design. The interface for viewing component information is also quite nice. It appears to be the least used, but it is actively maintained (with a new version in the works).
Astrum
Astrum fell in the middle of the road for me. It, too, is actively supported, and is lightweight and flexible. It's well designed and has the ability to add pages of documentation that look great. Unfortunately it didn't seem to have the ability to prototype pages and view them within the interface.
Fractal saves the day
We went with Fractal. I was a bit hesitant to choose a less popular tool with a looming major upgrade, but its development is top notch. I was also happy to see that others have made the same choice. It has the features we need, and I'm happier than I should be with how simple the directory and file structure is. The documentation has also been super helpful thus far. We've customized it with our client's branding and are ready to roll.
Be sure to reach out to @ChromaticHQ or @guschilds on Twitter if I've missed anything or if you have any questions!
