Skip to content


These are some guidelines you should always keep in mind when creating Primer design patterns.

The key goals are to create flexible, robust, and useful patterns that advance Primer's incremental innovation, while building upon an existing set of solid foundations.

Design system foundations

Primer is built on strong foundations that should remain stable. Become familiar with guidelines on typography, color, spacing, and layout.

➡️ Primer design guidelines

Upcoming patterns and proposals

It's important to know what's coming into Primer, to avoid duplicated efforts and to accommodate upcoming changes to elements that may interact with what you're planning to work on.

Check what is currently being designed and built, as this may introduce new concepts and variations to existing patterns.

➡️ Primer backlog (GitHub staff only)

Context and use cases

Before you start to create mockups and think of solutions, it's good to always carry out an audit of where similar patterns are used in, and where it can potentially be used once a new pattern exists. You can also audit different products to see how they've solved similar problems.

Think about as many different use cases where the pattern can be used across as possible. The goal is to create patterns that are flexible, but that solve concrete problems.

Finally, consider where a pattern will live in the context of the larger product. Don't design a single pattern in isolation of its possible surroundings.

Design mockups and prototypes

@todo Coming soon!

➡️ Using Figma at GitHub

Share early, and often

The work that you're doing shouldn't be a surprise that you only reaveal when you're done.

Systems designers can provide extra context and considerations that are helpful to create a solid design.

Product designers can consider the designs in the context of their own product area and whether their specific use cases could benefit from your proposal.

Engineers can consider how something may be implemented, what is realistic within the existing constraints, and what is unfeasible.

There are different ways you can ask for and get feedback:

  • Async via discussions (GitHub staff only): Record a short video and/or links to a Figma prototype (or any other kind of prototype, like sketches or code), providing context and specifying what kind of feedback you're looking for
  • Primer open office hours: Attend office hours on Thursdays (1.30pm PT). The Zoom link is posted right before in #primer. Be prepared to give context and ask what kind of feedback you're looking for succintly. Ideally, give a heads-up in #primer beforehand so we can be sure a designer will be present in the call
  • Ad-hoc in real-time: In #primer, ask for a short critique session with a systems designer, to get feedback on a specific issue

Design checklist

All Primer design patterns should take into account the following areas:

  • Primer Primitives
  • Input types and devices (keyboard, pointer, touch, etc.)
  • Responsiveness (from very small to extra large screens)
  • Themeability
  • Accessibility
  • Content
  • Interaction states
  • Documentation/APIs
  • Figma assets