Contribution Guidelines

We welcome anyone who would like to contribute to React Magma. Working with the React Magma team, you may contribute your skills to making our design system better.

Ways to Contribute

There are many ways to contribute to the React Magma project on Github. Here are just a few:

Bugs and mistakes
Documentation improvements
New or improved components and features

Check out this PDF to see a simplified look at a designer's journey through the contribution process. Then keep reading below for everything you need to know.

Bugs and Documentation Contributions

If you find a bug or piece of documentation requiring an update, you may open a new issue for the React Magma team to address, or you can fix the issue yourself and submit your own pull request.

Component and Feature Contributions

A new feature is complete when the following items are addressed. This can take several people to accomplish together or just a small duo of over-achievers.

Explain the Rationale

Explain how your idea will add value to the system. React Magma serves a wide range of products, and contributions that prove to be relatively universal and easy to reuse are more likely to be accepted.

Design Ideas

Have a great idea for React Magma but you’re not a developer? No problem. Submit designs in the form of wireframes or high-fidelity mockups for new components and work with our team to bring them to life.

Sketch Symbols or Design Assets

If you are creating a brand new component or enhancing the presentation of an existing component, then there probably needs to be a corresponding update to the Sketch symbol libraries for React Magma. Anyone can create new Sketch symbols, but they have to be added to the actual libraries by someone on the Cengage UX team. View the Sketch documentation for working with symbols and libraries.

Working Code

The component or enhancement must be built in React and follow the standards set by the React Magma team. More details for contributing to the code for React Magma can be found in the Github repository.

Code Documentation

Each component should have a corresponding MDX page to appear within the docs site with relevant examples. If you are going to contribute to the documentation, look at the existing documentation for other components as examples, and please try to stay as consistent as possible with wording and writing style.

Design Guidelines

Every component requires documentation on how to properly use that component within a design. The design guidelines should include:

Description of component
Intended usage
Design principles used when designing
Descriptions of the different types, sizes, and variations where applicable
Examples of correct and incorrect usage

Look at the existing design guidelines for other components as examples, and please try to stay as consistent as possible with wording and writing style.

General Contribution Guidance

Good Communication

Make sure you are giving progress updates for any contribution. With more communication, we can catch things earlier and help you develop using the conventions and practices that we have built-in. This will also ensure a much faster PR approval if we are on the same page the whole time.

Collaboration and Final Decisions

The React Magma team welcomes your suggestions and contributions. This project works best as an open, cross-organization collaboration. Please bring your ideas and constructive criticism to the team and we can brainstorm, engage in healthy debate, and work together towards the best possible solution. Because the React Magma team is ultimately responsible for the ongoing development and support of these components, the core team will make (and own) final decisions regarding public API, internal implementation details, build tools, coding style, and which work is the priority. Once a decision has been made, everyone involved needs to be willing to disagree and commit in the interest of moving forward.

Everyone involved in the creation of a new component is responsible for making sure it adheres to the WCAG 2.1 guidelines for accessibility. This includes, but is not limited to, color contrast ratios, alternative text, screen reader use, and keyboard navigation. If you’re not sure where to begin, a web search like “making a [component name] accessible” is a good place to start.

Development Guidance

Code Consistency

The React Magma team puts a lot of time, effort, and thought into making decisions around all aspects of the implementation of this component library. That effort includes ensuring that the React Magma code maintains a consistent look and feel across the entire repository. Before starting on your first PR please make sure to have a look at other components to see the different convention choices and structure. If you do see something that you believe should be changed, added, or might benefit from your unique perspective, please bring it to the React Magma team for discussion before making that change in your new component or fix.

Stay Focused

If, while you're looking through the repository, you see something outside of your component that you are focused on that you believe should be changed/fixed please let the team know. For your PR, make sure you stay focused on what you were originally intending on working on. That does not mean that we can't make changes outside of your component, but we want to make sure it's the right choice and if it is, we will create a separate PR as there may be side effects.

Pull Request Rigor

We appreciate the help with anything that comes in through a pull request, but please realize that we will not be rushing anything through and any developer should expect a decent amount of feedback on any pull request. Being a library that is used across multiple teams means that we need to make sure we are thinking of as many situations as possible, so even if you believe the component is ready for your team there could be more that we ask for to allow for the component to be used in a broader scenario.

Theme

We have a base theme built out and allow for the consumer to use their own, separate theme if need be. Make sure not to hard code any colors or refer directly to the magma theme in those implementations. Instead, components should use the ThemeContext, which will use the magma theme by default. If you do not see a color that you need to use as part of the magma theme, please talk to the team and we can find out where that color should live.

Interfaces and Property Tables

The property tables that we use are generated automatically but require some wiring up. The interface in the typescript file must be annotated with TypeDoc comments. You will also need to add the needed props to the frontmatter in the .mdx file. This will allow for our props table component to match the props referenced in the frontmatter to build out the props table.

Design & Usage Guidance

The need for a new or updated component often arises when a specific design problem is being solved. But because React Magma is intended for use across many different products, we must broaden our view to include how it might be used or impact other applications.

Reusable Components

We suggest exploring how a new component could be used and provide value in other scenarios outside the one you’re probably focused on. A component that can be used across many scenarios has a greater chance of being accepted.

Styling Consistency

Every component should be designed using the standardized styles of React Magma, including typography, spacing, and colors. We also very often put our components on dark backgrounds instead of only light backgrounds, so please think through whether the component needs an inverse version.

Responsive Behavior

React Magma is primarily used for web applications, and we believe strongly that every component and UI should have Responsive behavior. For a component, this means you need to think through how the component might change as the viewport of the device changes. This could involve the following:

The component simply shrinks and stretches gracefully at all sizes.
Something has to change at a specified breakpoint.
The function of the component won’t work at a certain size, so it is suppressed and a message is displayed letting the user know.