Primer Design System - GitHub's Component Library

Primer Design System is GitHub's component library. If you've used GitHub.com, you've seen Primer - every button, form, and input field uses these components.

Primer exists because GitHub got tired of their UI looking like shit across different teams. Every component follows the same patterns so you can't fuck up the interface. It's their internal system made public, which means you get components that have been stress-tested by 100+ million developers doing weird stuff you never thought of.

How Primer is Split Up

Primer has three parts because GitHub learned the hard way that one-size-fits-all design systems are bullshit:

Primer Product UI - 50+ React components for building actual applications. Current version is around v37. Components like ActionList, TreeView, and DataTable that don't completely shit themselves when you're displaying thousands of repository entries.

Primer Brand UI - Marketing site components because using product components for landing pages makes everything look like a developer tool. Nobody wants their marketing site to look like a GitHub issue tracker.

Octicons - 300+ icons designed for developer workflows. These aren't generic icons - they cover things like merge conflicts and CI status that regular icon libraries ignore.

The CSS Modules Migration That Actually Mattered

Version 37 ditched styled-components for CSS Modules, which was huge. GitHub wasn't following trends - their engineering team was pissed about bundle size bloat and shitty runtime performance.

What they fixed:

• Bundle sizes got ~30% smaller
• No more runtime CSS generation killing page loads
• Build times stopped sucking
• CSS debugging that doesn't make you want to quit

The dependencies now:

• @primer/react - Main components
• @primer/primitives - Design tokens
• styled-components@5.x - Legacy shit they're trying to kill

Revolutionary concept, I know - only took the industry 10 years to figure out designers and devs should use the same specs.

Why Primer is Different

Most design systems are academic bullshit. Primer runs GitHub.com, which means 100+ million developers use it daily. When a Primer component breaks, it breaks for more developers than most companies will ever see.

Real-world edge cases it handles:

• File trees with 10,000+ files (try that with Material-UI)
• Code review threads that span months
• Repository settings with hundreds of options
• Notification feeds processing thousands of events daily

Companies like OpenProject migrated specifically because it's battle-tested. When your design system survives GitHub's scale, you know it won't shit itself the moment you hit production traffic.

Getting Started - What They Don't Tell You

Primer setup is pretty straightforward, but there are gotchas:

npm install @primer/react @primer/primitives styled-components@5.x

Three packages, but styled-components is legacy shit they're trying to phase out. You'll get deprecation warnings. React 18+ works fine, but if you're stuck on 17, you'll need the compatibility layer and some patience.

Minimal setup:

import '@primer/primitives/dist/css/functional/themes/light.css'
import {BaseStyles, ThemeProvider, Button} from '@primer/react'

function App() {
  return (
    <ThemeProvider>
      <BaseStyles>
        <Button>This actually works</Button>
      </BaseStyles>
    </ThemeProvider>
  )
}

Critical gotcha: ThemeProvider must wrap your entire app or random components will render with broken styles. Learned that the hard way debugging why buttons looked fucked up.

The CSS Modules Migration - Performance Reality

Version 37 ditched styled-components because GitHub's team was dealing with real performance problems in production:

Before (styled-components hell):

• Runtime CSS generation killed initial page loads
• Bundle sizes bloated because tree-shaking was shit
• Debugging dynamic styles made you want to quit engineering
• Build times got progressively worse

After (CSS Modules):

• CSS processes at build time (much faster)
• ~30% smaller bundles in most real apps
• Tree-shaking that actually works
• CSS debugging that doesn't make you hate your life

Bundle size reality check: That 45KB is optimistic. Import ActionList, DataTable, and Dialog and you're looking at 80KB+ in real applications. Bundle analysis shows most projects import like 30% of components they never use because devs are lazy. Migration from CSS to React isn't terrible, but plan for a weekend of fixing prop names.

What They Actually Test Against

Primer gets tested against the real world because it runs GitHub.com:

• Users with 200+ browser extensions that break CSS in weird ways
• Corporate proxies that mangle JavaScript
• Ancient screen readers that developers forgot exist
• Mobile devices with 512MB RAM running browsers from 2018
• Accessibility auditors who will fail your shit for missing aria-describedby

WCAG 2.1 AA compliance isn't marketing bullshit - GitHub gets sued if their components break screen readers. Most other design systems treat accessibility as an afterthought.

Migration Reality

Migration guides include automated codemods because GitHub updates hundreds of components across their codebase. They're not doing manual find-and-replace like savages.

Version updates follow semantic versioning. Breaking changes include:

• Automated migration scripts (when possible)
• Deprecation warnings with upgrade paths
• Clear timelines (no surprise breaking changes)
• Technical explanations of why they broke your shit

Developer Experience Reality

Figma Integration: The official Figma library actually matches the React implementation. Designers can't spec impossible component states that don't exist in code.

TypeScript Support: Built-in definitions with good autocomplete. No @types/ packages that break every time you update. TypeScript definitions mean your IDE will autocomplete props and catch your dumb mistakes before runtime - no more wondering if it's 'variant' or 'size'.

Testing: Works with Jest and React Testing Library. No weird mocking requirements or custom test utilities to learn.

The catch: Some Primer components have wonky TypeScript generics that make your IDE confused. ActionList is particularly annoying with its type definitions - expect to wrestle with generic constraints for an hour.