Despite the enormous positive effects design systems teams can have on fellow engineers and the organization as a whole, they often feel misunderstood or under threat.
Unlike product developers, who build features for customer end-users, and IT teams, who build systems for employee end-users, design systems teams build components and libraries for developer-users who use those components and libraries to build features for end-users. The indirectness of this path between effort input and revenue output is what makes design systems valuable and what makes it tough to demonstrate that value.
If this value were merely hard to measure, that might be okay. But measurement and recognition fuel the feedback loop that connects features to benefits and benefits to adoption.
This feedback loop means design systems teams have to be wary about assuming the mental models of either product developers or IT teams. Instead, we recommend a different group to learn from: Open source maintainers.
Open source development has major differences from 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 systems teams often find themselves drifting toward one of two extremes. They either act like stewards of a community-driven codebase that’s meant to organically evolve over time or they act like gatekeepers of a rigid product that’s meant to be controlled and protected.
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.
In a representative interview, 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. 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.”
Design systems teams don’t have the same volume of new users but they depend just the same on onboarding and deepening engagement. 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.
Fluin, for example, uses Stackblitz to host code samples within Google’s documentation – making it easy for developers to reproduce and share bugs. Jake Anstadt, Senior Enterprise Architect at Surescripts, uses Stackblitz to provide “visual representations of the proper ways of using our shared components as well as how to style them.”
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 make the mistake of not identifying either a goal or a mission. Maintainers work hard but users, contributors, and maintainers themselves can lose sight of the end goal – whether that be profit-based, mission-based, or somewhere in between.
The libraries that design systems build and maintain can struggle for similar reasons. If the end goal is unclear, developer users can struggle to understand what the design systems team’s primary purpose is.
Design systems teams, like open source maintainers, can address this risk by identifying values and building alignment with developer users by writing down and sharing those values.
Abdalla writes “One of the best ways to align values and motivations is to write them down” and 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 fastlane, a set of open source tools that automated iOS deployment (later acquired by Twitter and then Google), writes, in a post about scaling open source communities, how the original inspiration for a project can be lost in the work of maintaining it.
“The project was started because the author needed the software for themselves,” he writes. “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.