Guide #025: How to prepare your design system for external contributions

Develop and publish requirements for moving components from an idea stage to officially being part of the design system. Generally known as upstreaming, this process should have phases and clear criteria, or a checklist of requirements, for each phase. Examples of phases include Experimental, Alpha, Beta and Stable. Once an item is built as Experimental for a specific feature and there is sufficient demand from other teams or use cases, the item becomes eligible for upstreaming.

Build a submission system that allows anyone to suggest a new component or pattern. This system should reflect the stages of your component development process and house the criteria for each stage. Submitters should be able to see the requirements for all stages so that they can select the appropriate stage for their idea as well as look ahead at upstream stages for what future requirements will be.

The submission system for proposing ideas to your component development process should be readily available and widely accessible. For example, utilize a Slackbot to respond to Slack message requests with instructions on how to access and complete the submission system. The design system team should maintain a practice of regularly reviewing submissions against upstreaming criteria and prioritize which ideas should be worked on next. Efficiencies include asynchronous review of submissions, attaching similar requests to the issue or ticket and documenting any relevant context or historical knowledge.

Guardrails should be defined for the creation of new components. Some teams call this the Experimental phase within their component development process. These guardrails should encourage the creation of generic components as opposed to feature-specific ones. If a new component is highly specific to a feature, documentation within your submission process should encourage either the building of a custom compositional component using existing design system components or the breaking down of the new component into smaller components. Other guardrails might include rules around property naming and limitations to minimize the occurrence of teams adding highly specific properties to a generic component.

Building components of “high quality” should be part of the criteria for being upstreamed into the system as a whole. The design system team should care about quality components from both the end user perspective as well as the developer experience. Building components that are easy to use, that are composable, that meet accessibility standards, and that work for as many scenarios as possible constitute some of the criteria for being of high quality. Whenever possible, codify quality requirements with linting or automated pull request checks.