postcss-font-family-system-ui 5.0.0 → 6.0.0

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 CHANGED
@@ -22,36 +22,42 @@ body {
22
22
  }
23
23
  ```
24
24
 
25
- ## Usage
25
+ Only fallbacks that are missing are added, so a hand-written stack, or CSS the
26
+ plugin already processed, keeps the families it lists in place. Missing
27
+ fallbacks are inserted right after `system-ui`, or after the listed fallbacks
28
+ that come before them, but before a generic family such as `sans-serif`; a
29
+ fallback listed only after a generic family is added before it as well:
26
30
 
27
- Add [postcss-font-family-system-ui] to your build tool:
31
+ ```css
32
+ body {
33
+ font-family: system-ui, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
34
+ }
28
35
 
29
- ```bash
30
- npm install postcss postcss-font-family-system-ui --save-dev
36
+ /* becomes */
37
+
38
+ body {
39
+ font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
40
+ Noto Sans, Ubuntu, Cantarell, Helvetica Neue, sans-serif;
41
+ }
31
42
  ```
32
43
 
33
- #### Node
44
+ `font-family` descriptors in `@font-face` rules are left alone, as they take a
45
+ single family name. When a value is changed, comments inside it are removed.
34
46
 
35
- Use [postcss-font-family-system-ui] to process your CSS:
47
+ ## Usage
36
48
 
37
- ```js
38
- import postcssSystemUiFont from "postcss-font-family-system-ui";
49
+ Add [postcss-font-family-system-ui] to your build tool:
39
50
 
40
- postcssSystemUiFont.process(YOUR_CSS);
51
+ ```bash
52
+ npm install postcss postcss-font-family-system-ui --save-dev
41
53
  ```
42
54
 
43
55
  #### PostCSS
44
56
 
45
- Add [PostCSS] to your build tool:
46
-
47
- ```bash
48
- npm install postcss --save-dev
49
- ```
50
-
51
57
  Use [postcss-font-family-system-ui] as a plugin:
52
58
 
53
59
  ```js
54
- import postcss from "gulp-postcss";
60
+ import postcss from "postcss";
55
61
  import postcssSystemUiFont from "postcss-font-family-system-ui";
56
62
 
57
63
  postcss([postcssSystemUiFont(/* options */)]).process(YOUR_CSS);
@@ -68,6 +74,7 @@ npm install gulp-postcss --save-dev
68
74
  Use [postcss-font-family-system-ui] in your Gulpfile:
69
75
 
70
76
  ```js
77
+ import gulp from "gulp";
71
78
  import postcss from "gulp-postcss";
72
79
  import postcssSystemUiFont from "postcss-font-family-system-ui";
73
80
 
@@ -84,26 +91,28 @@ gulp.task("css", () =>
84
91
  Add [Grunt PostCSS] to your build tool:
85
92
 
86
93
  ```bash
87
- npm install grunt-postcss --save-dev
94
+ npm install @lodder/grunt-postcss --save-dev
88
95
  ```
89
96
 
90
97
  Use [postcss-font-family-system-ui] in your Gruntfile:
91
98
 
92
99
  ```js
