a component library case study

ActBlue is a nonprofit tech org that enables small-dollar donors to contribute to progressive candidates and and organizations. We offer a suite of tools both for those looking to donate as well as those looking to fundraise. With multiple user types, multiple products, and product teams working on said products, our designs and code were both starting to drift.

Enter the design system, a single source of truth for resusable design patterns. Typically made up of both a UI Kit for designers to use in mock ups, and a Component Library for engineers to use in code, they offer multiple benefits to designers, engineers, and a tech org as a whole. To briefly sing their praises, design systems speed up both design and development times and help us provide consistent user experiences across multiple products and code bases. They can help ensure that your products are more usable and accessible—if you design and develop a component to be accessible from the start, each usage of that component is also accessible by default. They also limit the amount of CSS that has to be written (one and done!) and I know a few engineers who LOVE this benefit!

Our tiny design team (just myself and one other) knew that our orgazation had a lot to gain from creating a shared design system, and so we combined forces to create Blueprint, ActBlue’s internal design system.

the mobile view of a donor’s account
the mobile view of a donor’s profile
the mobile view for a donor without a saved profile
the mobile view for adding a new credit card

Our design twosome was tasked with a big, greenfield project. We were to design a responsive, downloadable web application (often called a Progressive Web App or PWA for short) for ActBlue’s donor base. The app (internally known as Donor HQ) needed to allow logged in donors to review their contribution history, manage recurring contributions, update their profile, edit payment methods, and more. This was a big project with many views and UI elements, and the first opportunity we had to collaborate so closely on something together. It was the perfect opportunity to get the design system started.

donor’s profile, a feature I took the lead on
the desktop view of a donor’s profile
recurring contribution, lead by my partner
the desktop view of a recurring contribution

The two of us collaborated extremely closely throughout the whole process, playing off of eachother’s strengths. Looking back, it’s one of the best collaborations I’ve ever been a part of. We each took the lead on designing different features within the new application. We shared designs often, bouncing off of eachother. Something I designed would inspire her work, and vice versa. Sometimes we’d even trade features if we were stuck, let the other person take a stab at a problem we were unsure of. And the constant collaboration helped us think about the entire application in terms of the design system. We made sure UI elements looked and behaved consistently unless there was a reason for them not to. The other designer took the lead on turning many of our designs into reusable components in Sketch.

fundraising, lead by my partner
the desktop view of a donor’s fundraising overview page
contribution history overview, a feature I took the lead on
the desktop view of a donor’s contribution history overview page

As we worked on designs, we shared our vision for a design system with our Engineering Manager. We convinced him of the benefits, and were given the green light to use the development process of Donor HQ to create a pilot version of Blueprint’s component library. The fact that I am front-end engineer as well as a designer helped our cause a bit, as I promised to handle the development of all of the resuable components we wanted to build.

We pulled in another engineer to help us set up a new repo for Blueprint’s component library, as well as setting up the build process so that all of ActBlue’s current and future applications could pull in components. We decided to build the library in React, as it’s what our more modern products were written in and is what we’d be using for Donor HQ. We also checked with teams who work on our Ruby application, and learned that they’ve even begun mixing React into their Ruby templates.

a screenshot of our component library in Storybook today
a screenshot of Storybook, featuring the Alert component

Like many other teams building component libraries, we utilized Storybook. Storybook is a wonderful tool that acts as both a "work bench" and "store front" for your component library. It’s a work bench as it gives you a place to put your components and view them in the browser while you work on creating them. It even offers tools to help ensure that what you’ve created is accessible! But it’s also a store front, because the "stories" you create for each component become documentation for future developers who are looking to use said component. You can set up stories so that they offer documentation as well as a way to generate code snippets that can simply be copy and pasted.

I also went ahead and got us set up on Netlify, everybody’s deploy tool (or at least mine!) This allowed us to deploy our Storybook site so that any engineer or designer could check out the available components. Netlify also offers this super awesome work flow that auto-deploys every PR and its commits to a unique URL, so that those reviewing a PR could simply click the link in the PR to see changes!

our Button component in Sketch, created by the other designer
a breakdown of many variations of a button
my Storybook implementation of the Button, mapped to variations we worked out together
a screenshot of the Storybook page for the Button component

Once we were all set up, I was able to start building components! The other designer and I continued to collaborate closely. As I began building and styling the reusable components we had designed together, I’d go to her with new technical limitations or missing variations or questions like "how should we handle the focus state" and we’d work it out together. We did this while not only thinking about what would definitely be built, Donor HQ, but also considered future potential use cases for each component. We did our best to balance reusability without overoptimizing and wasting time.

