Primer CSS Utilities

5.0.0 · abandoned · verified Tue Apr 21

primer-utilities provides a collection of immutable, atomic CSS utility classes, designed to facilitate rapid UI development. It forms a foundational part of the Primer Design System, originally developed by GitHub to style its own interfaces. The package's philosophy emphasizes single-purpose classes to promote consistency and reduce custom CSS. The current stable version is 5.0.0, published in January 2019. This standalone package is now superseded by modules within the @primer/css monorepo, which represents the actively maintained version of Primer. While primer-utilities@5.0.0 remains available on npm, it is no longer actively developed or directly maintained as a separate entity.

Common errors

```
Error: Can't find stylesheet to import. @import "primer-utilities/index.scss";
```
cause The Sass compiler cannot locate the `primer-utilities` package within `node_modules` or the specified include paths.

fix Ensure `node_modules` is included in your Sass compiler's load paths. For example, with Node-Sass or Dart Sass: `sass --load-path=node_modules styles.scss:styles.css`.
```
Primer utility classes (e.g., `m-4`, `p-responsive`) are not applying any styles in the browser.
```
cause The compiled CSS for Primer Utilities is not being loaded or correctly linked in your HTML document.

fix Verify that your build process successfully compiles your SCSS (including `@import "primer-utilities/index.scss";`) into a CSS file, and that this compiled CSS file is correctly linked in your HTML's `<head>` section, e.g., `<link rel="stylesheet" href="/path/to/your-compiled-styles.css">`.
```
My custom CSS is being overridden by Primer utility classes, even with supposedly higher specificity.
```
cause Specificity conflict where Primer's utility classes have a higher CSS specificity or appear later in the cascade than your custom styles.

fix Carefully increase the specificity of your custom CSS selectors, or ensure your custom stylesheets are loaded *after* Primer Utilities. For critical overrides, consider using a more specific utility class or modifying the component structure, avoiding `!important` where possible.

Warnings

breaking The `primer-utilities` npm package is officially deprecated. Its code and active development have been migrated into the larger `@primer/css` monorepo. Developers should transition to using `@primer/css` for active maintenance, updates, and new features.
Fix: Migrate your project to use the `@primer/css` package instead of `primer-utilities`. This may involve updating import paths and potentially adjusting to newer class names or architectural changes in `@primer/css`.
deprecated The standalone `primer-utilities` package has not received updates since version 5.0.0, published in January 2019. It is considered unmaintained, and relying on it for new projects or expecting bug fixes is not advisable.
Fix: Consider updating to the actively maintained `@primer/css` package to benefit from ongoing development, bug fixes, and compatibility with modern web standards and tooling.
gotcha Direct manipulation of `primer-utilities` SCSS files or variables (e.g., overriding in `node_modules`) is highly discouraged. Such modifications are fragile and will break during updates or when migrating to the `@primer/css` monorepo structure.
Fix: Always extend or override Primer styles using your own SCSS files that import `primer-utilities` first. Define custom classes with higher specificity or use Sass features like `@extend` if available in your version of Sass.
gotcha Due to its age, `primer-utilities@5.0.0` might exhibit compatibility issues with very recent versions of Sass compilers (e.g., Dart Sass) or modern PostCSS plugins, potentially leading to compilation errors or unexpected output.
Fix: If encountering compilation issues, try using an older, compatible version of your Sass compiler or consult the `@primer/css` migration guide for an actively supported setup. Alternatively, consider compiling the `build.css` once and linking it directly.

Install

npm install primer-utilities npm
yarn add primer-utilities yarn
pnpm add primer-utilities pnpm

Imports

index.scss
```
@import "primer-utilities/index.scss";
```
This is the primary way to import all utilities when using a Sass/SCSS preprocessor. Ensure your Sass compiler's include paths are configured to find `node_modules`.
CSS File
```
<link rel="stylesheet" href="/path/to/node_modules/primer-utilities/build/build.css">
```
For direct browser usage, link to the pre-compiled CSS file. The `build.css` is included in the npm package.
Specific Partial
```
@import "primer-utilities/lib/align";
```
You can import individual utility partials from the `/lib/` folder if you only need a subset of the utilities, reducing bundle size.

Quickstart

Demonstrates how to import Primer Utilities via Sass and apply basic spacing, display, and typography classes to an HTML element. The compiled CSS needs to be linked in the HTML.

/* styles.scss */
@import "primer-utilities/index.scss";

body {
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
  line-height: 1.5;
}

.my-component {
  background-color: var(--color-bg-default);
  border: var(--border-width-thin) solid var(--color-border-default);
  border-radius: var(--border-radius-2);
}

// To compile:
// npx sass styles.scss:styles.css

<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Primer Utilities Quickstart</title>
    <link rel="stylesheet" href="./styles.css">
</head>
<body>
    <div class="my-component p-4 m-3 d-flex flex-justify-center flex-items-center">
        <h1 class="f4 color-fg-default">Hello, Primer Utilities!</h1>
    </div>
    <p class="text-center mt-6">This demonstrates basic Primer Utilities usage.</p>
</body>
</html>

view raw JSON →