93
- import postcssSystemUiFont from "postcss-font-family-system-ui";
94
-
95
- grunt.loadNpmTasks("grunt-postcss");
96
-
97
- grunt.initConfig({
98
- postcss: {
99
- options: {
100
- use: [postcssSystemUiFont(/* options */)],
101
- },
102
- dist: {
103
- src: "*.css",
100
+ const postcssSystemUiFont = require("postcss-font-family-system-ui");
101
+
102
+ module.exports = (grunt) => {
103
+ grunt.loadNpmTasks("@lodder/grunt-postcss");
104
+
105
+ grunt.initConfig({
106
+ postcss: {
107
+ options: {
108
+ processors: [postcssSystemUiFont(/* options */)],
109
+ },
110
+ dist: {
111
+ src: "*.css",
112
+ },
104
113
  },
105
- },
106
- });
114
+ });
115
+ };
107
116
  ```
108
117
 
109
118
  ## Options
@@ -111,7 +120,8 @@ grunt.initConfig({
111
120
  ### family
112
121
 
113
122
  The `family` option defines the fallback families used to polyfill `system-ui`.
114
- It accepts an array or a comma-separated string.
123
+ It accepts a comma-separated string or an array of them. An empty or falsy
124
+ value is ignored, as if the option was not set.
115
125
 
116
126
  ```js
117
127
  import postcssSystemUiFont from "postcss-font-family-system-ui";
@@ -123,11 +133,11 @@ postcssSystemUiFont({
123
133
 
124
134
  ### browsers
125
135
 
126
- Note: if `family` option is specified, the `browsers` option will not be activated.
136
+ Note: if a non-empty `family` option is specified, the `browsers` option and the browserslist configuration are not used.
127
137
 
128
- The `browsers` option determines the supported browsers, which is used to tune levels of polyfill based on the [support matrix] of `system-ui` at caniuse.
138
+ The `browsers` option determines the supported browsers, which is used to tune levels of polyfill based on the [support matrix] of `system-ui` at caniuse. Browsers that support `system-ui` only on macOS, through `-apple-system` (Firefox 43–91) or `BlinkMacSystemFont` (Chrome 53–55), also get the generic fallbacks for other platforms.
129
139
 
130
- [postcss-font-family-system-ui] supports any standard [browserslist] configuration, which includes a `.browserslistrc` file, a `browserslist` key in `package.json`, or `browserslist` environment variables.
140
+ [postcss-font-family-system-ui] supports any standard [browserslist] configuration, which includes a `.browserslistrc` file, a `browserslist` key in `package.json`, or `browserslist` environment variables. The configuration is looked up from the location of each CSS file (the PostCSS `from` option), or from the current working directory when `from` is not set. As with Autoprefixer, CSS from a package with its own `browserslist` configuration, for example in `node_modules`, uses that package's configuration; set the `browsers` option to use the same browsers for every file. An invalid configuration is reported when the first `system-ui` declaration that uses it is processed.
131
141
 
132
142
  The `browsers` option should only be used when a standard browserslist configuration is not available.
133
143
 
@@ -142,7 +152,9 @@ If not valid browserslist configuration is specified, the [default browserslist
142
152
  ### preserve
143
153
 
144
154
  The `preserve: boolean` option controls whether `system-ui` should be preserved in the transformed CSS output.
145
- It accepts only boolean and the default is `true`
155
+ It accepts only boolean and the default is `true`. With the `family` option,
156
+ `preserve: false` removes `system-ui` from that list, unless it is the only
157
+ name, and `preserve: true` uses the list as given.
146
158
 
147
159
  ```js
148
160
  postcssSystemUiFont({
@@ -159,15 +171,15 @@ postcssSystemUiFont({
159
171
  });
160
172
  ```
161
173
 
162
- [css-img]: https://csstools.github.io/cssdb/badge/system-ui-font-family.svg
163
- [css-url]: https://csstools.github.io/cssdb/#system-ui-font-family
174
+ [css-img]: https://cssdb.org/images/badges/system-ui-font-family.svg
175
+ [css-url]: https://cssdb.org/#system-ui-font-family
164
176
  [npm-img]: https://img.shields.io/npm/v/postcss-font-family-system-ui.svg
165
177
  [npm-url]: https://www.npmjs.com/package/postcss-font-family-system-ui
166
178
  [git-img]: https://img.shields.io/badge/support-chat-blue.svg
167
179
  [git-url]: https://gitter.im/postcss/postcss
168
180
  [css fonts module level 4]: https://drafts.csswg.org/css-fonts-4/#system-ui-def
169
181
  [gulp postcss]: https://github.com/postcss/gulp-postcss
170
- [grunt postcss]: https://github.com/nDmitry/grunt-postcss
182
+ [grunt postcss]: https://github.com/C-Lodder/grunt-postcss
171
183
  [postcss-font-family-system-ui]: https://github.com/JLHwung/postcss-font-family-system-ui
172
184
  [postcss]: https://github.com/postcss/postcss
173
185
  [browserslist]: https://github.com/browserslist/browserslist#readme