Making a Contribution

Establishing Shared Value

One of the Design System’s principles is to include what’s shared and omit what’s not. To ensure the System provides the highest shared value to all product teams, contributions require an established need across three or more product teams to qualify for consideration.

When proposing a change, either small or large, identifying other teams with a shared need for the proposed feature or enhancement helps determine requirements and streamline the overall contribution process. The #mds-design and #mds-engineering Slack channels are a great place to connect with other teams to gauge shared need.

For all contributions, communication and transparency are key. Contributions should be thoroughly vetted with our design and engineering communities, leadership, and the MDS team to ensure alignment.

If you’re interested in making a contribution but don’t know where to start, you can find a list of open proposed components and enhancements on our Request a New Part page.

Small Changes

Small changes are contributions that improve or expand our current capabilities without posing any risk of disruption to product teams currently using MDS. If a small change is really a large change, the System team may decline the change with a polite request to submit a Request for Comment first.

Design

Examples of small design contributions include:

• Creating a small version of an existing icon.
• Expanding or updating existing design documentation.
• Creating a new Constant or making minor adjustments to an existing Constant.

To submit a small design contribution:

1. Discuss your contribution with the relevant segment owner.
2. Create a Small Contribution ticket with acceptance criteria for the contribution you’ll be making and post it on Slack in #mds-design for review.
3. Gather and incorporate feedback from the wider design team using a visual or UX critique session or Slack.
4. Add the outputs of your work—for example, an SVG for an icon or a link to a Word document—to your ticket and coordinate with the MDS core team to include your contribution in an upcoming release.

Code

Examples of a small code contribution include:

• Improving a component’s accessibility support by adding an additional ARIA tag.
• Fixing a defect based on established quality criteria, such as a functional or visual defect.
• Additions that improve component quality or completeness, such as performance or improved browser support.
• Expanding or updating existing technical documentation.

To submit a small code contribution:

1. Create a Small Contribution ticket with acceptance criteria for the contribution you’ll be making and post it on Slack in #mds-engineering for community review and feedback.
2. Request access to the MDS repository by emailing [email protected] or reaching out via Slack in the #mds-engineering channel.
3. Open a PR against the /develop branch with your fix and add 2+ members of the MDS core team as reviewers.
4. Address all feedback and merge your PR.

Large Changes

Large changes are contributions that substantially impact the design, build, or tooling of the System. These changes require consensus among the System core team, segment owner, and contributor—as well as thorough vetting within the product organization. Begin by proposing such changes via a Request for Comment. After receiving approval, follow the MDS development process to complete your contribution.

Examples of large changes include:

• Designing and/or building a new UI component.
• Designing and/or building a new variation for an existing UI component.
• Designing a new icon and adding it to the System.

Request for Comment

The Request for Comment (RFC) process protects the aspiring contributor from investing significant time to design, develop, and document a new feature that may not align with the System’s direction or vision.

1. Proposing a Request

To propose a feature via an RFC, use the Request for Comment JIRA ticket template. Be prepared to provide a thorough description and rationale for your contribution, as well as a list of other product teams with an established need for the new feature.

2. Review and Clarify

Once an RFC is received, a System team member or the segment owner will review it. The System team and/or the segment owner will confirm that the contributor has sufficiently detailed the proposal and provide initial feedback. The triaging member may also solicit initial feedback from community members likely to have a strong opinion on the topic.

3. Discussion

After the initial review and revision process, the proposal will be open for discussion for a short period of time.

Within one to two weeks, the System team, segment owner, and contributor will collaborate to determine whether to approve the request. Collaboration can include email (for clarifications and more details), Slack discussion, and, if necessary, face-to-face meetings.

4. Activation

Once approved to move forward, an RFC is considered “active” for implementation.

Activation is not a rubber stamp and does not mean the feature will ultimately be merged. It does mean that, in principle, all the major stakeholders have agreed to the feature and are amenable to incorporating it into the System.

5. Implementation

Contributors may implement an active RFC, conforming to considerations of quality, consistency, and reuse relative to similar system concerns. Materials may include:

• Design specification reviewed within established critiques and approved.
• Code (such as HTML, CSS, and JS) built and submitted as a pull request to the system repository.
• Documentation (such as guidelines, reference tables, images, and code examples) in the form of a Word document and related assets.

Contribution Process

Contributors should use the MDS development process as a guideline for how to approach their contribution. Some contributions may not use all five steps from the process, however, every contribution should include a [Discovery] phase to identify current standards, best practices, and teams that will directly benefit from the contribution.

Segments and Contributions

By providing a robust set of subject-matter-experts and engaged participants across a range of topics, segments provide contributors with key partners in the community to help review, expand and approve their work. Use the tables below as a starting point to ensure thorough review of your contribution.

Work with the segment owner to determine the level of review necessary for your specific contribution. You may not use every reviewer, or you may end up using multiple cycles with a particular reviewer. Your segment owner can also help to coordinate your work with other potential contributors, the MDS core team, and design leadership.

Visual Language, UI Components and Iconography

Design Contribution

Examples of design contributions include leading the design of a new UI component or a new variation for an existing component, significantly expanding aspects of our visual language, or designing a new icon to be added to the System.

Documentation Contribution

Examples of documentation contributions include expanding or editing documentation for existing UI components.

Charts

Design Contribution

Examples of design contributions include leading design of a new chart or a new variation to an existing chart, updating the visual design of an aspect of an existing chart, or expanding the charts visual language.

Documentation Contribution

Examples of documentation contributions include expanding or editing documentation for existing charts or the charts visual language.

UX Patterns

Examples of contributions include authoring a new UX pattern or expanding/editing an existing pattern.

Accessibility

Examples of contributions include expanding accessibility documentation for an existing UI component or proposing additional ARIA tags or other code to be added to an existing UI component.

Editorial

Examples of contributions include expanding editorial guidelines for existing UI components or creating new resources to reside in the editorial library.

Reference

The RFC process was inspired by the Rust RFC documentation.