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.
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
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
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
Collect feedback and iterate the design
Share updated designs electronically, without another meeting
If the design approach is accepted, build and document, then share electronically
Final review is conducted
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
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
Prepare one or more low-fidelity design options, schedule a review meeting with the Mineral team and all stakeholders. Collect feedback and iterate
Conduct customer interviews or user research, and optimize
Create high-fidelity design, and share designs and research
If the final design is accepted, build and document, then share
Final review meeting, iterate if needed
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.