diff --git a/plugins/postcss-custom-media/.tape.mjs b/plugins/postcss-custom-media/.tape.mjs
index 7dac6d271..3c91c6623 100644
--- a/plugins/postcss-custom-media/.tape.mjs
+++ b/plugins/postcss-custom-media/.tape.mjs
@@ -24,6 +24,15 @@ postcssTape(plugin)({
preserve: true
}
},
+ 'examples/true': {
+ message: 'minimal example with "true"',
+ },
+ 'examples/false': {
+ message: 'minimal example with "false"',
+ },
+ 'examples/complex': {
+ message: 'minimal example complex queries',
+ },
'nesting': {
message: 'works when nested'
},
diff --git a/plugins/postcss-custom-media/README.md b/plugins/postcss-custom-media/README.md
index e847e2fba..8fc2e1bc4 100644
--- a/plugins/postcss-custom-media/README.md
+++ b/plugins/postcss-custom-media/README.md
@@ -18,6 +18,81 @@
}
```
+## `true` and `false`
+
+With `@custom-media` you can use the constants `true` and `false`.
+These are especially handy when debugging.
+
+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.
+This plugin downgrades these queries to something that works in all browsers.
+
+Quickly check the result as if the query matches:
+
+```pcss
+@custom-media --small-viewport true;
+
+@media (--small-viewport) {
+ /* styles for small viewport */
+}
+
+/* becomes */
+
+@media (max-color:2147477350) {
+ /* styles for small viewport */
+}
+```
+
+Quickly check the result as if the query does not match:
+
+```pcss
+@custom-media --small-viewport false;
+
+@media (--small-viewport) {
+ /* styles for small viewport */
+}
+
+/* becomes */
+
+@media (color:2147477350) {
+ /* styles for small viewport */
+}
+```
+
+## logical evaluation of complex media queries
+
+It is impossible to accurately and correctly resolve complex `@custom-media` queries
+as these depend on the browser the queries will eventually run in.
+
+_Some of these queries will have only one possible outcome but we have to account for all possible queries in this plugin._
+
+⚠️ When handling complex media queries you will see that your CSS is doubled for each level of complexity.
+GZIP works great to de-dupe this but having a lot of complex media queries will have a performance impact.
+
+An example of a very complex (and artificial) use-case :
+
+```pcss
+
+@custom-media --a-complex-query tty and (min-width: 300px);
+
+@media not screen and ((not (--a-complex-query)) or (color)) {
+ /* Your CSS */
+}
+
+/* becomes */
+
+
+@media tty and (min-width: 300px) {
+@media not screen and ((not (max-color:2147477350)) or (color)) {
+ /* Your CSS */
+}
+}
+@media not tty and (min-width: 300px) {
+@media not screen and ((not (color:2147477350)) or (color)) {
+ /* Your CSS */
+}
+}
+```
+
## Usage
Add [PostCSS Custom Media] to your project:
diff --git a/plugins/postcss-custom-media/docs/README.md b/plugins/postcss-custom-media/docs/README.md
index 6d3d8dc76..2c7cb995f 100644
--- a/plugins/postcss-custom-media/docs/README.md
+++ b/plugins/postcss-custom-media/docs/README.md
@@ -26,6 +26,54 @@
```
+## `true` and `false`
+
+With `@custom-media` you can use the constants `true` and `false`.
+These are especially handy when debugging.
+
+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.
+This plugin downgrades these queries to something that works in all browsers.
+
+Quickly check the result as if the query matches:
+
+```pcss
+
+
+/* becomes */
+
+
+```
+
+Quickly check the result as if the query does not match:
+
+```pcss
+
+
+/* becomes */
+
+
+```
+
+## logical evaluation of complex media queries
+
+It is impossible to accurately and correctly resolve complex `@custom-media` queries
+as these depend on the browser the queries will eventually run in.
+
+_Some of these queries will have only one possible outcome but we have to account for all possible queries in this plugin._
+
+⚠️ When handling complex media queries you will see that your CSS is doubled for each level of complexity.
+GZIP works great to de-dupe this but having a lot of complex media queries will have a performance impact.
+
+An example of a very complex (and artificial) use-case :
+
+```pcss
+
+
+/* becomes */
+
+
+```
+
diff --git a/plugins/postcss-custom-media/test/examples/complex.css b/plugins/postcss-custom-media/test/examples/complex.css
new file mode 100644
index 000000000..5099b0f0e
--- /dev/null
+++ b/plugins/postcss-custom-media/test/examples/complex.css
@@ -0,0 +1,6 @@
+
+@custom-media --a-complex-query tty and (min-width: 300px);
+
+@media not screen and ((not (--a-complex-query)) or (color)) {
+ /* Your CSS */
+}
diff --git a/plugins/postcss-custom-media/test/examples/complex.expect.css b/plugins/postcss-custom-media/test/examples/complex.expect.css
new file mode 100644
index 000000000..f5563f551
--- /dev/null
+++ b/plugins/postcss-custom-media/test/examples/complex.expect.css
@@ -0,0 +1,11 @@
+
+@media tty and (min-width: 300px) {
+@media not screen and ((not (max-color:2147477350)) or (color)) {
+ /* Your CSS */
+}
+}
+@media not tty and (min-width: 300px) {
+@media not screen and ((not (color:2147477350)) or (color)) {
+ /* Your CSS */
+}
+}
diff --git a/plugins/postcss-custom-media/test/examples/false.css b/plugins/postcss-custom-media/test/examples/false.css
new file mode 100644
index 000000000..9957197fa
--- /dev/null
+++ b/plugins/postcss-custom-media/test/examples/false.css
@@ -0,0 +1,5 @@
+@custom-media --small-viewport false;
+
+@media (--small-viewport) {
+ /* styles for small viewport */
+}
diff --git a/plugins/postcss-custom-media/test/examples/false.expect.css b/plugins/postcss-custom-media/test/examples/false.expect.css
new file mode 100644
index 000000000..81462295b
--- /dev/null
+++ b/plugins/postcss-custom-media/test/examples/false.expect.css
@@ -0,0 +1,3 @@
+@media (color:2147477350) {
+ /* styles for small viewport */
+}
diff --git a/plugins/postcss-custom-media/test/examples/true.css b/plugins/postcss-custom-media/test/examples/true.css
new file mode 100644
index 000000000..825dff4d7
--- /dev/null
+++ b/plugins/postcss-custom-media/test/examples/true.css
@@ -0,0 +1,5 @@
+@custom-media --small-viewport true;
+
+@media (--small-viewport) {
+ /* styles for small viewport */
+}
diff --git a/plugins/postcss-custom-media/test/examples/true.expect.css b/plugins/postcss-custom-media/test/examples/true.expect.css
new file mode 100644
index 000000000..1fb198d97
--- /dev/null
+++ b/plugins/postcss-custom-media/test/examples/true.expect.css
@@ -0,0 +1,3 @@
+@media (max-color:2147477350) {
+ /* styles for small viewport */
+}