Guidelines for building design patterns using Primer.

Design flexible, robust, and repeatable patterns that build on a set of solid foundations.

Design system foundations

Primer is the stable trusted layer. At its foundations are typography, color, spacing, and layout.

➡️ Primer design guidelines

Upcoming patterns and proposals

To avoid duplicated efforts and to accommodate upcoming changes, keep up with the Primer Roadmap.

➡️ Primer Roadmap (GitHub staff only)

Context and use cases

When creating a new pattern, we advise starting with an audit of similar patterns that already exist as well as identifying opportunity areas where the new pattern can be used. Consider as many different use cases as possible. The goal is to create patterns that are flexible, reusable, and that solve concrete problems.

Finally, consider where a pattern will live in the context of a system. A pattern designed for a specific context is not likely to be considered a reusable component.

Share early, and often

There are many opportunities to get feedback from Primer maintainers.

Systems designers provide extra context and considerations for designing with system-wide considerations Accessibility designers provide context and considerations for accessible and inclusive design Product designers consider the designs in the context of their own product area and whether their specific use cases could benefit from your work Design 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:

Design checklist

All design patterns for Primer Library consideration should at minimum:

  • Leverage Primer: Leverages the foundational building blocks and tools of Primer. Reuses or extends existing patterns and primitives rather than creating overrides
  • Maintain high design quality: Visually in harmony with GitHub UI and all visual elements are used are in their correct context
  • Prioritize code as a top concern: Designed with code quality and component API top of mind
  • Be inclusive: Designs follow Primer accessibility guidelines and considers a global audience
  • Have documentation: Design patterns are documented for easy adoption