Skip to content

Commit fa8f8f1

Browse files
authored
postcss-custom-media : update docs (#692)
* psotcss-custom-media : improve docs * wording * wording
1 parent 6fab587 commit fa8f8f1

File tree

9 files changed

+165
-0
lines changed

9 files changed

+165
-0
lines changed

plugins/postcss-custom-media/.tape.mjs

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,15 @@ postcssTape(plugin)({
2424
preserve: true
2525
}
2626
},
27+
'examples/true': {
28+
message: 'minimal example with "true"',
29+
},
30+
'examples/false': {
31+
message: 'minimal example with "false"',
32+
},
33+
'examples/complex': {
34+
message: 'minimal example complex queries',
35+
},
2736
'nesting': {
2837
message: 'works when nested'
2938
},

plugins/postcss-custom-media/README.md

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,81 @@
1818
}
1919
```
2020

21+
## `true` and `false`
22+
23+
With `@custom-media` you can use the constants `true` and `false`.
24+
These are especially handy when debugging.
25+
26+
If you are unsure how your page is affected when a certain media query matches or not you can use these, to quickly toggle the results.
27+
This plugin downgrades these queries to something that works in all browsers.
28+
29+
Quickly check the result as if the query matches:
30+
31+
```pcss
32+
@custom-media --small-viewport true;
33+
34+
@media (--small-viewport) {
35+
/* styles for small viewport */
36+
}
37+
38+
/* becomes */
39+
40+
@media (max-color:2147477350) {
41+
/* styles for small viewport */
42+
}
43+
```
44+
45+
Quickly check the result as if the query does not match:
46+
47+
```pcss
48+
@custom-media --small-viewport false;
49+
50+
@media (--small-viewport) {
51+
/* styles for small viewport */
52+
}
53+
54+
/* becomes */
55+
56+
@media (color:2147477350) {
57+
/* styles for small viewport */
58+
}
59+
```
60+
61+
## logical evaluation of complex media queries
62+
63+
It is impossible to accurately and correctly resolve complex `@custom-media` queries
64+
as these depend on the browser the queries will eventually run in.
65+
66+
_Some of these queries will have only one possible outcome but we have to account for all possible queries in this plugin._
67+
68+
⚠️ When handling complex media queries you will see that your CSS is doubled for each level of complexity.<br>
69+
GZIP works great to de-dupe this but having a lot of complex media queries will have a performance impact.
70+
71+
An example of a very complex (and artificial) use-case :
72+
73+
```pcss
74+
75+
@custom-media --a-complex-query tty and (min-width: 300px);
76+
77+
@media not screen and ((not (--a-complex-query)) or (color)) {
78+
/* Your CSS */
79+
}
80+
81+
/* becomes */
82+
83+
84+
@media tty and (min-width: 300px) {
85+
@media not screen and ((not (max-color:2147477350)) or (color)) {
86+
/* Your CSS */
87+
}
88+
}
89+
@media not tty and (min-width: 300px) {
90+
@media not screen and ((not (color:2147477350)) or (color)) {
91+
/* Your CSS */
92+
}
93+
}
94+
```
95+
2196
## Usage
2297

2398
Add [PostCSS Custom Media] to your project:

plugins/postcss-custom-media/docs/README.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,54 @@
2626
<example.expect.css>
2727
```
2828

29+
## `true` and `false`
30+
31+
With `@custom-media` you can use the constants `true` and `false`.
32+
These are especially handy when debugging.
33+
34+
If you are unsure how your page is affected when a certain media query matches or not you can use these, to quickly toggle the results.
35+
This plugin downgrades these queries to something that works in all browsers.
36+
37+
Quickly check the result as if the query matches:
38+
39+
```pcss
40+
<true.css>
41+
42+
/* becomes */
43+
44+
<true.expect.css>
45+
```
46+
47+
Quickly check the result as if the query does not match:
48+
49+
```pcss
50+
<false.css>
51+
52+
/* becomes */
53+
54+
<false.expect.css>
55+
```
56+
57+
## logical evaluation of complex media queries
58+
59+
It is impossible to accurately and correctly resolve complex `@custom-media` queries
60+
as these depend on the browser the queries will eventually run in.
61+
62+
_Some of these queries will have only one possible outcome but we have to account for all possible queries in this plugin._
63+
64+
⚠️ When handling complex media queries you will see that your CSS is doubled for each level of complexity.<br>
65+
GZIP works great to de-dupe this but having a lot of complex media queries will have a performance impact.
66+
67+
An example of a very complex (and artificial) use-case :
68+
69+
```pcss
70+
<complex.css>
71+
72+
/* becomes */
73+
74+
<complex.expect.css>
75+
```
76+
2977
<usage>
3078

3179
<envSupport>
Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
2+
@custom-media --a-complex-query tty and (min-width: 300px);
3+
4+
@media not screen and ((not (--a-complex-query)) or (color)) {
5+
/* Your CSS */
6+
}
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
2+
@media tty and (min-width: 300px) {
3+
@media not screen and ((not (max-color:2147477350)) or (color)) {
4+
/* Your CSS */
5+
}
6+
}
7+
@media not tty and (min-width: 300px) {
8+
@media not screen and ((not (color:2147477350)) or (color)) {
9+
/* Your CSS */
10+
}
11+
}
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
@custom-media --small-viewport false;
2+
3+
@media (--small-viewport) {
4+
/* styles for small viewport */
5+
}
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
@media (color:2147477350) {
2+
/* styles for small viewport */
3+
}
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
@custom-media --small-viewport true;
2+
3+
@media (--small-viewport) {
4+
/* styles for small viewport */
5+
}
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
@media (max-color:2147477350) {
2+
/* styles for small viewport */
3+
}

0 commit comments

Comments
 (0)