Guidelines for contributing to GitHub’s CSS.
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.
Making a decision on whether new components should be added is done on a case by case basis. It’s not always easy to make that decision but here are some questions you should ask yourself before moving forward with a pull request. The design systems team will help you make this decision.
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:
@product-design to help.type: new styles label, or type: refactor where appropriate.status: 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!
Let the design systems team know if we can improve these guidelines and make following this process any easier.
Our documentation site for Primer CSS is built using Next.js and deployed with Now. Our site is built from the pages folder and uses MDX to render markdown.
Documentation for Primer CSS modules should live in the corresponding .md file for that module in the /pages/css folder.
-There are separate folders in /pages/css for component, object, support, and utilities docs, as well as separate folders for more general documentation such as principles and tooling.
Each folder corresponds to a new url such as primer.style/css/utilities.
To add new documentation, locate the appropriate folder and create a new .md file. Be sure to include the proper front matter (at minimum, title, path and status). For example:
--- title: Alerts path: components/alerts status: Stable source: 'https://github.com/primer/css/tree/master/src/alerts' bundle: alerts ---
The anatomy of a Primer CSS markdown file is pretty straight forward, but has a few optional properties for making the page render special features.
Typically the file will look something like this:
---
title: Avatar stack
---
# Avatar stack
Stacked avatars can be used to show who is participating in thread when there is limited space available. When you hover over the stack, the avatars will reveal themselves. Optimally, you should put no more than 3 avatars in the stack.
```erb
<span class="avatar-stack tooltipped tooltipped-s" aria-label="jonrohan, broccolini, and shawnbot">
<%= avatar_for("jonrohan", 39, class: "avatar") %>
<%= avatar_for("broccolini", 39, class: "avatar") %>
<%= avatar_for("shawnbot", 39, class: "avatar") %>
</span>
```
Which consists of three parts:
and will render into an example used in the page. This can contain rails helpers also eg.<%= octicons “fire” %>`The options you have for the frontmatter are outlined below:
--- title: Document title ---
This is a nicer title for the guide section. If title: is not present, the helper will use the filename.
--- example_layout: toggle ---
Example layout will be applied to code blocks. By default it will just put the html into the page along with the syntax highlighted code, but for special cases, like animations, we need some customizations. The options for this property are toggle, plain, none. You can also specify example layout on a per code block basis.
--- example_template: icons ---
In cases where you don’t want to use code blocks to render examples, you can choose to make your example templates. Just specify the template name here, and it will be rendered at the end of a guide.
--- status: Needs refactoring ---
The status option is a tag that will tag a module as a thing, displaying what state the feature is in.
--- source: https://github.com/github/github/tree/master/app/assets/stylesheets/components/x.scss ---
The source option will let you point the document to the source file. This is only necessary for components that still live in the github/github repo; Primer CSS source files will have the source field populated automatically.
In pages published on primer.style/css, a table of contents is automatically inserted after the first ## Table of Contents heading (if present).
When using code blocks for demo purposes, you can choose to render each of the blocks differently by specifying the layout in the info string. For example if you want to use toggle as the layout for a code block:
```html layout=toggle <div class="p-5">Animation</div>
#### Versioning Primer CSS follows [semantic versioning](http://semver.org/) 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 I recommend reviewing [semver](http://semver.org/) and/or ask in [#design-systems](https://github.slack.com/archives/design-systems) or and experienced open-source contributor.