README
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 filesdist/json
contains JSON files for each set of primitivesdist/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 viarequire('@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 approriate 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/deprected
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