While this contributing guide is for GitHub employees, all contributions from the community are welcome.
Components are frequently used visual patterns we've abstracted into a set of convenient styles, that would be otherwise difficult to achieve with utilities.
Decisions to add new components are made on a case-by-case basis, with help from the GitHub Design Systems team. Some questions that we use to guide these decisions include:
Many of the same questions can be applied to utilities, however the purpose of these styles is different:
Utilities do one thing well and one thing only. These styles are immutable and therefore often use the
!important tag. For this reason we aim not to change the properties of utilities very often. They often form the building blocks of our pages and when we introduce new ones we need to do so with care as we'll likely need to live with these styles for a long time. When assessing whether there is a need to add a new utility, consider these additional questions:
It's usually better to open an issue before investing time in spiking out a new pattern. This gives the design systems team a heads up and allows other designers to share thoughts. Here's an outline of what's helpful to include in a new style issue:
Type: Enhancementfor new styles
Type: Bug Fixfor—you guessed it!—bug fixes
Type: Polishfor refactors of existing styles
Type: Breaking Changefor any change that removes CSS selectors or SCSS variables
status: review neededand the
design-systemslabels to your pull request. Follow the ship checklist for additional shipping steps.
New styles we add should be used in as many places as makes sense to in production. Often it takes time to refactor all instances to use the new styles in one pr, but you should ensure this is followed up on.
type: refactor. Add a task list with links to the code or pages that need updating. If you need help, request help in this issue.
If you get to this step you've helped contribute to a style guide that many of your colleagues use on a daily basis, you've contributed to an open source project that's referenced and used by many others, and you've helped improve the usability and consistency of GitHub for our users. Thank you!
Please open an issue if we can improve these guidelines and make following this process any easier.
Documentation for Primer CSS modules should live in the corresponding
.mdx file for that module in the
There are separate folders in
/docs/content for component, object, support, and utilities docs, as well as separate folders for more general documentation such as principles and tooling.
docs/content/ automatically become pages with URLs based on their path relative to
content/. For example,
docs/content/components/box.md creates a
To add new documentation, locate the appropriate folder and create a new
.mdx file. Be sure to include the proper front matter (at minimum, title and status). For example:
---title: Alertsstatus: Stablesource: 'https://github.com/primer/css/tree/main/src/alerts'---
A table of contents is automatically inserted at the top of every page published on primer.style/css.
For new components or doc pages, add the title and url to nav.yml.
Check out Doctocat's live code documentation for more information about creating live code examples.
Primer CSS follows semantic versioning conventions. This helps others know when a change is a patch, minor, or breaking change.
To understand what choice to make, you'll need to understand semver and know if one of the changes shown is a major, minor, or patch. Semver is confusing at first, so we recommend reviewing semver and/or asking the team by opening an issue.