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 and 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.
Note: Documentation for Primer CSS modules should live in the README of that module, see the primer modules section below for more details. The anatomy of a guide will work the same as part of a module README as well as regular markdown documentation.
The style guide takes a content first approach. Everything you see on the site is built from markdown files found in this folder.
Currently there’s a few levels of hierarchy. The top level is styleguide/ inside the only content rendered is the README.md file on the style guide homepage.
The folders immediately in styleguide/ represent top level navigation. There’s a little bit of setup needed to create a new top level navigation item.
github/github/app/views/navigation/_styleguide.html.erbEverything inside these top level navigation items gets built into the guide for that section. README.md files will be returned for sections (ie. primer, js, ruby, branding) when the user is on a section landing page ie /primer/.
The anatomy of a style guide markdown file 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 the style guide you can add a {:toc} tag to have a table of contents automatically generated.
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>
## Primer CSS modules Modules are created for all the styles we include in the Primer framework. Modules are folders with a specific structure that include CSS, a `package.json`, and other files for publishing to repositories in our GitHub Primer organization and NPM. The source of truth for our CSS will be in the github/github codebase, but we publish updates to NPM whenever styles in github/github are changed. By publishing to NPM we are able to distribute our reusable modules to other GitHub properties. Modules are grouped into three packages: - **primer-core:** modules that are used for dotcom as well as marketing websites - **primer-product:** modules that are only used on dotcom - **primer-marketing:** modules that are only used on marketing websites and occasionally for promotional content on dotcom You can add module packages by including any or all of the following imports in your bundle:
@import “primer-core/index.scss” @import “primer-product/index.scss” @import “primer-marketing/index.scss”
### Creating a module
1. Create a new repository on https://github.com/primer that will be the location for your module. Only the design systems team have write access to that repository. If you don't have access, ask in #design-systems and someone will create a folder for you.
2. Create a new folder inside one of the primer directories (core, product, or marketing), and within the appropriate styles folder (components, objects, utilities etc.). This folder cannot be inside another module with a `package.json` file.
3. Inside the folder you'll need at least a `package.json` file. Here is an example of what you'll need in the package file. The main thing it's looking for are `name, version, and repository`. The publish script uses this to push to the distribution repository.
```js
{
"name": "module-name",
"version": "0.1.0",
"description": "",
"homepage": "https://github.com/styleguide",
"license": "MIT",
"repository": "https://github.com/primer/primer.git",
"main": "utilities.scss",
"bugs": {
"url": "https://github.com/primer/primer/issues"
},
"author": "GitHub, Inc.",
"scripts": {
"test": "echo "Error: no test specified" && exit 1"
},
"keywords": [
"primer",
"css",
"github",
"primercss"
]
}
```
5. The directory layout should typically be like this:
```
a-module/
├── lib/
│ ├── partial.scss
│ └── partial.scss
├── index.scss
├── README.md
└── package.json
```
Create a stylesheet named `index.scss`. In this file include a list of relative imports for the partials required, like the example below:
```scss
@import "primer-support/index.scss";
@import "./lib/button.scss";
@import "./lib/button-group.scss";
```
Add a `README` to give some info on the module and how to install it, and a documentation section. Here's an example of the [buttons README](https://github.com/primer/primer/blob/master/README.md).
### Publishing changes and new modules
Once you have your directory setup, you will be ready to publish the module.
To publish, there are two requirements. First, you must be on the `master` branch. Second, all changes should be committed and synced with the remote `master`. These requirements protect us from changes being overwritten. Once you're on `master` run `script/css-modules --help` to get a list of all the available commands. This script will help with versioning and publishing.
#### 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.