Contribute

Mineral Contribution Process

v1 (WIP)

Table of Contents

Intro

Mineral is a collaboratively maintained design system, fueled by the contributions of fellow ESDesign team members. This approach allows us to build a massively capable system that addresses the needs of disparate product teams, and provides the flexibility to adapt itself over time as new business, technology and user experience challenges arise.

Mineral will never be able to solve every design challenge, especially those that are specific to a particular product, but new design patterns that are potentially useful for a broader range of products and situations can be considered for adoption into Mineral as a way to leverage and amplify the good work of our team members, and promote UX consistency.

Goals

The goals of our Contribution Process are to:

  • Provide clear guidance on how and when to make contributions

  • Offer open access to the contribution mechanism for everyone in ESD

  • Support quality and consistency of guidelines and patterns

  • Ensure consistent user experience and accessibility outcomes

  • Facilitate the contribution submission, evaluation and adoption process

I Have a Challenge

If you’ve encountered a challenge, your first course of action is reviewing the Mineral documentation and/or emailing the Mineral team directly to find a solution. Mineral might not be able to help you solve some challenges that are unique to your specific product or situation, but our goal is to build Mineral to be a robust system that can at least offer guidance to designers for most situations.

In the event that Mineral does not provide a concrete solution to your challenge, product teams are always empowered to design new solutions for their customers’ needs. The next question is, can that new solution offer any value to your fellow ESD team mates, and what do I do next?

Contribution Types

If your design work could be valuable to other teams, consider contributing it to Mineral. There are 2 types of contributions, Light and Heavy. The “weight” of them is related to the amount of work and impact associated with each.

Contribution Types At-A-Glance

Light Contribution

  • Takes as little as 1 week

  • Examples: adding new icons, adding a theme color, adjusting the spacing in button, changing links in the footer

Heavy Contribution

  • Takes 2–3 weeks

  • Examples: creating a high-density table mode, altering a decorative color palette, adding a new form control, or any change that requires consumers of components to change their code

Which Type Do I Need?

It’s easy to determine which type of contribution you should use. Just follow this decision tree.

Contribution type decision tree

Light Contribution

A Light Contribution is for smaller changes to existing design patterns. It’s intended to be relatively easy to make these types of contributions, and as a result, the number of meetings and other steps is kept to a minimum.

Procedure

  1. You’ve already emailed the Mineral team, and since the challenge is small and easily understood, you should prepare one or more design possibilities that solve it

  2. Hold an initial review meeting with the Mineral team to introduce the challenge, and have a thorough dialogue about the ways you’ve solved it. Designer, developer, researcher and other stakeholders should be present

  3. Collect feedback and iterate the design

  4. Share updated designs electronically, without another meeting

  5. If the design approach is accepted, build and document, then share electronically

  6. Final review is conducted

  7. Design and code are incorporated

Heavy Contribution

A Heavy Contribution is for large changes to existing design patterns, or for the creation of entirely new design patterns. This type of contribution is reserved for complex design challenges, and so more communication and collaboration is required with the Mineral team.

Procedure

  1. Arrange a kickoff meeting where the challenge can be reiterated, along with the reasoning and documentation justifying why this challenge can’t be solved with existing Mineral UI. Designer, developer, researcher and other stakeholders should be present

  2. Prepare one or more low-fidelity design options, schedule a review meeting with the Mineral team and all stakeholders. Collect feedback and iterate

  3. Conduct customer interviews or user research, and optimize

  4. Create high-fidelity design, and share designs and research

  5. If the final design is accepted, build and document, then share

  6. Final review meeting, iterate if needed

  7. Design and code are incorporated

Checklists

Use these checklists to prepare your submissions for review and consideration.

Submission Checklist

  • What is the user need?

  • Is there customer feedback or research that prompted this effort?

  • What existing design pattern is this based on, and why is the existing pattern not sufficient?

  • Can you articulate the value that this solution offers to other teams?

  • Does your design meet Mineral foundations and accessibility standards?

  • Have you discussed this challenge/solution with your developers and other stakeholders?

  • Have you considered the technical checklist and how you will achieve each one?


Technical Checklist

  • Does your contribution render and function properly in all supported browsers (IE11, latest Chrome, Firefox, Safari)?

  • Have automated tests been written and are they passing?

  • If your contribution aligns with an ARIA Widget, does your code implement all functionality detailed in the authoring practices and examples? If not, does your code meet WCAG 2.1 AA guidelines?

  • Have rendering performance (initial load time & 60fps) and perceived performance been considered?

  • Have you created or updated relevant documentation?

  • If you’re contributing a new component or a breaking change, have you tested it in a sandbox?


Closing the Loop

The submission process does not always result in your work being accepted. Sometimes, despite having great work that solves your design challenge, it’s not a good fit for the Mineral system. That’s not a judgment on your work, just a way for Mineral to stay relevant and nimble so other teams will find it valuable.

If your contribution is incorporated into Mineral, you’ll eventually see it in the Mineral documentation. That’s a huge success, and the success of your work will be exponentially amplified and used as a basis for design work by many teams in the future.

For any questions or suggestions, email the Mineral team. We’re eager to help.