@primer/primitives 8.0.0-rc.2e61fcd8 → 8.0.0-rc.473cfc21
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +94 -28
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -16,43 +16,109 @@ npm install --save @primer/primitives
|
|
|
16
16
|
|
|
17
17
|
## Usage
|
|
18
18
|
|
|
19
|
-
[Storybook](https://primer.style/primitives/storybook) | [Docs](https://primer.style/
|
|
19
|
+
[Storybook](https://primer.style/primitives/storybook) | [Docs](https://primer.style/primitives/)
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
Primitive data is served in several formats from the `dist/` folder:
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
- `dist/scss` contains [SCSS][scss] files that define CSS variables to be imported into other SCSS files
|
|
24
|
+
- `dist/json` contains JSON files for each set of primitives
|
|
25
|
+
- `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.
|
|
24
26
|
|
|
25
|
-
|
|
27
|
+
## Deprecating variables
|
|
26
28
|
|
|
27
|
-
|
|
29
|
+
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`:
|
|
28
30
|
|
|
31
|
+
```diff
|
|
32
|
+
data/
|
|
33
|
+
colors/
|
|
34
|
+
+ deprecated.json
|
|
35
|
+
spacing/
|
|
36
|
+
...
|
|
29
37
|
```
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
// data/colors/deprecated.json
|
|
41
|
+
|
|
42
|
+
{
|
|
43
|
+
"text.primary": "fg.default", // this means: `text.primary` is deprecated. Use `fg.default` instead
|
|
44
|
+
"auto.blue.4": ["accent.fg, accent.emphasis"], // this means: `auto.blue.4` is deprecated. Use `accent.fg` or `accent.emphasis` instead
|
|
45
|
+
"text.white": null // this means: `text.white` is deprecated. We don't have a replacement for it
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
During the build process, the `deprecated.json` files will be added to a `dist/deprecated` directory organized by variable category:
|
|
51
|
+
|
|
52
|
+
```diff
|
|
53
|
+
dist/
|
|
54
|
+
js/
|
|
55
|
+
ts/
|
|
56
|
+
json/
|
|
57
|
+
scss/
|
|
58
|
+
+ deprecated/
|
|
59
|
+
+ colors.json
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Removing variables
|
|
63
|
+
|
|
64
|
+
When you're ready to remove a variable, first remove it's definitions:
|
|
65
|
+
|
|
66
|
+
```diff
|
|
67
|
+
// data/colors/vars/global_light.ts
|
|
68
|
+
import {get} from '../../../src/utils-v1'
|
|
69
|
+
|
|
70
|
+
export default {
|
|
71
|
+
text: {
|
|
72
|
+
- primary: get('scale.gray.9'),
|
|
73
|
+
secondary: get('scale.gray.6')
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
```diff
|
|
79
|
+
// data/colors/vars/global_dark.ts
|
|
80
|
+
import {get} from '../../../src/utils-v1'
|
|
81
|
+
|
|
82
|
+
export default {
|
|
83
|
+
text: {
|
|
84
|
+
- primary: get('scale.gray.1'),
|
|
85
|
+
secondary: get('scale.gray.3')
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Then remove it from `deprecated.json` and add it to `removed.json`:
|
|
91
|
+
|
|
92
|
+
```diff
|
|
93
|
+
// data/colors/deprecated.json
|
|
94
|
+
{
|
|
95
|
+
- "text.primary": "fg.default"
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
```diff
|
|
100
|
+
// data/colors/removed.json
|
|
101
|
+
{
|
|
102
|
+
+ "text.primary": "fg.default"
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
During the build process, the `removed.json` files will be added to a `dist/removed` directory organized by variable category:
|
|
107
|
+
|
|
108
|
+
```diff
|
|
109
|
+
dist/
|
|
110
|
+
js/
|
|
111
|
+
ts/
|
|
112
|
+
json/
|
|
113
|
+
scss/
|
|
114
|
+
deprecated/
|
|
115
|
+
+ removed/
|
|
116
|
+
+ colors.json
|
|
51
117
|
```
|
|
52
118
|
|
|
53
|
-
##
|
|
119
|
+
## V8 Tokens
|
|
54
120
|
|
|
55
|
-
|
|
121
|
+
With `/primitives` version 8, design tokens have been moved to json files in the [src/tokens](./src/tokens/) directory. Those tokens are compiled with [style dictionary](https://amzn.github.io/style-dictionary/#/) in [scripts/buildTokens.ts](./scripts/buildTokens.ts).
|
|
56
122
|
|
|
57
123
|
To make working with tokens easier, we added some additional functionality on top of what style dictionary comes with:
|
|
58
124
|
|