Five-stage component maturation process
New components progress through five stages before becoming Primer components: (1) Exists and is discoverable with a name, description, and at least one Storybook story; (2) Meets basic design quality checks against the pattern design checklist; (3) Has documentation including Storybook stories and MVP component documentation; (4) Is accessible, passing axe checks and following Product Accessibility Checkpoints; (5) Ready to upstream, satisfying enough criteria to reach Alpha maturity status.
When Primer maintainers upstream components
Primer maintainers decide to upstream a component based on: whether the pattern is frequently used by multiple feature teams, whether it solves a particular design, engineering, or accessibility problem worth encouraging, potential negative consequences like performance impact, how it fits thematically with existing Primer components, and whether the time investment in owning and maintaining it is worthwhile.
Component naming rule for avoiding duplication
New components should never have the same name as an existing Primer component, especially if distinctly different. The only exception is when introducing the React implementation of a component already created in Primer ViewComponents. When creating a modified version of an existing component, attempt to modify it in Primer first; if rejected, iterate on a fork with a new name until it can be upstreamed.
Component lifecycle maturity levels
Upstreamed components go through component lifecycle maturity levels. Alpha level is considered safe for production use but consumers should expect breaking changes. Beta level represents further maturation. Stable level is the goal for all or most components.
Who can initiate upstreaming to Primer
Component upstreaming to Primer can be initiated in two ways: (1) by Primer maintainers if a component gains enough traction being used by multiple feature teams, or (2) by a feature team that believes the component is ready by creating an issue using the Primer pattern proposal issue template.
Minimum requirements for new component discovery
At the earliest phase, a new component needs a name, a description, at least one Storybook story, and must pass basic accessibility checks to be discoverable and ready for sharing with other teams.
Documentation requirements for MVP component
Basic component documentation must include Storybook stories demonstrating all features and options, and meet the MVP component documentation criteria.
Ways to contribute to Primer
There are six main ways to contribute to Primer: participate in discussions, propose a new UI pattern, improve the documentation, design or build new patterns, give feedback and report bugs, and contribute to open source repos.
Code of conduct requirement for contributions
All contributions to Primer must follow the code of conduct.
Getting help with Primer contributions
If you get stuck or need help while contributing, head to #primer on Slack or start a discussion in github/primer with your question.
External contribution policy for Primer
At this time, Primer is not looking for external contributions from non-GitHub staff. Some links in the documentation are only available to GitHub staff.
How to participate in Primer discussions
If you have a question, feedback, or suggestion, you can start a new discussion in github/primer/discussions (GitHub staff only) or review existing ones.
Primer office hours
Primer office hours are held once a week and anyone at GitHub can join, ask questions, and participate in ongoing conversations. Zoom invite links are posted in Slack before the meeting starts.
Process for proposing a new UI pattern
To propose a new Primer pattern, start a discussion in github/primer/discussions (GitHub staff only) for early-stage proposals. For more developed proposals, open a pattern request issue using the pattern proposal template.
How to improve Primer documentation
If you notice something missing, a typo, or have ideas for improvement, start a discussion or submit a pull request with a fix using the 'Edit this page on GitHub' link in the documentation footer.
Contributing guidelines for Primer open source repos
When contributing to Primer open source repos, follow the repo's specific contributing guidelines. Primer CSS is at github.com/primer/css/blob/main/CONTRIBUTING.md, Primer React is at github.com/primer/react/blob/main/contributor-docs/CONTRIBUTING.md, Primer ViewComponents is at github.com/primer/view_components/blob/main/docs/contributors/README.md, and Octicons is at github.com/primer/octicons/blob/main/CONTRIBUTING.md.
Contribution eligibility for Primer Web Figma
Currently only GitHub employees can contribute to Primer Web due to how Figma handles open source files.
Branch naming convention for Figma contributions
When creating a branch from Primer Web, name it @username/changes-being-made. For example: @lukasoppermann/update-button-radius.
Review request process for Figma changes
After making changes to a Primer Web branch, request a review from the direct responsible individual (DRI) of the file. If unsure who that is, reach out in the #primer-figma Slack channel. Once approved, a maintainer will merge and publish the changes to the library.
Rationale for branch-based contribution process
The Primer Web branch-based process ensures no accidental changes are added to the library and allows better tracking of changes. It functions like a repository that does not allow direct pushes to the main branch.
Component naming should reflect code
Component names and their properties should reflect what is present in code whenever possible. For example, the button component is named Button instead of btn.
Component names use PascalCase
Component names in Figma use PascalCase. For example, the action list component is named ActionList.
Layer naming should describe content and positioning
Every component's layers should be named to reflect what is rendered on that layer. When describing component layer structure, Primer uses a left-to-right direction to reflect start-to-end positioning. Layer names should not use abstract defaults from Figma such as Frame 403.
Breaking changes with layer modifications
When updating existing components, be careful with adding or removing layers that have children as this will create a breaking change for consumers.
Group layer naming should be explicit
For groups of items within a component, be explicit about what is contained within a group rather than using abstract layer names.
Text layer naming conventions
Layer names for text should typically represent the type of textual information it contains. Text layers that will retain overrides when swapping to another instance or variant should be named the same. Examples of text layer names include: ButtonText, Message, Text.
Action layer naming
Layers that contain actions should have their name describe the action, such as 'Action: Button options'.
Variant properties should follow code implementations
When creating a new component, apply variant properties that follow existing parameters as seen in other framework implementations such as Primer React. If a parameter exists but cannot be expressed in Figma (e.g., alt or href), it is not necessary to include it.
Variant properties appear above component properties
Variant properties will always appear above component properties in the properties panel and can only be reordered with other variant properties.
Common component property types in Primer
The following are common component properties and their types used in Primer Web: leadingVisual (Boolean) - Show/hide the leading visual which is at the start of the component (left-side); title (Text) - Text content for the Title layer; leadingAction (Instance swap) - Swap between different interactive options such as checkbox, checkmark, or bullet.
Property naming conventions
When writing properties (variant or component), write them as they are seen or would be written in code. For variants, keep the property name in camelCase with values in lowercase. When indicating a boolean property, add a question mark. Examples: label? (true, false), state (rest, focus, hover), visual (octicon, avatar).
Common property categories for Primer components
Common property categories used in Primer Web Figma components include: type (values: text, single select, multi-select, danger, header, item, footer); state (values: default/rest, hover, selected, disabled); size (values: small, medium, large or pixel values); leading[Accessory] (values: icon, avatar) placed to the left of text; trailing[Accessory] (values: icon, avatar, label, counter) placed to the right of text; description (values: on/off as boolean, short/long, inline/block); selected (values: on/off as boolean toggle).
Decision criteria for multiple variants vs multiple components
The main distinction between using variants or adding additional related components is to ask: Will this change only visual styling or will this also change the function or purpose of the component? Also consider how this will affect maintenance of the component.
When to use multiple components instead of variants
Examples of when to use multiple components in Primer include: Alerts (Banners), Avatars (Avatar and AvatarStack), Form select items.
When to use variants instead of multiple components
Examples of when to use variants in Primer include: Buttons, Outline labels, Navigation > Header.
Slot component for customizable content
The _Slot component is a local component to the Primer Web library used as a placeholder for customizable content where designers have more flexibility. Slots are recommended for headers, main content, and footers. Slots should be used within a container that has autolayout to dynamically fit its parent container.
Using slots in design files
When using a component that contains slots within your own design file, create a local component with the specific contents needed and replace the _Slot with an instance of the local component. Due to certain bugs in Figma, if a _Slot is replaced and does not flex, the auto layout properties will need to be manually updated.
Contribution checklist for components
For all component contributions: verify changes to the component API (props, variants, etc.) are reflected in the documentation sheet; properties are sorted in sensible order; when adding a component the default variant is used; changes are accessible per accessibility guidelines; properties and behavior match code as closely as possible; all layers are named without defaults (no Frame 23, etc.). When adding new components additionally: component name matches the code component name in PascalCase; component is added to the overview page; component is in light mode; component uses primitives via styles from Primer Primitives Figma library; properties follow property guidelines; component adheres to authoring components guidelines.
Primer Web Figma DRI
The Direct Responsible Individual (DRI) for Primer Web (Internal Figma library and External Figma library) is @lukasoppermann.
Primer Brand Figma DRI
The Direct Responsible Individual (DRI) for Primer Brand (Internal Figma library) is @danielguillan.