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 and layout objects.
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 objects and utilities, however the purpose of these styles is different:
!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: Enhancement
for new stylesType: Bug Fix
for—you guessed it!—bug fixesType: Polish
for refactors of existing stylesType: Breaking Change
for any change that removes CSS selectors or SCSS variablesstatus: review needed
and the design-systems
labels 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.
Removing styles and SCSS variables can be scary. How do you know if the thing you're deleting (or just planning to delete) isn't used in other projects? Semantic versioning provides us with an answer: We don't know, but we can use "major" version increments (from, say, 13.4.0
to 14.0.0
) to signal that the release includes potentially breaking changes. The rule is simple:
Whenever we delete a CSS selector or SCSS variable, we will increment to the next major version.
When planning to delete a CSS selector or SCSS variable, you should:
Add a TODO@version comment above the line in question:
// TODO@15.0.0: delete $some-unused-var$some-unused-var: 15px !default;
Add it to deprecations.js:
const versionDeprecations = {'15.0.0': [{variables: ['$some-unused-var'],message: '$some-unused-var is unused, and has been deprecated.'}]}
We have several checks and tools in place to help us plan, track, and catch both expected and unexpected removals of both CSS selectors and SCSS variables:
deprecations.js
This file is where we document all of our current and planned CSS selector and SCSS variable deprecations (removals), and is used to generate deprecation data for other tools.
script/test-deprecations.js
This script compares the CSS stats and variable data between the latest release and the local code, and throws error messages if:
Run script/test-deprecation.js --help
for more info and available options.
primer-css/TODO
This stylelint rule looks for comments in the form:
// TODO@<version>: <message>
and generates an error for each one whose <version>
is less than or equal to the current version (in package.json
). You can test this rule for future releases with:
PRIMER_VERSION=<version> npx stylelint-only primer-css/TODO -- src
where <version>
is the future version you'd like to compare against. Assuming that the correctly formatted comments exist already, violations of this stylelint rule can be used to generate a checklist of lines to remove in a future release.
See the deprecation data docs for more information.
Our documentation site for Primer CSS is built using Doctocat and deployed with Now. Our site is built from the docs
folder and uses MDX to render markdown.
Documentation for Primer CSS modules should live in the corresponding .md
or .mdx
file for that module in the /docs/content
folder.
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.
Documents in docs/content/
automatically become pages with URLs based on their path relative to content/
. For example, docs/content/components/box.md
creates a /components/box
page.
To add new documentation, locate the appropriate folder and create a new .md
or .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/master/src/alerts'---
A table of contents is automatically inserted at the top of every page published on primer.style/css.
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.