Adding new components
Guidance to help you get your components added to Primer. The primary audience for this guidance is GitHub staff.
The process starts with a new component being introduced as a custom React component in a feature team's app and becoming a Primer component once it matures and gets more usage.
This guidance is intended for GitHub staff members who are introducing design patterns that are not yet supported by Primer components. Contributions from Primer consumers who don't work at GitHub are welcome and encouraged, but these steps assume the reader is working on a feature team at GitHub.
Your component should have:
This is the least refined phase of a new component: it just needs to exist. If you've already decided that this is a component worth sharing with other teams, it just needs to be discoverable and pass basic accessibility checks.
For guidance on what makes a pattern worth sharing, check out the documentation: Handling new patterns.
Check the design against the criteria in the pattern design checklist.
The criteria in the pattern design checklist ensure your pattern is sturdy enough to be used in production and easily picked up by other designers or engineers. For a more detailed quality check, you can refer to the product design checklist (GitHub staff only).
The most basic documentation your component should have:
Documentation makes your pattern easier for others to use, and helps the team understand how your pattern could be adopted into Primer.
Resources for writing documentation:
Your component likely meets basic accessibility requirements if it passes axe checks and follows the guidance in the Product Accessibility Checkpoints (GitHub staff only) in our accessibility playbook.
It would be even better if your component has gone through an a11y design review and a a11y engineering review. Every new component we add to Primer goes through rigorous testing by the accessibility team, so your component will be better prepared for adopting and releasing in Primer.
Now your component has satisfied enough criteria that it's well on it's way to being at the “Alpha” maturity status! From here, your team or the Primer maintainers will be in a good position to adopt your component and iterate on it until it reaches the “Alpha” maturity status.
New components should never have the same name as an existing Primer component - especially if it's distinctly different from the existing component. The only exception is if you're introducing the React implementation of a component that has already been created in Primer ViewComponents.
If you're creating a modified version of an existing component, try to modify it in Primer first. If your changes are rejected by Primer, you can iterate on a "fork" of the component with a new name until it can be upstreamed. See the flowchart in the "Handling new patterns" guidelines.
Primer has a strict process for adding new components to ensure they meet certain quality criteria and are accessible.
Initiated by Primer: If a component gains enough traction that it's being regularly used by multiple feature teams, the Primer maintainers will create and prioritize an issue to upstream it.
Initiated by a feature team: If a feature team feels that the component is ready to be upstreamed to Primer, anybody is welcome to create an issue to review the component with Primer maintainers. During that review, the Primer will decide whether or not the component is a good candidate for upstreaming. Use the Primer pattern proposal issue template.
The Primer maintainers (designers and engineers) will decide if a component should be upstreamed using input from feature teams and the criteria described above.
Once a component is upstreamed, it goes through a component lifecycle maturity process until it reaches the stable level.
Once a component meets “Alpha” criteria it's considered safe to be use in production, but consumers can expect breaking changes as it matures to “Beta”. We aim to get all or most components to the “Stable” level of maturity criteria.
Although Primer has a high barrier of entry for introducing new components, contributions from everyone are welcome and encouraged. The contribution documentation and the Primer team members are available to guide new component contributions.
Primer maintainers often lack the bandwidth to do the work for you, but will do their best to answer your questions and help get your contribution to the “Alpha” maturity level.
If you're pitching design patterns that are lower-level than a component (for example, data saving patterns, focus management utility), you can create an issue or pull request, share your idea at the Primer patterns weekly working session (only available to GitHub staff), or post to one of Primer's Slack channels (only available to GitHub staff).