# @primer/primitives

> Typography, spacing, and color primitives for Primer design system

Latest version **11.10.0** (published 2026-07-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install @primer/primitives
pnpm add @primer/primitives
yarn add @primer/primitives
bun add @primer/primitives
```

## Health

**Score 65/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types; large bundle.

## Facts

| | |
|---|---|
| Version | 11.10.0 |
| Published | 2026-07-30 |
| First published | 2019-03-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 0 |
| Unpacked size | 54.9 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 408 |
| Author | GitHub, Inc. |
| Maintainers | primer-css |
| Keywords | primitives, colors, spacing, typography, variables, design-system |

## Links

- npm: https://www.npmjs.com/package/@primer/primitives
- Repository: https://github.com/primer/primitives
- Homepage: https://github.com/primer/primitives#readme
- Issues: https://github.com/primer/primitives/issues
- npm.io page: https://npm.io/package/@primer/primitives

## Alternatives

- [postcss-color-hex-alpha](https://npm.io/package/postcss-color-hex-alpha.md) — 6.4M weekly downloads
- [randomcolor](https://npm.io/package/randomcolor.md) — 348.0K weekly downloads
- [bows](https://npm.io/package/bows.md) — 1.3K weekly downloads
- [ep_prefer_color_scheme](https://npm.io/package/ep_prefer_color_scheme.md) — 260 weekly downloads
- [coc-yank](https://npm.io/package/coc-yank.md) — 61 weekly downloads

## Recent versions

- 11.10.0 (latest) — 2026-07-30
- 0.0.0-20260909104418 (canary) — 2026-09-09
- 11.10.0-rc.3645ebea (next) — 2026-07-30
- 10.0.0-rc.8406ac7b (next-major) — 2024-11-25
- 0.0.0-20260902200110 — 2026-09-02
- 0.0.0-20260902194223 — 2026-09-02
- 0.0.0-20260901222934 — 2026-09-01
- 0.0.0-20260901220421 — 2026-09-01
- 0.0.0-20260810090144 — 2026-08-10
- 0.0.0-20260805163820 — 2026-08-05
- 0.0.0-20260730211557 — 2026-07-30
- 0.0.0-20260729190608 — 2026-07-29
- 0.0.0-20260729185604 — 2026-07-29
- 11.10.0-rc.b9a4d7fd — 2026-07-29
- 0.0.0-20260729064256 — 2026-07-29
- … 5367 more at https://npm.io/package/@primer/primitives/versions

## README

# Primer Primitives

[![npm package](https://img.shields.io/npm/v/@primer/primitives.svg?style=flat)](https://www.npmjs.com/package/@primer/primitives) [![Storybook](https://github.com/primer/primitives/actions/workflows/deploy.yml/badge.svg)](https://primer.style/primitives/storybook/) [![A11y contrast check](https://github.com/primer/primitives/actions/workflows/a11y-contrast.yml/badge.svg)](https://github.com/primer/primitives/actions/workflows/a11y-contrast.yml)

This repo contains values for color, spacing, and typography primitives for use with [Primer][primer], GitHub's design system.

![primer primitives diagram showing how the package connects with other primer libraries](./readme-light.png#gh-light-mode-only)
![primer primitives diagram showing how the package connects with other primer libraries](./readme-dark.png#gh-dark-mode-only)

## Install

This repository is distributed on [npm][npm]. After [installing npm][install-npm], you can install `@primer/primitives` with this command.

```sh
npm install --save @primer/primitives
```

## Usage

[Storybook](https://primer.style/primitives/storybook) | [Docs](https://primer.style/foundations/primitives/getting-started)

See [Primitives documentation](https://primer.style/foundations/primitives/getting-started) for more information on theming and using CSS variables.

Data is served from the `dist/` folder:

- `dist/css` contains CSS files with values available as CSS variables

All available imports:

```css
/* size/typography */
@import '@primer/primitives/dist/css/base/size/size.css';
@import '@primer/primitives/dist/css/base/typography/typography.css';
@import '@primer/primitives/dist/css/functional/size/border.css';
@import '@primer/primitives/dist/css/functional/size/breakpoints.css';
@import '@primer/primitives/dist/css/functional/size/size.css';
@import '@primer/primitives/dist/css/functional/size/viewport.css';
@import '@primer/primitives/dist/css/functional/typography/typography.css';

/* motion */
@import '@primer/primitives/dist/css/base/motion/motion.css';

/* spacing */
@import '@primer/primitives/dist/css/functional/spacing/space.css';

/* color */
@import '@primer/primitives/dist/css/functional/themes/light.css';
@import '@primer/primitives/dist/css/functional/themes/light-tritanopia.css';
@import '@primer/primitives/dist/css/functional/themes/light-high-contrast.css';
@import '@primer/primitives/dist/css/functional/themes/light-colorblind.css';
@import '@primer/primitives/dist/css/functional/themes/dark.css';
@import '@primer/primitives/dist/css/functional/themes/dark-colorblind.css';
@import '@primer/primitives/dist/css/functional/themes/dark-dimmed.css';
@import '@primer/primitives/dist/css/functional/themes/dark-high-contrast.css';
@import '@primer/primitives/dist/css/functional/themes/dark-tritanopia.css';
```

> **Note:** Motion CSS imports are required for components with animations, such as `Spinner` from `@primer/react`. If you're experiencing issues with animated components appearing static, ensure you've imported the motion CSS files.
>
> **Note:** Spacing tokens provide a unified semantic scale for `gap`, `padding`, and `margin`. Import `functional/spacing/space.css` to use `--space-*` tokens in your components.

## Design token data

Design token data is stored in the [src/tokens](./src/tokens/) directory. These tokens are compiled with [style dictionary](https://styledictionary.com) in [scripts/buildTokens.ts](./scripts/buildTokens.ts).

To make working with tokens easier, we added some additional functionality on top of what style dictionary comes with:

### Extending and Overwriting

We have two main color modes: `light` and `dark`. Additionally we have specific accessibility modes based on those, such as `light high contrast`.

We added a way to create a mode by only including the changes from the main mode. We call this `overrides`.
`Overrides` are created in `src/tokens/functional/color/[light|dark]/overrides/` and have to be added to [themes.config.ts](./scripts/themes.config.ts) to work.
In the individual files, e.g. `light.high-contrast.json5` you can now add tokens in the same structure as in any main file, e.g. `primitives-light.json5` to replace them.

### Transforming Colors with Alpha and Mix

#### Alpha

You can create color tokens that inherit a color but have a different alpha value by adding the `alpha` property.
**Note:** The original alpha value will be replaced by your value. If you add `alpha: 0.4` to a color, it doesn't matter if the color you reference has no `alpha` or `alpha: 0.7`, the new token will always have newly the defined value of `alpha: 0.4`.

```json5
{
  muted: {
    $value: '{base.color.blue.3}',
    alpha: 0.4, // the opacity value of the color === 40% opaque
    $type: 'color',
  },
}
```

#### Extensions property

According to the [w3c design token specs](https://design-tokens.github.io/community-group/format/#design-token), the [`$extensions`](https://design-tokens.github.io/community-group/format/#extensions) property is used for additional meta data.

For our Figma export we use the following meta data:

- `collection` the collection that the token is added to within Figma
- `mode` the mode that the token is added to within the collection in Figma
- `scopes` the scopes that are assigned to the token in Figma, the actual Figma compatible `scopes` are retrieved from an object in the [figmaAttributes transformer](./src/transformers/figmaAttributes.ts)

Code example

```json5
  bgColor: {
    $value: '{borderColor.accent.muted}',
    $type: 'color',
    $extensions: {
      'org.primer.figma': {
        collection: 'pattern/mode',
        mode: 'light',
        scopes: ['bgColor'],
      },
    },
  }
```

#### Token names and @-hack

Token names have to be in camelCase or kebab-case and may only include letters, numbers and `-`. This is enforced by the token validation (`npm run lint:tokens`).
The only exception is the `@`-hack. This is used when you want to have a default value and sub-values, e.g. `bgColor.accent` and `bgColor.accent.muted`.
In this case you can create the following structure. The `@` will be removed from the name and act as the default value.

```json5
{
  bgColor: {
    accent: {
      '@': {
        // values for bgColor-accent (default)
      },
      muted: {
        // values for bgColor-accent-muted
      },
    },
  },
}
```

## License

[MIT](./LICENSE) © [GitHub](https://github.com/)

[primer]: https://github.com/primer/primer
[npm]: https://www.npmjs.com/
[install-npm]: https://docs.npmjs.com/getting-started/installing-node

---
_Source: https://npm.io/package/@primer/primitives · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._