Learning from failure: Thoughts on effectively managing design system contributions

When our design system reached its first milestone of maturity - a solid Figma library, some base level React components, and human resources (Product Manager, Sr. Director, and dedicated Engineers) we decided to adopt an InnerSource model with the hope that it would both speed up growth and create a sense a ownership (i.e. buy-in) in our organization. So, we set about developing a process for teams to contribute to our code base.

It was simple enough: We marked all component designs in the Figma library that didn’t have React counterparts as “Needs development,” and any time designers used one, their engineers could choose to contribute it. We developed some basic Contributing Guidelines and, when someone wanted to contribute, we assisted them with getting the library running locally.

Failure 1: Insubstantial contributing guidelines

How do you build a component? There are seemingly endless approaches to building React components. And there are as many ways to write code. We had some scripts in place to lint and type-check, and we had a template for Pull Requests, but we had no explicit directions or guidance on component structure, prop-naming, etc. Our guidelines lacked north star examples we could point to and say, “This is a perfect component. Model yours after this one.”

Failure 2: No formal PR review process

When pull requests started rolling in, we became keenly aware of how much our documentation was lacking. The first component I reviewed I thought, “This isn’t how we build components.” It wasn’t wrong, it was different. Which, unfortunately, for a design system library, is, in fact, wrong. So, my team and I started providing feedback in the GitHub PR review. The thread was long (painfully long) and thorough and it appeared as if several voices were shouting, “This needs to change! And this needs to change!” all at once. The review comments and suggestions were thoughtful, helpful, and more than likely overwhelming.

Failure 3: Blocking launch

It took weeks to get through all the reviews and re-reviews. By the time the component was merged and a new version was deployed, the contributing team had missed their launch deadline (on another occasion, a team abandoned their contribution to the library and just used the component they built directly in their codebase because they couldn’t wait for us - I don’t blame them).

Failure 4: Bugs for everyone

After the component was released and teams started to consume it, we started getting notified of various bugs. To be fair, we expect and account for human error, to discover some bugs after a component hits production - we dedicate resources to fixing them. That said, because we immediately added the component to the library, it meant that any and every team could consume it. The bugs we encountered could have affected one team but instead, they affected many.

Failure 5: No room for iteration

We have a healthy working relationship with design and understand that design is an iterative process. We expect that components will change and we’ll have to make updates. But there’s a short period of time directly after a design is implemented in production where, regardless of how much usability testing and prototyping was done ahead of time, iteration is at its peak. Designs can change quickly to adapt to unforeseen user behavior, missed accessibility features, etc. and it’s imperative that components are able to change quickly, too. When a component is deployed to multiple teams, it becomes more complicated and difficult to update. When several teams depend on a component, there are a healthy number of considerations to be made before making any change, even a small one.

So, what’s the solution? Where’s the “effectively managing design system contributions” part of this?

1. Have good, clear contributing guidelines. Be explicit and exhaustive. Provide examples. Remember your guidelines are a living, breathing set of documents that should be maintained alongside the rest of the library. Accept contributions for these guidelines, too!
2. Your team (the design system team) needs contribution processes for themselves. When someone reaches out to the team, who responds? When a PR is put up, who reviews? What’s the threshold for taking a conversation from a PR thread to chat or a meeting? When I catch myself about to leave more than 2-3 comments in a PR review, I reach out to my team to make sure we’re coordinated and not overwhelming contributors. On our team, we have one “support person” each week who is responsible for handling interactions with anyone who needs assistance. For contributions, we assign feature owners. As the feature owner, you’re not responsible for doing all the work yourself but, you’re expected to ensure the work gets done and it meets requirements.
3. Don’t accept contributions for untested components (you shouldn’t have untested components in your design library, either). Teams should build new components on their own, deploy them into production, iterate, and work out the bugs before contributing them to the library.
4. Never put yourself in a position where you can block a team. When it’s contribution time, don’t attach the work to any sort of deadline other than your own. Expect to refactor a lot of the contributor’s code to align it to your standards and for this to take some time. Some constructs that worked in the contributor’s environment will fail when you use them elsewhere. Your version of the component needs to work for all teams, not just one.
5. To get ahead of the curve, if you know a team wants to contribute a component, partner with them early and often to help them craft it in a way that reduces the amount of re-work when it gets added to the library later. Collaborate on tech design and review their PR’s. Again, don’t be a blocker but, get your hands dirty sifting through their component work and provide suggestions when applicable.

Parting thoughts

Managing a design system is hard work. It takes a lot of time, energy, commitment, and organization. You probably won’t get it right the first time, or the second time. Learn from your failures and please, learn from mine.