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

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

$ npm install --save @primer/primitives

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.

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

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

MIT © GitHub