For a design system to thrive and scale within a larger product ecosystem, central system team members can’t make all the decisions, design all design, code all code. Instead, a system practice must model and foster a federated community, opening the door to contributions far and wide. Don’t underestimate the effort to create and run these processes.
The open source community offers rich examples of well-documented contribution models, including Rust, Ember, and Node.js. What follows is an expansion of those ideas to broader considerations needed to serve a diverse design system community.
Code is truth. Therefore, a system must articulate the expectations and process for submitting and reviewing code, usually via pull requests. However, from the outside, a system isn’t just code: it’s design decisions, documentation, editorial word lists, the works.
Therefore, a system team should be ready for diverse contributions like:
In many cases, a systems team slots such contributions into the system backlog. Yet, even if taken up, such contributions still require back and forth to clarify requests, work on naming, and more.
Takeaway: Consider the range of disciplines and experience levels served by the system, define how non-coders submit works, and anticipate level-of-effort needed to integrate some contributions from the outside.
While contributions come in many sizes, you can usually classify them as small or large.
Small changes can include fixing a functional, visual, or accessibility defect, objective improvements (such as a focus state), performance, and browser support. For code, such changes can be submitted as a pull request to a designated branch in the system repository, reviewed, and implemented in the team’s normal workflow.
On the other hand, even a simple pull request (PR) can touch upon a system’s architecture, challenge widely applied conventions, or be “bigger than a breadbox.” Large changes can include:
In those cases, system team members must devote more effort to consider impacts and guide, collaborate with and review contributions.
Takeaway: Distinguish what constitutes a small change from a large change, and deflect larger changes to an established review process.
For more substantial changes, a system must empathize with contributors by offering an easy to understand process that doesn’t waste their time. I find inspiration from the Request for Comment (RFC) model described by Rust and Ember.
Such a process should step through discussion, proposal with preliminary work and an ultimately larger time commitment in delivering and reviewing a polished, testing, and acceptable revision.
Steps could include:
Takeaway: Have a process, avoid too many steps, separate understanding the change from making the change, and include clear milestones so a contributor sensibly invests their time.
System parts must often be higher quality and more flexible to address a range of concerns. Mature system practices document processes and checklists (as described in Component QA in Design Systems) that can quite intimidate an aspiring contributor. In addition, a contributors’s proposal may trigger requirements they didn’t consider or don’t care about.
System solutions must be more robust, adhering to conventions that can include:
Ugh! Suddenly, an ambitious contributor is overwhelmed by and frustrated with complexity. They may rescind the contribution, slow down, or negotiate with system team members to fill gaps, smooth rough edges, and complete the contribution.
Takeaway: Be prepared for difficult conversations to establish the meticulous quality required. If the contribution has validity, they balk, and you have time, ask if they are comfortable handing you the baton.
Ah, documentation. I’ve worked with some incredibly talented designers and developers over the year that struggle when faced with a documentation template in Google Docs. Often, they can’t get started, because they fear or acknowledge that they write poorly, avoiding the task so as to prevent their contribution at all.
Let’s face it, Material Design’s documentation is fantastically well-written with gorgeous Do’s, Don’ts, other imagery and demos. It’s like a design course! Salesforce Lightning’s component doc is incredibly detailed. Both are great examples to emulate. My teams also make doc components within our component libraries to document components. Head spinning yet?
So, it’s the contributor’s job to document their new work, using the system’s tools, to meet a certain level of quality. Right? Usually.
However, set expectations that documentation — like design and coding — is incremental. Your system’s threshold for “good enough” documentation is likely lower. Therefore, offer templates (such as a Google Doc they can copy) and a System Doc Editorial Guide to improve authoring efficiency and quality.
Takeaway: Make good documentation a required part of the contribution process, even if a more well-trained system team member does much of the work. Offer predictable models for building variations and authoring doc to smooth the process and get the most out of your contributors.
With so many contributions, it’s really up to the systems team to ensure they blend well. There’s often a normalize step – whether design, code, documentation, or artifacts from other disciplines – that follows to clean up the contribution. Other times, that normalization crops up as realizations after the fact.
Takeaway: Live with the reality that core members are responsible for maintaining an internally consistent system, and that curation takes effort. Your community appreciates you for it!
Whether it’s a new icon (easy!) or a complex combo box with hierarchical menus (hard!), every person I’ve met derives intrinsic reward for doing something that mattered. But it matters much more to them when a system practice recognizes their efforts. Here’s some ideas on how to recognize contributors:
The system of the people, for the people, and by the people indeed!
EightShapes can energize your efforts to coach, workshop, assess or partner with you to design, code, document and manage a system.