Primer React

Primer React is GitHub’s official component library, implementing the Primer Design System in React. It ships the same accessible, themeable UI primitives — buttons, forms, overlays, navigation, data tables — that power GitHub.com itself, alongside a documented theming system built on CSS custom properties.

The package is organized into a stable public API plus /experimental, /deprecated, and /next sub-exports, so teams migrating between component generations or trying unreleased components can opt in explicitly without affecting the main entry point.

What You Get

• A large catalog of accessible React components (ActionList, Dialog, Overlay, DataTable, Avatar, Autocomplete, and dozens more) matching GitHub’s production UI
• A CSS-custom-property theming system supporting light/dark and high-contrast color modes out of the box
• Separate /experimental, /deprecated, and /next entry points for staged adoption of new or legacy components without breaking the stable API
• Generated components.json/hooks.json metadata describing the component API surface, useful for docs tooling or codemods
• An official MCP server package (@primer/mcp) in the same monorepo for AI-assisted component discovery

Common Use Cases

• Building internal tools or GitHub Apps that want GitHub-native look and feel
• Adopting an accessible, pre-tested component set instead of building UI primitives from scratch
• Migrating an app off deprecated Primer components using the /deprecated and /next sub-exports as a staged path
• Theming a product to support light, dark, and high-contrast modes using Primer’s CSS variable system

Under The Hood

Architecture: Primer React is one package (packages/react) inside a Turborepo/npm-workspaces monorepo that also holds @primer/mcp, a rolldown CSS-import plugin, and Storybook example apps. The library’s src/ directory is organized per-component (one folder per component, e.g. ActionList/, Dialog/, DataTable/), each colocating its TypeScript implementation, CSS module, tests, and stories; components are re-exported through stable, experimental, deprecated, and next-generation entry points defined in package.json’s exports map, letting the build emit separate bundles (dist/index.js, dist/experimental/index.js, dist/deprecated/index.js, dist/next/index.js) from one source tree. Tech Stack: TypeScript (91% of the codebase) with CSS Modules for styling, built via a custom script/build pipeline, tested with Vitest (unit) and Playwright (visual regression, snapshot images checked into .playwright/snapshots), linted with ESLint (@eslint-react plugin) and Stylelint, and versioned/published via Changesets. Code Quality: every component folder has a co-located __tests__/.test.tsx file and a classname-coverage script enforcing that public CSS class names stay under test; the monorepo also runs tsc --noEmit type-checking and axe-based accessibility checks (@github/axe-github) as part of CI. API Design: components follow consistent naming and prop conventions across the catalog (compound components like ActionList.Item, Dialog.Header), TypeScript types ship with every export, and the documentation site (primer.style/react) provides live, editable examples for each component — though the sheer size of the API surface (100+ components across four entry points) means the learning curve is nontrivial for newcomers.