Media queries module

files/en-us/web/css/@media/index.md

@@ -123,6 +123,8 @@ Media feature expressions test for their presence or value, and are entirely opt
     Added in Media Queries Level 5.
 - {{cssxref("@media/resolution", "resolution")}}
   - : Pixel density of the output device.
+- {{cssxref("@media/scan", "scan")}}
+  - : Whether display output is progressive or interlaced.
 - {{cssxref("@media/scripting", "scripting")}}
   - : Detects whether scripting (i.e. JavaScript) is available.
     Added in Media Queries Level 5.
@@ -246,6 +248,7 @@ For more examples, please see [Using media queries](/en-US/docs/Web/CSS/CSS_medi
 
 ## See also
 
+- [CSS media queries](/en-US/docs/Web/CSS/CSS_media_queries) module
 - [Using media queries](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries)
 - In JavaScript, `@media` can be accessed via the CSS object model interface {{domxref("CSSMediaRule")}}.
 - [Extended Mozilla media features](/en-US/docs/Web/CSS/Mozilla_Extensions#media_features)

files/en-us/web/css/css_media_queries/index.md

@@ -3,63 +3,136 @@ title: CSS media queries
 slug: Web/CSS/CSS_media_queries
 page-type: css-module
 spec-urls:
+  - https://drafts.csswg.org/mediaqueries-3/
   - https://drafts.csswg.org/mediaqueries/
-  - https://drafts.csswg.org/css-conditional/
+  - https://drafts.csswg.org/mediaqueries-5/
 ---
 
 {{CSSRef}}
 
-**CSS media queries** are a key component of [responsive design](/en-US/docs/Learn/CSS/CSS_layout/Responsive_Design) that allow you to apply CSS styles depending on the presence or value of device characteristics.
+**CSS media queries** module enables testing and querying viewport values or user-agent features, to conditionally apply CSS styles based on the current user environment. Media queries are used in the CSS `@media` rule and in other contexts and languages, such as HTML and JavaScript.
 
-It's common to apply a media query based on the {{Glossary("viewport")}} size so that layout choices can be made for devices with different screen sizes.
-For example, you may have a smaller font size for devices with small screens, increase the padding between paragraphs when a page is viewed in portrait mode, or increase the size of buttons on touchscreens.
+Media queries are a key component of [responsive design](/en-US/docs/Learn/CSS/CSS_layout/Responsive_Design). They enable applying CSS styles depending on the presence or value of device characteristics. It's common to apply a media query based on the {{Glossary("viewport")}} size so that layout choices can be made for devices with different screen sizes. For example, you may increase the font sizes when printing a page, the padding between paragraphs when a page is viewed in portrait mode, or the size of buttons on touchscreens.
 
-![A laptop and a mobile device with different viewport sizes that can be queried using media queries where we can see the content being laid out differently.](media-queries.svg)
-
-In [CSS](/en-US/docs/Web/CSS), use the {{cssxref("@media")}} [at-rule](/en-US/docs/Web/CSS/At-rule) to conditionally apply part of a style sheet based on the result of a media query.
-To conditionally apply an entire style sheet, use {{cssxref("@import")}}.
+In [CSS](/en-US/docs/Web/CSS), use the {{cssxref("@media")}} [at-rule](/en-US/docs/Web/CSS/At-rule) to conditionally apply part of a style sheet based on the result of a media query. To conditionally apply an entire style sheet, use {{cssxref("@import")}}.
 
 When designing reusable HTML components, you may also use [container queries](/en-US/docs/Web/CSS/CSS_container_queries), which allow you to apply styles based on the size of a containing element rather than the viewport or other device characteristics.
 
-### Media queries in HTML
-
-In [HTML](/en-US/docs/Web/HTML), media queries can be applied to various elements:
-
-- In the {{HTMLElement("link")}} element's [`media`](/en-US/docs/Web/HTML/Element/link#media) attribute, they define the media to which a linked resource (typically CSS) should be applied.
-- In the {{HTMLElement("source")}} element's [`media`](/en-US/docs/Web/HTML/Element/source#media) attribute, they define the media to which that source should be applied. (This is only valid inside {{HTMLElement("picture")}} elements.)
-- In the {{HTMLElement("style")}} element's [`media`](/en-US/docs/Web/HTML/Element/style#media) attribute, they define the media to which the style should be applied.
-
-### Media queries in JavaScript
-
-In [JavaScript](/en-US/docs/Web/JavaScript), you can use the {{domxref("Window.matchMedia()")}} method to test the window against a media query.
-You can also use {{domxref("MediaQueryList.addListener()")}} to be notified whenever the state of a query changes.
-With this functionality, your site or app can respond to changes in the device configuration, orientation, or state.
-
-You can learn more about programmatically using media queries in [Testing media queries](/en-US/docs/Web/CSS/CSS_media_queries/Testing_media_queries).
-
 ## Reference
 
 ### At-rules
 
 - {{cssxref("@import")}}
 - {{cssxref("@media")}}
 
+### Descriptors
+
+- {{cssxref("@media/any-hover", "any-hover")}}
+- {{cssxref("@media/any-pointer", "any-pointer")}}
+- {{cssxref("@media/aspect-ratio", "aspect-ratio")}}
+- {{cssxref("@media/color", "color")}}
+- {{cssxref("@media/color-gamut", "color-gamut")}}
+- {{cssxref("@media/color-index", "color-index")}}
+- {{cssxref("@media/device-aspect-ratio", "device-aspect-ratio")}}
+- {{cssxref("@media/device-height", "device-height")}}
+- {{cssxref("@media/device-width", "device-width")}}
+- {{cssxref("@media/display-mode", "display-mode")}}
+- {{cssxref("@media/dynamic-range", "dynamic-range")}}
+- {{cssxref("@media/forced-colors", "forced-colors")}}
+- {{cssxref("@media/grid", "grid")}}
+- {{cssxref("@media/height", "height")}}
+- {{cssxref("@media/hover", "hover")}}
+- {{cssxref("@media/inverted-colors", "inverted-colors")}}
+- {{cssxref("@media/monochrome", "monochrome")}}
+- {{cssxref("@media/orientation", "orientation")}}
+- {{cssxref("@media/overflow-block", "overflow-block")}}
+- {{cssxref("@media/overflow-inline", "overflow-inline")}}
+- {{cssxref("@media/pointer", "pointer")}}
+- {{cssxref("@media/prefers-color-scheme", "prefers-color-scheme")}}
+- {{cssxref("@media/prefers-contrast", "prefers-contrast")}}
+- {{cssxref("@media/prefers-reduced-data", "prefers-reduced-data")}}
+- {{cssxref("@media/prefers-reduced-motion", "prefers-reduced-motion")}}
+- {{cssxref("@media/prefers-reduced-transparency", "prefers-reduced-transparency")}}
+- {{cssxref("@media/resolution", "resolution")}}
+- {{cssxref("@media/scan", "scan")}}
+- {{cssxref("@media/scripting", "scripting")}}
+- {{cssxref("@media/update", "update")}}
+- {{cssxref("@media/video-dynamic-range", "video-dynamic-range")}}
+- {{cssxref("@media/width", "width")}}
+
+> **Note:** CSS media queries level 5 introduces five `@media` descriptors that have not been implemented: {{cssxref("@media/environment-blending", "environment-blending")}}, {{cssxref("@media/horizontal-viewport-segments", "horizontal-viewport-segments")}}, {{cssxref("@media/nav-controls", "nav-controls")}}, {{cssxref("@media/vertical-viewport-segments", "vertical-viewport-segments")}}, and {{cssxref("@media/video-color-gamut", "video-color-gamut")}}
+
+> **Note:** CSS media queries level 4 deprecated three `@media` descriptors: {{cssxref("@media/device-aspect-ratio", "device-aspect-ratio")}}, {{cssxref("@media/device-height", "device-height")}}, and {{cssxref("@media/device-width", "device-width")}}.
+
+### Data types and operators
+
+- [`<media-types>`](/en-US/docs/Web/CSS/@media#media_types)
+- [`<media-features>`](/en-US/docs/Web/CSS/@media#media_features)
+- [`<resolution>`](/en-US/docs/Web/CSS/resolution)
+- [Logical operators](/en-US/docs/Web/CSS/@media#logical_operators)
+
+### Glossary terms
+
+- [media](/en-US/docs/Glossary/Media/CSS)
+- [media query](/en-US/docs/Glossary/Media_query)
+
 ## Guides
 
 - [Using media queries](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries)
-  - : Introduces media queries, their syntax, and the operators and media features which are used to construct media query expressions.
-- [Testing media queries programmatically](/en-US/docs/Web/CSS/CSS_media_queries/Testing_media_queries)
+
+  - : Introduces media queries, their syntax, and the operators and media features used to construct media query expressions.
+
+- [Beginner's guide to media queries](/en-US/docs/Learn/CSS/CSS_layout/Media_queries)
+
+  - : Introduction to media queries and approaches for using them to create responsive designs.
+
+- [Testing media queries](/en-US/docs/Web/CSS/CSS_media_queries/Testing_media_queries)
+
   - : Describes how to use media queries in your JavaScript code to determine the state of a device, and to set up listeners that notify your code when the results of media queries change (such as when the user rotates the screen or resizes the browser).
+
 - [Using media queries for accessibility](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries_for_accessibility)
-  - : Learn how Media Queries can help users understand your website better.
+
+  - : Learn how media queries can help users understand your website better.
+
 - [Printing](/en-US/docs/Web/CSS/CSS_media_queries/Printing)
+
   - : Tips and techniques for helping improve web content printer output.
 
+- [Learn: responsive images](/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images)
+
+  - : Learn how to use media queries with `sizes` to implement responsive image solutions on websites.
+
+## Related concepts
+
+- [CSS containment](/en-US/docs/Web/CSS/CSS_containment) module
+  - {{cssxref("@container")}} at-rule
+  - [Using container queries](/en-US/docs/Web/CSS/CSS_container_queries)
+- [CSS conditional rules](/en-US/docs/Web/CSS/CSS_container_queries) module
+  - {{cssxref("@supports")}} at-rule
+  - [Using feature queries](/en-US/docs/Web/CSS/CSS_conditional_rules/Using_feature_queries)
+- [CSS paged media](/en-US/docs/Web/CSS/CSS_paged_media) module
+  - {{cssxref("@page")}} at-rule
+- [CSS object model](/en-US/docs/Web/API/CSS_Object_Model) module
+  - {{DOMxRef("MediaQueryList")}} interface
+    - {{DOMxRef("MediaQueryList.matches", "matches")}} property
+    - {{DOMxRef("MediaQueryList.media", "media")}} property
+    - {{DOMxRef("MediaQueryList.change_event", "change")}} event
+  - {{DOMxRef("MediaList")}} interface
+    - {{DOMxRef("MediaList.mediaText", "mediaText")}} property
+  - {{DOMxRef("MediaQueryListEvent")}} object
+- HTML
+  - `sizes` attribute for [`<img>`](/en-US/docs/Web/HTML/Element/img#sizes), [`<link>`](/en-US/docs/Web/HTML/Element/link#sizes), and [`<source>`](/en-US/docs/Web/HTML/Element/source#sizes) for {{HTMLElement("picture")}}
+  - `media` attribute for [`<link>`](/en-US/docs/Web/HTML/Element/link#media), [`<source>`](/en-US/docs/Web/HTML/Element/source#media), and [`<style>`](/en-US/docs/Web/HTML/Element/style#media) [HTML](/en-US/docs/Web/HTML)
+  - [Viewport `<meta>` tag](/en-US/docs/Web/HTML/Viewport_meta_tag)
+- SVG [`media`](/en-US/docs/Web/SVG/Attribute/media) attribute
+
 ## Specifications
 
 {{Specifications}}
 
 ## See also
 
+- [Using the `srcset` and `sizes` attributes](/en-US/docs/Web/HTML/Element/img#using_the_srcset_and_sizes_attributes)
 - [Container queries](/en-US/docs/Web/CSS/CSS_container_queries)
+- [CSS paged media](/en-US/docs/Web/CSS/CSS_paged_media)
 - Use {{cssxref("@supports")}} to apply styles that depend on browser support for various CSS technologies.

files/en-us/web/css/css_media_queries/printing/index.md

@@ -21,11 +21,11 @@ Add the following to your {{HTMLElement("head")}} tag.
 <link href="/path/to/print.css" media="print" rel="stylesheet" />
 ```
 
-## Using media queries and @page to improve layout
+## Using media queries and @page to control printed content
 
-You can use the CSS {{cssxref("@media")}} at-rule to set a different appearance for your webpage when it is printed on paper and when it is displayed on the screen. The `print` option sets the styles that will be used when the content is printed.
+You can use the CSS {{cssxref("@media")}} at-rule to set different styles for your webpage when it is printed on paper or as a PDF versus when it is displayed on the screen. The `print` [media type](/en-US/docs/Web/CSS/@media#media_type) sets the styles for printed media; these styles will only be used for printed content.
 
-Add this at the end of your stylesheet. Note that specificity and precedence rules still apply:
+Add this at the end of your stylesheet. Note that [specificity](/en-US/docs/Web/CSS/Specificity) and precedence rules still apply:
 
 ```css
 @media print {
@@ -42,7 +42,7 @@ You can also use the {{cssxref("@page")}} at-rule to modify different aspects of
 
 ## Detecting print requests
 
-Browsers send {{domxref("Window/beforeprint_event", "beforeprint")}} and {{domxref("Window/afterprint_event", "afterprint")}} events to let content determine when printing may have occurred. You can use this to adjust the user interface presented during printing (such as by displaying or hiding user interface elements during the print process).
+Browsers send {{domxref("Window/beforeprint_event", "beforeprint")}} and {{domxref("Window/afterprint_event", "afterprint")}} events determine when printing may have occurred. You can use this to adjust the user interface presented during printing (such as by displaying or hiding user interface elements during the print process).
 
 ## Examples
 

files/en-us/web/css/css_media_queries/testing_media_queries/index.md

@@ -7,21 +7,21 @@ browser-compat: api.MediaQueryList
 
 {{CSSRef}}
 
-The {{Glossary("DOM")}} provides features that can test the results of a [media query](/en-US/docs/Web/CSS/CSS_media_queries) programmatically, via the {{domxref("MediaQueryList")}} interface and its methods and properties. Once you've created a `MediaQueryList` object, you can check the result of the query or receive notifications when the result changes.
+The {{Glossary("DOM")}} provides features that can test the results of a {{Glossary("media query")}} programmatically, via the {{domxref("MediaQueryList")}} interface and its methods and properties. Once you've created a `MediaQueryList` object, you can check the result of the [query](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries) or receive notifications when the result changes.
 
 ## Creating a media query list
 
-Before you can evaluate the results of a media query, you need to create the `MediaQueryList` object representing the query. To do this, use the {{domxref("window.matchMedia")}} method.
+Before you can evaluate the results of a media query, you need to create the {{domxref("MediaQueryList")}} object representing the query. To do this, use the {{domxref("window.matchMedia")}} method.
 
-For example, to set up a query list that determines if the device is in landscape or portrait orientation:
+For example, to set up a query list that determines if the device is in landscape or portrait [orientation](/en-US/docs/Web/CSS/@media/orientation):
 
 ```js
 const mediaQueryList = window.matchMedia("(orientation: portrait)");
 ```
 
 ## Checking the result of a query
 
-Once you've created your media query list, you can check the result of the query by looking at the value of its `matches` property:
+Once you've created your media query list, you can check the result of the query by looking at the value of its [`matches`](/en-US/docs/Web/API/MediaQueryList/matches) property:
 
 ```js
 if (mediaQueryList.matches) {
@@ -33,7 +33,7 @@ if (mediaQueryList.matches) {
 
 ## Receiving query notifications
 
-If you need to be aware of changes to the evaluated result of the query on an ongoing basis, it's more efficient to register a [listener](/en-US/docs/Web/API/EventTarget/addEventListener) than to poll the query's result. To do this, call the `addEventListener()` method on the {{domxref("MediaQueryList")}} object, with a callback function to invoke when the media query status changes (e.g., the media query test goes from `true` to `false`):
+If you need to be aware of changes to the evaluated result of the query on an ongoing basis, it's more efficient to register a [listener](/en-US/docs/Web/API/EventTarget/addEventListener) than to poll the query's result. To do this, call the {{domxref("EventTarget.addEventListener", "addEventListener()")}} method on the {{domxref("MediaQueryList")}} object, with a callback function to invoke when the media query status changes (e.g., the media query test goes from `true` to `false`):
 
 ```js
 // Create the query list.
@@ -51,7 +51,7 @@ handleOrientationChange(mediaQueryList);
 mediaQueryList.addEventListener("change", handleOrientationChange);
 ```
 
-This code creates the orientation-testing media query list, then adds an event listener to it. After defining the listener, we also call the listener directly. This makes our listener perform adjustments based on the current device orientation; otherwise, our code might assume the device is in portrait mode at startup, even if it's actually in landscape mode.
+This code creates the orientation-testing media query list and adds an event listener to it. After defining the listener, we also call the listener directly. This makes our listener perform adjustments based on the current device orientation; otherwise, our code might assume the device is in portrait mode at startup, even if it's actually in landscape mode.
 
 The `handleOrientationChange()` function would look at the result of the query and handle whatever we need to do on an orientation change:
 
@@ -82,6 +82,8 @@ mediaQueryList.removeEventListener("change", handleOrientationChange);
 ## See also
 
 - [Media queries](/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries)
+- [CSS media queries](/en-US/docs/Web/CSS/CSS_media_queries) module
+- [CSS object model](/en-US/docs/Web/API/CSS_Object_Model) module
 - {{domxref("window.matchMedia()")}}
 - {{domxref("MediaQueryList")}}
 - {{domxref("MediaQueryListEvent")}}