Primer Brand 0.61.0: A new typographic foundation

[jesussandreas]

Typographic styles have been rethought, simplified, and refined in the 0.61.0 release of Primer Brand.

---

This milestone release marks the beginning of a broader set of changes coming to Primer Brand over the next few months. Each release will represent a tonal shift in how we approach brand-focused UI at GitHub, and bring us closer to the design direction introduced on githubuniverse.com in 2025.

This Discussion post will focus on the first set of changes: Typography 🔤.

Jump to section:

1. What changed
2. How to upgrade
3. Why we revamped our type scale

What changed

• All heading and body weights and sizes have been updated globally.
• Mona Sans and Mona Sans Mono have been upgraded to their latest versions.
• Mona Sans Mono is now our default monospace typeface.

How to upgrade

This release contains various breaking changes. Review the detailed information on the release notes carefully and validate the updated typography in you project.

npm install @primer/react-brand@0.61.0

Font weight updates

The Heading component now uses a different default font weight range, but no sizes have been removed. If you need to revert to the previous weight, you can use the weight prop.

<Heading weight="900">My heading</Heading>

Text wrapping

Headings now use text-wrap: balance by default. You can disable this behavior using the textWrap prop, if needed.

<Heading textWrap="none">My heading</Heading>

Font file locations

The location of the Mona Sans font file has changed. If you were importing the font into your project, you will need to update the import path.

- @primer/react-brand/fonts/MonaSans.woff2
+ @primer/react-brand/fonts/MonaSansVF[wdth,wght,opsz].woff2

Why we revamped our type scale

GitHub’s surfaces were using three competing systems for typography: the Primer brand scale, the Refactor scale, and a legacy blog scale that had not been updated in years. Each of these was built with slightly different goals and constraints, and when combined, the result was a scattered typographic landscape with too many heading options, inconsistent hierarchies, and size jumps that were not calibrated for editorial reading.

The updated type scale simplifies the system, standardizes hierarchy, and creates one shared foundation for GitHub interfaces. It removes unnecessary variants, aligns us to proven industry standards, and creates a more consistent typographic rhythm across web, tablet, and mobile.

Key Improvements

1. Consolidated duplicated heading variants

Several GitHub surfaces relied on heading styles that served the same role but differed slightly in size, weight, or spacing. Although these differences were minor, they resulted in inconsistent hierarchy and made it harder to apply typography consistently from page to page.

The updated scale consolidates these overlapping styles into a single, clearly defined set of headings. Each level now has a consistent size, weight, and intended role across surfaces. This removes redundancy without reducing flexibility, making the system easier to understand, apply, and maintain.

For readers, this results in clearer hierarchy and more predictable structure. For designers and engineers, it reduces decision overhead and removes the need to choose between near-identical options that behave differently depending on context.

2. A scale tuned around proportion, hierarchy, and balance

The updated scale introduces two stable anchors for smaller headings: 28px and 22px. These values sit comfortably below primary headings and above body copy, keeping hierarchy clear at a glance. They also scale more smoothly across desktop, tablet, and mobile breakpoints.

Larger headings received similar attention. Display now sits at 64, Heading 1 at 56px and Heading 2 at 48px. This fills in large jumps and creates a smoother progression without expanding the system.

The intent was not to shrink everything, but to remove extremes and bring the full scale into better balance.

3. Weight adjustments that favor clarity over boldness

Our previous typographic weights leaned heavy, especially on large headings. While bold settings create a strong presence, they can also overpower surrounding content and make type feel visually dense.

The new weights are tuned to Mona Sans variable values that feel more neutral and technical, while still maintaining hierarchy through contrast in size, spacing, and structure:

Display: 425
H1 and H2: 440
H3 and H4: 460
H5 and H6: 480

We intend this to create a calmer reading experience and a more balanced relationship between headings, supporting content, and UI components.

4. Subtle spacing refinements

Letter spacing now defaults to zero for headings, allowing Mona Sans to carry its own optical adjustments. Body copy adds a minimal 1% percent spacing boost for comfort in longer text blocks. Line heights were lightly tuned to normalize density, improve scan comfort, and keep rhythm consistent.

These changes are not intended to shift the voice of the type, but to reduce micro inconsistencies that add up when layouts become more complex.

5. Consistent behavior across breakpoints

The previous scale had large jumps at smaller screen sizes, causing oversized headings and inefficient vertical spacing. The updated scale is designed to hold hierarchy without dominating the viewport.

On tablet and mobile, sizes reduce proportionally, spacing tightens slightly, and the number of steps between levels remains small. The outcome is a system that feels consistent, adaptable, and easier to reason about when designing responsively.

What the updated scale achieves:

• A single shared hierarchy model across brand, product, and supporting surfaces
• Reduced cognitive load for both readers and makers
• More predictable hierarchy cues from page to page
• A tighter progression between type levels, with fewer outliers
• Improved behavior at tablet and mobile breakpoints
• Cleaner, more modern expression without losing identity

Instead of three overlapping scales, we now have one system with clear structure, smoother transitions, and enough flexibility for a wide range of content types.

The goal isn’t just aesthetic refinement; it’s about removing friction, clarifying hierarchy, and creating a foundation that supports how GitHub communicates at scale.

---

This is just the first of several milestone releases coming to Primer Brand this year. Stay tuned to our releases page for more updates.

Thanks to the team that made this happen: @jesussandreas @simmonsjenna @kylewaynebenson @rezrah @danielguillan

Have any questions or feedback? Drop them in the comments below.