Making a Contribution

While some changes may be small, others may be more substantial and require deeper consideration. For these larger changes, the System follows a Request-for-Comment (RFC) model.

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 Design and Engineering Microsoft Teams MDS 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 the Microsoft Teams MDS Design channel for review.
  3. Gather and incorporate feedback from the wider design team using a visual or UX critique session or Microsoft Teams.
  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 the Microsoft Teams MDS Engineering channel for community review and feedback.
  2. Request access to the MDS repository by emailing [email protected] or reaching out via Microsoft Teams 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), Microsoft Teams 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.

Step
Description
Reviewers

[Discovery]

Gather requirements, research approaches, identify existing design standards, and plan out the remainder of the work for your contribution.

Segment, Key Community Members, Critique

[Design]

Create design concepts, gather feedback, and iterate to refine your contribution. Review all new design work with design leadership.

Segment, Key Community Members, Critique, Design Leadership

[Build]

For contributions that also neccessitate additions to the MDS codebase, coordinate with the MDS team on implementation.

MDS Core Team, Key Community Members

[Doc]

Based off of the work done during the [Discovery] and [Design] phases, author new documentation and refine by gathering feedback.

Segment, Key Community Members, Design Leadership

[Publish]

Coordinate with the MDS team to publish content to the documentation site.

MDS Core Team

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.

Person(s)
Description
Frequency

Segment

Work with the segment owner to define and refine your contribution. They can also assist planning out the work and identifying collaborators. Some segments have established groups that meet regularly, the segment owner can invite you to these sessions.

Regularly

Key Collaborators

Identify 2+ reviewers (including at least one senior-level) from the design community to provide detailed review and comments on all proposed content. Look for reviewers on teams that have a need for the new feature.

Regularly

Visual/UX Critique

Leverage our community critique sessions to get feedback from many perspectives. Consider checking in with the community to review your initial concepts as well as your near-final approach.

As Needed

Design Leadership

Coordinate with the MDS team to share your work at an upcoming mid-sprint design review with David Williams, Brian Verhoeven, Tim Mills, Jason Ackley and Philip Burton.

Initial Concepts & Final Review
Required

MDS Core Team

Share near-final work with the MDS core team for review and suggestions regarding implementation and next steps.

Final Review

Documentation Contribution

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

Person(s)
Description
Frequency

Segment

Work with the segment owner to define and refine your contribution. They can also assist planning out the work and identifying collaborators. Some segments have established groups that meet regularly, the segment owner can invite you to these sessions.

Regularly

Key Collaborators

Identify 2+ reviewers (including at least one senior-level) from the design community to provide detailed review and comments on all proposed content. Look for reviewers across products to ensure a range of perspectives.

Regularly

MDS Core Team

Share near-final content with the MDS core team for review and comments, with a focus on voice and tone.

Final Review

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.

Person(s)
Description
Frequency

Segment

Work with the segment owner and the Charts segment group to define and refine your contribution. They can also assist planning out the work and identifying collaborators.

Regularly

Key Collaborators

Identify 2+ reviewers (including at least one senior-level) from the design community to provide detailed review and comments on all proposed content. Look for reviewers on teams that have a need for the new feature.

Regularly

Visual/UX Critique

Leverage our community critique sessions to get feedback from many perspectives. Consider checking in with the community to review your initial concepts as well as your near-final approach.

As Needed

Chart Standards Lead

Present proposed content to Chris Cantore for review and comments.

Initial Concepts & Final Review
Required

Design Leadership

Coordinate with the MDS team to share your work at an upcoming mid-sprint design review with David Williams, Brian Verhoeven, Tim Mills, Jason Ackley and Philip Burton.

Initial Concepts & Final Review
Required

MDS Core Team

Share near-final work with the MDS core team for review and comments regarding implementation and next steps.

Final Review

Documentation Contribution

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

Person(s)
Description
Frequency

Segment

Work with the segment owner and the Charts segment group to define and refine your contribution. They can also assist planning out the work and identifying collaborators.

Regularly

Key Collaborators

Identify 2+ reviewers (including at least one senior-level) from the design community to provide detailed review and comments on all proposed content. Look for reviewers across products to ensure a range of perspectives.

Regularly

MDS Core Team

Share near-final content with the MDS core team for review and comments, with a focus on voice and tone.

Final Review

UX Patterns

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

Person(s)
Description
Frequency

Segment

Work with the segment owner and the UX patterns segment group to define and refine your contribution. They can also assist planning out the work and identifying collaborators.

Regularly

Key Collaborators

Identify 2+ reviewers (including at least one senior-level) from the UX community to provide detailed review and comments on all proposed content. Look for reviewers across products to ensure a range of perspectives.

Regularly

UX Critique

Leverage our community critique sessions to get feedback from many perspectives. Consider checking in with the community to review your initial concepts as well as your near-final approach.

As Needed

UX Leadership

Share your work with Tim Mills or Brian Verhoeven for review and comments.

Initial Draft & Final Review
Required

MDS Core Team

Share near-final content with the MDS core team for review and comments, with a focus on voice and tone.

Final Review

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.

Person(s)
Description
Frequency

Segment

Work with the segment owner to define and refine your contribution. They can also assist planning out the work and identifying collaborators.

Regularly

Key Collaborators

Identify 2+ collaborators from the design and engineering community with accessibility experience to provide detailed review and comments on all proposed content. When proposing code-related updates, always include at least one engineer as a key collaborator.

Regularly

MDS Core Team

Share near-final content with the MDS core team for review and comments. The core team can also help to identify any guidelines that can be codified directly in to components.

Final Review

Editorial

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

Person(s)
Description
Frequency

Segment

Work with the segment owner to define and refine your contribution. They can also assist planning out the work and identifying collaborators.

Regularly

Key Collaborators

Identify 2+ collaborators from the content strategy team to provide detailed review and comments on all proposed content.

Regularly
Required

MDS Core Team

Share near-final content with the MDS core team for review and comments, with a focus on voice and tone.

Final Review

Reference

The RFC process was inspired by the Rust RFC documentation.

©2020 Morningstar, Inc. All rights reserved. Terms of Use