a story highlighting a specific use case of the SectionLink component
a screenshot of Storybook, featuring the SectionLink component
a second story with a second use case
a screenshot of Storybook, featuring the SectionLink component

As I was developing these reusable components, another engineer started building out Donor HQ. He utilized the components I was building, and was able to provide real-time feedback on the developer experience and limitations he ran into, which I was then able to address. He and I also had a really great collaboration experience together.

Using Donor HQ to create the pilot version of our design system was a huge success. We released an application that was usable, accessible, and extremely polished. And the best part was, all of those wonderful little bits of UI were ready and waiting for others to utilize. Releasing this application also got other teams interested in using Blueprint—probably because it looked so dang good! Other teams started utilizing Blueprint in their own projects. First with small bits of UI, and eventually with larger features. The value of the component library started to make itself apparent. Engineers told me they hardly wrote any CSS anymore, and Product Managers started noticing that features built with Blueprint were automatically more accessible, because I built each component with accessibility in mind.

a keyboard-accessible dropdown component I developed
a screenshot of Storybook, featuring the Dropdown component

The adoption of Blueprint at ActBlue continues to grow. We’re running into some new problems with our workflows, but they’re to be expected and nothing to be concerned about. For example, as our organization continues to grow, more and more teams of engineers are utilizing Blueprint. Originally it was something that the design team owned, but our team is small and our time is limited. We had other work to get done, and couldn’t fix every bug request that came in nor build every new component that a team needed. Plus, some engineers actually liked and missed writing CSS, and wanted to be more involved. Engineers kept asking me "How do I join team Blueprint?!" Additionally, although I consider myself (and now the other designer, who I had the pleasure of mentoring with her coding skills) capable front end developrs, there were some issues creeping up that we wanted other engineers help with. For example, performance issues because of the way Blueprint components were exported and imported, as well as coming up with a testing strategy.

It was time to get other engineers involved not only in the usage of Blueprint, but also the creation and maintenance. I brought this up with the other Engineering Managers, and advocated for more resources. We settled on a three-month "working group," in which we were to choose a handful of engineers to come together and decide on and solve a few concreate problems. I saw it as another pilot program, but this time for Team Blueprint!

I reached out to everyone who had previously shown interest in working on Blueprint. Together we decided on 3 goals: 1. Fix the performance issue by making Blueprint "tree-shakeable," meaning you could import a single component at a time, rather than the whole library, 2. Decide on and begin to implement a testing strategy, and 3. Review common CSS that was still being written as far as layouts were concerned, and create some new components that could replace that CSS.

the Page component, created by a member of the working group; you might have noticed that we used this layout in our original DonorHQ designs. At the time, we were unsure if it would be reused in other applications, so we held off on adding it to Blueprint as not to over-optimize.
a screenshot of Storybook, featuring the Page component

The working group absolutely killed it. They were able to make Blueprint tree-shakeable without any breaking changes. The documented a robust testing strategy, added Percy visual regression testing, and wrote jest tests for many of the more fragile components. And they created new components to replace one-off code in multiple applications. I don’t take credit for any of the above work. It was all done by the amazing members of the working group. My role was mainly in helping to facilitate communication, and getting out of their way ;) I was so happy to see so many engineers excited about contributing to the component library, and doing a damn good job.

Once the goals were met and the 3-month working group came to a close, I started getting the question "what now?" The other Engineering Managers saw the working group as a way to fix some important issues with Blueprint, but I saw it as a pilot program for a long-term maintenance team. Other larger organizations have entire teams dedicated to maintaining their design system. Though we’re not there yet, it was apparnet to myself, my design partner-in-crime, and the other engineers that we needed to head in that direction.

I met with the members of the working group to get their take on the future of Blueprint. We discussed a lot of really awesome ideas, my favorite one being to model our internal component library off of open source projects. Anyone at ActBlue can be an author, submitting PRs for new components, changes to components, and bug fixes. But we also select a few long-term maintainers to review code and oversee the long-term vision of Blueprint. I wrote this up in a proposal, and shared it with the other Engineering Managers for thoughts and comments.

The future of Blueprint is still TBD as this maintenance plan is still being discussed. But the benefits of a shared component library have made themselves clear. People are enthusiastic about Blueprint. Even if we still have a few formalities to work out, Blueprint is here to stay. And I have no doubt that our products and code will be better because of it!