README.md

Primer Primitives

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

Install

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

$ npm install --save @primer/primitives

Usage

Primitive data is served in several formats from the dist/ folder:

• dist/scss contains SCSS files that define CSS variables to be imported into other SCSS files
• dist/json contains JSON files for each set of primitives
• dist/js contains CommonJS-style JavaScript modules for each set of primitives, as well as an index file that loads all of the primitives for all primitive types; you can access this via require('@primer/primitives'). The JavaScript modules also include TypeScript typings files for use in TypeScript projects.

Deprecating variables

To deprecate a variable, define a mapping from the deprecated variable to its replacement(s) in a file called deprecated.json in the appropriate subdirectory of data:

  data/
    colors/
+     deprecated.json
    spacing/
    ...

// data/colors/deprecated.json

{
  "text.primary": "fg.default", // this means: `text.primary` is deprecated. Use `fg.default` instead
  "auto.blue.4": ["accent.fg, accent.emphasis"], // this means: `auto.blue.4` is deprecated. Use `accent.fg` or `accent.emphasis` instead
  "text.white": null // this means: `text.white` is deprecated. We don't have a replacement for it
}

During the build process, the deprecated.json files will be added to a dist/deprecated directory organized by variable category:

  dist/
    js/
    ts/
    json/
    scss/
+   deprecated/
+     colors.json

Removing variables

When you're ready to remove a variable, first remove it's definitions:

// data/colors/vars/global_light.ts
import {get} from '../../../src/utils'

export default {
  text: {
-   primary: get('scale.gray.9'),
    secondary: get('scale.gray.6')
  }
}

// data/colors/vars/global_dark.ts
import {get} from '../../../src/utils'

export default {
  text: {
-   primary: get('scale.gray.1'),
    secondary: get('scale.gray.3')
  }
}

Then remove it from deprecated.json and add it to removed.json:

// data/colors/deprecated.json
{
- "text.primary": "fg.default"
}

// data/colors/removed.json
{
+ "text.primary": "fg.default"
}

During the build process, the removed.json files will be added to a dist/removed directory organized by variable category:

  dist/
    js/
    ts/
    json/
    scss/
    deprecated/
+   removed/
+     colors.json

License

MIT © GitHub