@primer/primitives 4.8.1 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @primer/primitives
 
+## 5.0.0
+
+### Major Changes
+
+- [#245](https://github.com/primer/primitives/pull/245) [`65ad2df`](https://github.com/primer/primitives/commit/65ad2df4d19f1eac86778879266bab6648ebe0e4) Thanks [@colebemis](https://github.com/colebemis)! - All deprecated color variables have been removed. See [removed variables](https://primer.style/primitives/colors#removed-variables) for the complete list of removed variables.
+
+* [#245](https://github.com/primer/primitives/pull/245) [`65ad2df`](https://github.com/primer/primitives/commit/65ad2df4d19f1eac86778879266bab6648ebe0e4) Thanks [@colebemis](https://github.com/colebemis)! - The `deprecations` directory in the `dist` directory has been renamed to `deprecated`:
+
+  ```diff
+  dist/
+  - deprecations/
+  + deprecated/
+  ```
+
+  You'll need to update your imports accordingly:
+
+  ```diff
+  - import deprecatedColors from '@primer/primitives/dist/deprecations/colors.json'
+  + import deprecatedColors from '@primer/primitives/dist/deprecated/colors.json'
+  ```
+
+### Minor Changes
+
+- [#245](https://github.com/primer/primitives/pull/245) [`65ad2df`](https://github.com/primer/primitives/commit/65ad2df4d19f1eac86778879266bab6648ebe0e4) Thanks [@colebemis](https://github.com/colebemis)! - The [`dist`](https://unpkg.com/browse/@primer/primitives/dist/) directory now contains a `removed` directory with data about removed variables organized by category:
+
+  ```diff
+    dist/
+      js/
+      ts/
+      json/
+      scss/
+      deprecated/
+  +   removed/
+  +     colors.json
+  ```
+
+  Each JSON file in the `removed` directory contains a mapping of removed variables to replacement variables. Example:
+
+  ```js
+  // dist/removed/colors.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
+  }
+  ```
+
+  This data will allow you to write linters to prevent usage of removed variables.
+
+### Patch Changes
+
+- [#250](https://github.com/primer/primitives/pull/250) [`9948e13`](https://github.com/primer/primitives/commit/9948e139bcdd360bccb939aab27992ac06b3a3bf) Thanks [@Juliusschaeper](https://github.com/Juliusschaeper)! - Fix duplicate hex value (red 9)
+
 ## 4.8.1
 
 ### Patch Changes

package/README.md

@@ -2,6 +2,9 @@
 
 This repo contains values for color, spacing, and typography primitives for use with [Primer][primer], GitHub's design system.
 
+![primer primitives diagram](https://user-images.githubusercontent.com/4608155/135384588-192c279f-020f-4544-a61f-559be6629f18.png)
+
+
 ## Install
 
 This repository is distributed on [npm][npm]. After [installing npm][install-npm], you can install `@primer/primitives` with this command.
@@ -14,9 +17,101 @@ $ npm install --save @primer/primitives
 
 Primitive data is served in several formats from the `dist/` folder:
 
-* `dist/scss` contains [SCSS][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.
+- `dist/scss` contains [SCSS][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 approriate subdirectory of `data`:
+
+```diff
+  data/
+    colors/
++     deprecated.json
+    spacing/
+    ...
+```
+
+```js
+// 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:
+
+```diff
+  dist/
+    js/
+    ts/
+    json/
+    scss/
++   deprecated/
++     colors.json
+```
+
+## Removing variables
+
+When you're ready to remove a variable, first remove it's definitions:
+
+```diff
+// data/colors/vars/global_light.ts
+import {get} from '../../../src/utils'
+
+export default {
+  text: {
+-   primary: get('scale.gray.9'),
+    secondary: get('scale.gray.6')
+  }
+}
+```
+
+```diff
+// 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`:
+
+```diff
+// data/colors/deprecated.json
+{
+- "text.primary": "fg.default"
+}
+```
+
+```diff
+// 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:
+
+```diff
+  dist/
+    js/
+    ts/
+    json/
+    scss/
+    deprecated/
++   removed/
++     colors.json
+```
 
 ## License
 

package/dist/deprecated/colors.json

@@ -0,0 +1 @@
+{}