Although design systems teams greatly benefit both engineers and the entire organization they serve, their value is often misunderstood and as a result they commonly feel under threat.
Unlike product aligned developers, who build features for external end-users, design systems teams build libraries for internal developers who then use those libraries to build products and features for revenue generating customers. The value of design systems comes from the multiplying effect they have on other teams’ productivity, and that indirect contribution to revenue can be challenging to demonstrate.
If the challenge of measuring and demonstrating the value of design systems was a purely academic excercise, then you would be forgiven for losing interest at this point in the post. However, in high performing organizations measurement and recognition fuel the feedback loop that drives adoption and continued investment.
This feedback loop means design systems teams have to be wary about assuming the mental model of product aligned development teams. Instead, we recommend a different group to learn from: Open source maintainers.
Open source development has major differences from corporate design systems of course, but a few key similarities make it a useful comparison: Both groups face pressure to expand adoption; both groups are motivated to deepen usage among existing users; and both groups need to support a large, diverse userbase with limited resources.
Here, we’ve gathered 5 of the best lessons design systems teams can take from open source and apply to their work.
1. Choose a model and embrace the tradeoffs
Design system teams usually gravitate towards one of two extremes: stewards of an organically evolving community-driven codebase or gatekeepers of a tightly controlled product.
Open source maintainers are likely more familiar with this tension than anyone else and different projects and maintainers have pursued either model or found a balance that works for everyone involved.
Despite how long open source has been around, these models weren’t well articulated until Nadia Eghbal wrote Working In Public in 2020. In the book, Eghbal breaks open source projects down into four major models:
- Federations: Projects with high contributor growth and high user growth, such as Rust, Node.js, and Linux.
- Toys: Projects with low contributor growth and low user growth – essentially personal projects.
- Stadiums: Projects with low contributor growth and high user growth, such as Babel, Bundler, and RSpec.
- Clubs: Projects with high contributor growth and low user growth, such as Astropy, a package that provides functionality and tooling for Python developers working in astronomy.
The latter two models parallel two models for design systems: closed projects, where a relatively small central team prioritizes, builds, and supports most of the work, and open projects, where a central team is surrounded by rings of engineers contributing to the work.
The primary benefit of identifying a model you’re operating in is that it allows you to see tradeoffs. By making analogous comparisons, design systems can identify tradeoffs they might not have been aware of.
Closed projects and stadium models both benefit from greater contributor consistency and quality. This structure often enables greater quality as a result of greater focus and control, but without a widespread community of contributors, there can be a lack of feature coverage.
Open projects and club models can turn the previous disadvantage upside down by involving contributors more directly. Contributors and users overlap, often creating more participation.
In both cases, there are tradeoffs: A closed project operating within a stadium model maintains a lot of control but often loses engagement, whereas an open project operating within a club model creates more engagement that can, in some cases, support the work and in other cases, burn out the people in charge of maintenance.
2. Prioritize maintenance and restrict scope creep
In recent years, maintainer burnout has become one of the biggest topics in open source. Research shows that 16% of projects end up abandoned and burnout has become one of the clearest causes.
Clive Thompson, author of Coders: The Making of a New Tribe and the Remaking of the World, talked to Jacob Thornton, one of the creators behind Bootstrap, about the growing issue of maintainer burnout. In the interview, Thornton talks about how busy he’s gotten, sharing that he frequently “couldn’t grab dinner with someone after work” because he feared letting users down.
Thornton said he felt guilty and many open-source maintainers feel the same.
You weigh that joy against the knowledge that any new project will necessarily steal time from old projects.
- Nolan Lawson
Open source maintainers are often drawn into an ever-expanding amount of work and formerly small projects can start suffering from success. Even though design systems teams can clock out in a way open source maintainers often struggle to, similar kinds of burnout prevention can help design systems minimize stress and maximize focus and impact.
A core dynamic that causes burnout is the tension between maintenance and growth. Design systems teams, like open source maintainers, often find themselves stuck between the need to maintain core functionality and the desire to build new functionality.
Nolan Lawson, a web developer at Salesforce and a major contributor to PouchDB, wrote a post called What it feels like to be an open-source maintainer that touches on this point. In it, he writes “You can still recall the thrill of creation, the joy of writing a new project from scratch and solving a previously-unsolved problem.”
“Now,” he writes, “you weigh that joy against the knowledge that any new project will necessarily steal time from old projects. You wonder if it’s time to formally deprecate one of your old repos, or to mark it as unmaintained.”
The emotions that come from building something new and the seeming practicality of fulfilling a user’s request make it tempting to build, build, build, and rarely maintain.
Here, advice from Steve Klabnik, community team leader for the Rust team at Mozilla and owner of the official Rust community documentation, comes in handy. In a post about how to be an open source gardener, Klabnik writes that “my most valuable contributions haven’t been code. Writing a patch is the easiest part of open source. The truly hard stuff is all of the rest: bug trackers, mailing lists, documentation, and other management tasks.”
When Google engineers were developing Angular, for example, the vast growth in bug reports became a huge problem. It took, on average, more than thirty minutes for the Angular team to review a bug report. The problem only threatened to worsen as the rate of developers visiting the Angular and Material documentation rose to 1,500,000 every month.
If you don’t tend your garden, you’ll get weeds.
- Steve Klabnik
A browser-based IDE became a core part of their maintenance system because it enabled them to create fast, secure, and consistent development environments for the reproduction of bugs. Stephen Fluin, a developer relations lead at Google, reported that a browser-based IDE “significantly reduced our team’s support burden for bug reproductions and enabled rapid innovation.”
Maintenance can’t merely be one item to be prioritized amongst a list of others. As Klabnik writes, much of the work that sustains maintainability isn’t sheer maintenance but work that creates systems to enable maintenance.
That’s why Klabnik emphasizes gardening as a mental model. He writes that these efforts “only work if you keep at it: if you don’t tend your garden, you’ll get weeds. […] Without someone actively paying attention, it’s only a matter of time before things get unseemly.”
3. Document, document, document
Open source maintainers have learned that the best way to scale their projects – including growing the number of contributions, increasing the quality of those contributions, and making more potential contributors feel welcomed – is to create lots of great documentation.
Similar to the previous lesson, prioritization tends to drift toward building. But in the wake of forward progress, documentation can suffer – onboarding documentation especially so.
Safia Abdalla, a Microsoft engineer and a maintainer on the nteract project, writes that “Many engineering teams underinvest in their onboarding and development workflows.”
Open source projects, she writes, “don’t have the privilege of neglecting this experience for prospective contributors; their success depends on a healthy stream of new people.”
Though design systems teams may not onboard users at the same rate as open-source projects, effective onboarding and engagement are equally crucial. If the company is growing and the proportion of engineers using a design system team’s component library dwindles, the impact of design systems work will dwindle too.
To make projects more approachable and better capable of growth, design systems teams and open source maintainers need to create more documentation and better documentation.
Many open-source maintainers suggest documentation types that design systems teams can borrow. Orta Therox, a Typescript engineer who maintains a third-party dependency manager and the most popular Objective-C testing framework, writes that he committed to including three “buckets” of documentation in future work:
- Highlight pages (intro pages, app pages, team pages)
- Guides (tutorials, overviews, FAQs)
- Reference (Command-line interface, APIs for developers)
Together, these documentation types “make it pretty easy to separate where people should look depending on what they’re looking for.”
Ash Furrow, formerly an engineer for the open-source app Artsy and now an engineer at Shopify, focuses on readme documentation in a post on building popular projects.
According to Furrow, a good readme includes the following elements (though we’d add that most documentation benefits from at least some of these elements too):
- A description of the problem your library solves.
- An explanation of how your library solves the problem in a really nice way.
- A very brief example, with a link to more examples or documentation.
- Installation steps and where to go if they have a question.
- A GIF of the library in use.
And as Furrow describes, great documentation goes beyond text on the screen.
For instance, StackBlitz is used to host code samples in Google’s documentation, making it easy for developers to reproduce and share bugs.
As Jake Anstadt, a Senior Enterprise Architect at Surescripts put it: with great documentation supported by visual, interactive components “developers are no longer building UIs by copying code from existing apps and modifying it in all sorts of unpredictable ways.”
4. Identify values and build alignment
Open-source maintainers often neglect to clearly define their goals or mission. This oversight can cause confusion and disengagement among users, contributors, and even the maintainers themselves, regardless of whether their aim is profit or purpose-driven.
Similarly, if a design system’s objectives are not clearly stated, it can become difficult for developers to grasp its primary function and value.
To mitigate this risk, design systems teams, like open source maintainers, can build alignment with their users by identifying and clearly communicating their core values and objectives.
Again referencing Safia Abdalla, a maintainer on the nteract project: “One of the best ways to align values and motivations is to write them down.” She shares a few ways to do so, including a code of conduct (CoC), a content style guide, a README, and contributor workflows. Instead of choosing the perfect method, Abdalla emphasizes “conveying these values in as many avenues as you can. It’s better to risk redundancy than to risk contributors missing the message.”
Jeff Lindsay, who pioneered webhooks and developed open-source tools and libraries like logspout, registrator, localtunnel, JWT, and RequestBin, wrote about how documenting goals helped project growth in a post called Leadership, Guilt, and Pull Requests. At the time, Lindsay was struggling to keep up with the demands from Dokku, resulting in an “incremental path of maintaining the status quo” and feelings of “sadness” and “guilt.”
But then, Lindsay writes, he “did something different.” He documented his goals – what he wanted and why – and maintainers started moving the project in that direction (much to his surprise).
The challenge is to still somehow use the product to feel the user’s pain points, and realize what to focus their time on.
- Felix Krause
Alignment has to be bottom-up as well as top-down.
Felix Krause, creator of fastlane, a set of open source tools for automating iOS deployments (later acquired by Twitter and then Google), writes about how a project’s original vision can often get lost amidst the ongoing maintenance work.
In a post titled scaling open source communities he explains “The project was started because the author needed the software for themselves. Suddenly they work on the open source project full-time, stopping the activity they’ve been doing before. With that, they stop being a user of their own project. They are not in their own product’s target group anymore.”
Design systems teams and open source maintainers can communicate a vision but they also have to keep in close enough contact with users that they can actually understand what users need.
“The challenge,” Krause writes, “is to still somehow use the product to feel the user’s pain points, and realize what to focus their time on.” He recommends using the project regularly or at least periodically onboarding to the project.
5. Become an advocate
Design systems teams – like open source maintainers – have to be part developer, part marketer, and part customer support.
Jacob Herrington, former core team member at Solidus and contributor to Dev.to, has written about the shift from software engineer to open source maintainer, and why “soft skills” play a key role. “From the time I’ve spent as a maintainer,” he writes, “I’ve learned that there is a non-technical aspect of maintainership that could arguably be more important than the software engineering skills that usually come into play: communication skills.”
Marketing, anathema to many developers, is essential but Herrington is quick to point out that he doesn’t mean marketing fluff: “Understand that I’m using the word marketing to describe a set of tactics used to connect people with the best solution to their problem; nothing malicious, the opposite.”
Design systems might be even slower to recognize the need to embrace marketing because open-source maintainers, for the most part, have much bigger markets whereas the market for a design systems team is generally housed in the same Slack workspace. But adoption still separates the least successful from the most, making some kind of marketing necessary.
Herrington points out that “Healthy projects should have some degree of adoption” but that this doesn’t have to mean “hockey-stick growth.” Instead, he writes, “diverse communities and new contributors usually improve Open Source projects, so it makes sense that maintainers worry about the adoption of their projects.”
Similarly, design systems teams should worry about who’s adopting and using their libraries (such as new engineers vs. tenured engineers) and to what effect they’re using those libraries (faster rate of feature completion, for example). As Fluin, one of the people doing the design systems work that supports Angular at Google, says “For frameworks and design systems to succeed, they have to be incredibly easy to adopt.”
Build narrowly and learn widely
Across these examples, two meta lessons emerge that might be more important than any of the other lessons: Build narrowly and learn widely.
Even though the ultimate impact of design systems work will be wide and the benefits will affect many customer end users indirectly, focus on building for your developer users. Like many open-source maintainers, you’re in the business of enabling other developers to build.
The narrowness of your building will benefit the most, however, from wide learning. The potential impact of design systems work is enormous but the path toward success isn’t clearly mapped out. To forge a path, learn from a diverse range of sources (such as open source maintainers) without being afraid to steal one idea and ignore another.
