Skip to content

Introduction

Primer is built for GitHub by GitHub. Its guidelines are a collection of open source principles, standards, and recommendations for designing GitHub. As a design language, Primer provides common grammar and vocabulary to build cohesive, accessible, responsive, and efficient experiences.

A cohesive experience

GitHub has a global audience. Millions of people use GitHub every day for many different reasons, in many different ways. They all come from different backgrounds. We can’t infer their physical or cognitive abilities, or devices they use, or the internet connection they have. All of that needs to be taken into account before, during, and after the design process.

Familiar patterns help people intuitively navigate to the information they're looking for, while also helping people discover new features. If pages and features don’t share the same metaphors, people get confused more easily, it makes it harder for them to understand the features we provide.

Primer focuses on the user experience so people can benefit from using a platform that is cohesive, no matter where in the platform they are. If a page behaves and feels familiar, it allows people to focus on the task at hand, instead of requiring them to parse UI that looks completely new.

Inclusive and accessible design

GitHub is a home for all developers. To be inclusive means we must consider accessibility at the core of how we design.

Accessibility and inclusive design needs to be considered from the start of a project, because it deeply affects its design, how the product behaves, and how it’s built.

Adding accessibility support to a design after the fact generally turns into a difficult retrofit.

For more information, see Accessibility at GitHub.

Responsive design

Browsers are found on devices with different shapes, sizes, display qualities, and input methods, so we can’t assume a desktop-only experience is enough. Supporting responsive experiences is an essential part of developing for the Web today. In fact, making sure pages work well on most screen sizes or zoom levels is an accessibility requirement as well.

Primer plays an important role in providing reusable patterns and components that can streamline the creation of responsive-friendly and accessible designs, letting teams focus on bigger problems. GitHub projects should take advantage of these patterns so they can provide people with cohesive experiences throughout the entire platform.

Primer uses the term “Responsive design” to refer to design decisions that are adapted to device form factors and user preferences.

For more information, see Responsive.

Design for efficiency

GitHub is a platform used for productivity. We aim to encourage flow, focus, and an experience that is fast and compact.

By providing a cohesive, inclusive, and responsive design, Primer’s goal is to remove as much friction as possible between the human and the software.

Primer patterns and components aim towards accessible solutions that don’t dilute efficient UI interactions. It focuses on responsive design that doesn’t reduce desktop experiences into mobile-first solutions. Ultimately, it recognizes the need to encourage flow by providing calm and logical experiences throughout.

The Zen of GitHub

“Whether you call it taste, culture, or zen, there are underlying assumptions that members of an organization rely on to resolve ambiguity in pursuit of the organization’s mission.”
Ben Balter

The GitHub API consolidates the Zen of GitHub in its own codebase, in 14 aphorisms:

  • Responsive is better than fast
  • It’s not fully shipped until it’s fast
  • Anything added dilutes everything else
  • Practicality beats purity
  • Approachable is better than simple
  • Mind your words, they are important
  • Speak like a human
  • Half measures are as bad as nothing at all
  • Encourage flow
  • Non-blocking is better than blocking
  • Favor focus over features
  • Avoid administrative distraction
  • Design for failure
  • Keep it logically awesome

We recommend you to read about the story behind the Zen of GitHub in these posts: