Primer CSS

Primer CSS is the Sass/SCSS implementation of GitHub’s Primer Design System — the same visual language that powers github.com. It ships as a set of modular stylesheets covering core primitives (typography, layout, color modes), product UI components (buttons, forms, navigation, tooltips, labels, pagination), and marketing patterns, all composable via @import so consumers only pull in what they need.

The project is explicitly in maintenance (“KTLO”) mode: GitHub now recommends primer/react or primer/view_components for new component-driven work, positioning Primer CSS as the stable low-level utility and class layer underneath those higher-level libraries, or for teams that want GitHub’s visual system without a JavaScript component framework.

What You Get

• Modular SCSS partials for core, product, and marketing UI split by concern (buttons, forms, layout, navigation, tooltips, labels, pagination, avatars)
• A compiled dist/primer.css bundle plus an ESM/CJS classnames export listing every known class for tooling and lint integrations
• Built-in color-mode mixins supporting GitHub’s light/dark/high-contrast theme variables
• A deprecations registry (deprecations.json / deprecations.js) that maps old selectors to their replacements across major versions
• Stylelint config integration (@primer/stylelint-config) and CI-enforced linting for consistent SCSS authoring

Common Use Cases

• Building internal tools or admin UIs that should visually match GitHub without adopting React
• Styling GitHub Apps, Actions custom UIs, or browser extensions that need to feel native to github.com
• Providing the underlying utility classes consumed by primer/react and primer/view_components components
• Auditing or migrating a legacy GitHub-styled codebase using the deprecations map and selector-diff tooling
• Prototyping GitHub-style layouts quickly with prebuilt Box, layout, and typography utility classes

Under The Hood

Architecture The codebase is organized as independently importable SCSS modules under src/ (base, box, buttons, forms, layout, navigation, pagination, tooltips, utilities, plus product/marketing groupings), each aggregated through an index.scss that composes a support/ layer of shared variables and mixins first, then component partials, with utility classes imported last so they can override component-level styles — a clear, deliberate cascade-ordering strategy rather than a flat stylesheet. A Node-based build pipeline (script/build-css.js, script/dist.js) compiles the Sass to dist/primer.css and derives a classnames module (ESM/CJS/.d.ts) enumerating every emitted class, which downstream tooling (linters, primer/react) consumes to validate class usage against the framework. Tech Stack The framework is pure Sass/SCSS (PostCSS-based build via postcss, postcss-calc, postcss-import, autoprefixer) with a thin Node.js/JavaScript layer for build scripts, the classnames export, and a deprecation-tracking system; @primer/primitives is a required peer dependency supplying the underlying design tokens, and Storybook (in docs/) hosts the component documentation site. Code Quality Testing is Jest-based (__tests__/css.test.js, build.test.js, docs.test.js) and focuses on build-output invariants — verifying the classnames export is non-empty and well-formed, that deprecated selectors never equal their replacements, and that generated stats/diffs match expectations — rather than visual/unit testing of individual components, which is appropriate for a stylesheet package. Stylelint and ESLint (via @primer/stylelint-config and eslint-plugin-github) run in CI alongside Jest, and Changesets manages versioning/changelog generation, giving the project consistent linting and release discipline despite the unconventional (non-visual) test surface. What Makes It Unique Unlike general-purpose CSS frameworks, Primer CSS is the literal production stylesheet layer for github.com, tracked release-for-release against GitHub’s live design system, with an explicit deprecation/migration mechanism (migrations/v16.md, v18.md, selector-diff reporting) that lets consumers upgrade major versions with a generated diff of what changed — a level of upgrade tooling most CSS frameworks don’t provide.