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 and sizes, 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.

Nielsen Norman Group defines Responsive Web Design as “a web development approach that creates dynamic changes to the appearance of a website, depending on the screen size and orientation of the device being used to view it”.

“Adaptive design”, on the other hand, has been a term historically used to identify an approach where entirely separated fixed layouts were created to support mobile devices (MDN has good documentation on how we got here).

“Responsive design” at GitHub is inherently adaptive, in the sense that it should not only adjust layout and spacing when resizing a page, but support patterns and component variants that match the paradigms and affordances of the person’s device:

  • Responsive to the form factor: adapt to viewport size, and pointing device support (fine for desktop, or coarse, for touch), and to the device metaphors and affordances.
  • Responsive to the user preferences: respect browser’s default font size, reduced motion, color scheme, contrast preferences, etc.

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 unified term “Responsive design” to discuss any design decisions related to device form factor and user preferences.

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.


Next: The Zen of GitHub