DESIGN SYSTEMS

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

For centralized design system teams, it is critical to create a contribution model so that external contributors can suggest ideas to be upstreamed to the official design system.

Jason Stevens

Jan 12, 2023

Publish the phases of your component development process

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.

Create an issue or ticketing system that allows anyone to submit a proposal to the component development process

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.

Make the submission system as self-serve and as automated as possible

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.

Establish guardrails for creating new components

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.

Establish a baseline of quality for upstreaming components

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.

Include demand or utilization as part of your upstreaming criteria

Consider developing upstreaming criteria around how often a component is utilized throughout the product. For example, if a component is utilized three or more times within the product, it is displaying sufficient “demand” for being upstreamed. The purpose of demand or utilization criteria is to make sure design system resources are applied to work that has the broadest benefit to the system as a whole, as opposed to bespoke ideas suggested by individual product teams. Of course, this should not be the only upstreaming criteria.

Utilize extensive documentation to more efficiently manage inquires and communicate guidelines

A cost-effective way to manage the expansion of your design system is through extensive documentation of your components and the patterns those components can create. Consider developing interface guidelines where you can go into detail about the future vision of how components can work together without actually building them in a composition or interface. By writing markdown documentation with screenshots, you can explain how components can work together without utilizing engineering resources.

Make it clear to the organization why an upstreaming process is needed

Typically, when a product team is building a new feature or component, they hyper-focus on that one specific use case, and limit their exploration of other use cases, which would ultimately slow them down. This is why partnering with a systems designer is critical. Within upstreaming phases, a designer and an engineer should stress test the item and apply systems-level thinking to verify that the component meets accessibility requirements, utilizes the methodology of how other components are built, is composable with other elements, doesn’t break anything, has sufficient documentation, and meets a defined level of quality.

Featured expert

Katie Langerman

Senior Designer, GitHub

With a deep interest in how code connects design to engineering, Katie Langerman bridges the creative/tech divide. She also runs Ladies that UX Boston, empowering women in design and technology.

DESIGN SYSTEMS TOOLS

Suggestion Box