From be04bdb03aeef5f10c404610569166670a618357 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Wed, 14 Sep 2022 16:20:02 +0200 Subject: [PATCH 01/14] docs(CSS): prefers-color-scheme for embedded content --- .prettierignore | 4 ---- files/en-us/web/css/@media/prefers-color-scheme/index.md | 3 +++ 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/.prettierignore b/.prettierignore index d013b7c6c7bd2ed..567609b1234a9b8 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,5 +1 @@ build/ - -# Ignore markdown files till full pass is made on each folder -*.md - diff --git a/files/en-us/web/css/@media/prefers-color-scheme/index.md b/files/en-us/web/css/@media/prefers-color-scheme/index.md index 7f3384ad7b12295..9ff14ab91de508b 100644 --- a/files/en-us/web/css/@media/prefers-color-scheme/index.md +++ b/files/en-us/web/css/@media/prefers-color-scheme/index.md @@ -17,6 +17,9 @@ The **`prefers-color-scheme`** [CSS](/en-US/docs/Web/CSS) [media feature](/en-US The user might indicate this preference through an operating system setting (e.g. light or dark mode) or a user agent setting. +To avoid cases where OS and browser preferences are conflicting, `prefers-color-scheme` passes the color scheme of the embedding element in the embedding document to the embedded content when acceptable from security standpoint. +This applies to both same and cross-origin SVG and iframe elements. + ## Syntax - `light` From d850ccdf768becc300902b23aaff2ad47922d50a Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Thu, 15 Sep 2022 15:02:59 +0200 Subject: [PATCH 02/14] docs(CSS): minor fix for coloer-scheme --- files/en-us/web/css/@media/prefers-color-scheme/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/css/@media/prefers-color-scheme/index.md b/files/en-us/web/css/@media/prefers-color-scheme/index.md index 9ff14ab91de508b..cbdb4c986b4dc42 100644 --- a/files/en-us/web/css/@media/prefers-color-scheme/index.md +++ b/files/en-us/web/css/@media/prefers-color-scheme/index.md @@ -17,7 +17,7 @@ The **`prefers-color-scheme`** [CSS](/en-US/docs/Web/CSS) [media feature](/en-US The user might indicate this preference through an operating system setting (e.g. light or dark mode) or a user agent setting. -To avoid cases where OS and browser preferences are conflicting, `prefers-color-scheme` passes the color scheme of the embedding element in the embedding document to the embedded content when acceptable from security standpoint. +To avoid cases where OS and browser preferences are conflicting, `prefers-color-scheme` passes the `color-scheme` of the embedding element in the embedding document to the embedded content when acceptable from security standpoint. This applies to both same and cross-origin SVG and iframe elements. ## Syntax From 78471856aaed3875d1c46c27b19854cb72e13c22 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Mon, 19 Sep 2022 10:19:02 +0200 Subject: [PATCH 03/14] chore(build) replace Prettier config --- .prettierignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.prettierignore b/.prettierignore index 567609b1234a9b8..9359c3f3d3c18c9 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1 +1,4 @@ build/ + +# Ignore markdown files till full pass is made on each folder +*.md From 8121b78124aab65db5bdc57fe05094610841309e Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Mon, 19 Sep 2022 11:45:29 +0200 Subject: [PATCH 04/14] docs(CSS): add example of embedded SVG for prefers-color-scheme --- .../css/@media/prefers-color-scheme/index.md | 56 ++++++++++++++++--- 1 file changed, 48 insertions(+), 8 deletions(-) diff --git a/files/en-us/web/css/@media/prefers-color-scheme/index.md b/files/en-us/web/css/@media/prefers-color-scheme/index.md index cbdb4c986b4dc42..c319f614f2d2302 100644 --- a/files/en-us/web/css/@media/prefers-color-scheme/index.md +++ b/files/en-us/web/css/@media/prefers-color-scheme/index.md @@ -14,11 +14,10 @@ browser-compat: css.at-rules.media.prefers-color-scheme {{QuickLinksWithSubpages("/en-US/docs/Web/CSS/@media/")}} The **`prefers-color-scheme`** [CSS](/en-US/docs/Web/CSS) [media feature](/en-US/docs/Web/CSS/Media_Queries/Using_media_queries#media_features) is used to detect if the user has requested a light or dark color theme. - The user might indicate this preference through an operating system setting (e.g. light or dark mode) or a user agent setting. -To avoid cases where OS and browser preferences are conflicting, `prefers-color-scheme` passes the `color-scheme` of the embedding element in the embedding document to the embedded content when acceptable from security standpoint. -This applies to both same and cross-origin SVG and iframe elements. +For embedded elements, `prefers-color-scheme` passes the `color-scheme` of the embedding element to the embedded content when acceptable from security standpoint. +This applies to both same and cross-origin SVG and iframe elements and prevents cases where OS and browser preferences for color schemes are conflicting. ## Syntax @@ -29,9 +28,10 @@ This applies to both same and cross-origin SVG and iframe elements. ## Examples -The elements below have an initial color theme. They can be further themed according to the user's color scheme preference. +### Detecting a dark theme -### HTML +The elements below have an initial color theme. +They can be further themed according to the user's color scheme preference. ```html
Day (initial)
@@ -44,7 +44,7 @@ The elements below have an initial color theme. They can be further themed accor
Night (changes in dark scheme)
``` -### CSS +The following CSS is used to style the elements above: ```css .day { @@ -88,9 +88,49 @@ The elements below have an initial color theme. They can be further themed accor } ``` -### Result +{{EmbedLiveSample("Detecting_a_dark_theme")}} + +### Color scheme inheritance + +The following example shows how to use `prefers-color-scheme` with the `color-scheme` property can inherited from the embedding element. +A script is used to specify the source of the image elements, this would normally be done in HTML as `` or similar. + +The first circle inherits the `color-scheme` from the browser or OS and can be toggled using this page's theme switcher. +The second and third circle inherit the `color-scheme` from the embedding element and so the `@media` query allows to specify styles of the embedded content based on the parent element's `color-scheme`. + +```html +
+ +
+ +
+ +
+
+ +
+ + + +``` -{{EmbedLiveSample("Examples")}} +{{EmbedLiveSample("Color_scheme_inheritance")}} ## Specifications From eef81638b12a156113781638c70e05466bdb7bf5 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Mon, 19 Sep 2022 14:03:19 +0200 Subject: [PATCH 05/14] docs(CSS): add xrefs for color-scheme & prefers-color-scheme --- files/en-us/web/css/@media/prefers-color-scheme/index.md | 1 + files/en-us/web/css/color-scheme/index.md | 1 + 2 files changed, 2 insertions(+) diff --git a/files/en-us/web/css/@media/prefers-color-scheme/index.md b/files/en-us/web/css/@media/prefers-color-scheme/index.md index c319f614f2d2302..28252638056c389 100644 --- a/files/en-us/web/css/@media/prefers-color-scheme/index.md +++ b/files/en-us/web/css/@media/prefers-color-scheme/index.md @@ -142,6 +142,7 @@ The second and third circle inherit the `color-scheme` from the embedding elemen ## See also +- {{cssxref("color-scheme")}} CSS property - [Simulate prefers-color-scheme in Firefox](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/examine_and_edit_css/index.html#view-media-rules-for-prefers-color-scheme) (Firefox Page Inspector > Examine and edit CSS) - [Video tutorial: Coding a Dark Mode for your Website](https://www.youtube.com/watch?v=jmepqJ5UbuM) - [Redesigning your product and website for dark mode](https://stuffandnonsense.co.uk/blog/redesigning-your-product-and-website-for-dark-mode) diff --git a/files/en-us/web/css/color-scheme/index.md b/files/en-us/web/css/color-scheme/index.md index 6080b17623a26ee..4061302b45fc157 100644 --- a/files/en-us/web/css/color-scheme/index.md +++ b/files/en-us/web/css/color-scheme/index.md @@ -82,6 +82,7 @@ To opt the entire page into the user's color scheme preferences declare `color-s ## See also +- [`prefers-color-scheme`](/en-US/docs/Web/CSS/@media/prefers-color-scheme) media query to detect user preferences for color schemes. - [Applying color to HTML elements using CSS](/en-US/docs/Web/CSS/CSS_Colors/Applying_color) - Other color-related properties: {{cssxref("color")}}, {{cssxref("background-color")}}, {{cssxref("border-color")}}, {{cssxref("outline-color")}}, {{cssxref("text-decoration-color")}}, {{cssxref("text-emphasis-color")}}, {{cssxref("text-shadow")}}, {{cssxref("caret-color")}}, and {{cssxref("column-rule-color")}} - {{cssxref("background-image")}} From f14d789ac7cf76cfb78ad1dfcc45c4d30a6bf074 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Tue, 20 Sep 2022 10:49:59 +0200 Subject: [PATCH 06/14] docs(CSS): improve wording for prefers-color-scheme docs --- files/en-us/web/css/@media/prefers-color-scheme/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/files/en-us/web/css/@media/prefers-color-scheme/index.md b/files/en-us/web/css/@media/prefers-color-scheme/index.md index 28252638056c389..f86894fb0457491 100644 --- a/files/en-us/web/css/@media/prefers-color-scheme/index.md +++ b/files/en-us/web/css/@media/prefers-color-scheme/index.md @@ -16,7 +16,7 @@ browser-compat: css.at-rules.media.prefers-color-scheme The **`prefers-color-scheme`** [CSS](/en-US/docs/Web/CSS) [media feature](/en-US/docs/Web/CSS/Media_Queries/Using_media_queries#media_features) is used to detect if the user has requested a light or dark color theme. The user might indicate this preference through an operating system setting (e.g. light or dark mode) or a user agent setting. -For embedded elements, `prefers-color-scheme` passes the `color-scheme` of the embedding element to the embedded content when acceptable from security standpoint. +Using `prefers-color-scheme` in embedded elements allows you to style a component based on the `color-scheme` of the parent element when acceptable from security standpoint. This applies to both same and cross-origin SVG and iframe elements and prevents cases where OS and browser preferences for color schemes are conflicting. ## Syntax @@ -95,6 +95,7 @@ The following CSS is used to style the elements above: The following example shows how to use `prefers-color-scheme` with the `color-scheme` property can inherited from the embedding element. A script is used to specify the source of the image elements, this would normally be done in HTML as `` or similar. +On browsers that support this feature (such as Firefox), you should see three circles, with one drawn in a different color. The first circle inherits the `color-scheme` from the browser or OS and can be toggled using this page's theme switcher. The second and third circle inherit the `color-scheme` from the embedding element and so the `@media` query allows to specify styles of the embedded content based on the parent element's `color-scheme`. From 156834056f96bfb0b86acc01f9c939d836c35c13 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Tue, 20 Sep 2022 13:52:14 +0200 Subject: [PATCH 07/14] typo fix --- files/en-us/web/css/@media/prefers-color-scheme/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/files/en-us/web/css/@media/prefers-color-scheme/index.md b/files/en-us/web/css/@media/prefers-color-scheme/index.md index f86894fb0457491..9c3ced3fd0dcb9f 100644 --- a/files/en-us/web/css/@media/prefers-color-scheme/index.md +++ b/files/en-us/web/css/@media/prefers-color-scheme/index.md @@ -92,8 +92,8 @@ The following CSS is used to style the elements above: ### Color scheme inheritance -The following example shows how to use `prefers-color-scheme` with the `color-scheme` property can inherited from the embedding element. -A script is used to specify the source of the image elements, this would normally be done in HTML as `` or similar. +The following example shows how to use `prefers-color-scheme` with the `color-scheme` property inherited from a parent element. +A script is used to specify the source of the image elements, this would normally be done in HTML as ``. On browsers that support this feature (such as Firefox), you should see three circles, with one drawn in a different color. The first circle inherits the `color-scheme` from the browser or OS and can be toggled using this page's theme switcher. From ceb767c8835838a2b08c896797f18765baf327b7 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Thu, 6 Oct 2022 11:21:41 +0200 Subject: [PATCH 08/14] docs(CSS) add details on secure animated mode for SVGs --- files/en-us/web/css/@media/prefers-color-scheme/index.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/files/en-us/web/css/@media/prefers-color-scheme/index.md b/files/en-us/web/css/@media/prefers-color-scheme/index.md index 90315e87cc52ae1..9aec4ffb45587e4 100644 --- a/files/en-us/web/css/@media/prefers-color-scheme/index.md +++ b/files/en-us/web/css/@media/prefers-color-scheme/index.md @@ -17,9 +17,12 @@ browser-compat: css.at-rules.media.prefers-color-scheme The **`prefers-color-scheme`** [CSS](/en-US/docs/Web/CSS) [media feature](/en-US/docs/Web/CSS/Media_Queries/Using_media_queries#media_features) is used to detect if the user has requested a light or dark color theme. The user might indicate this preference through an operating system setting (e.g. light or dark mode) or a user agent setting. -Using `prefers-color-scheme` in embedded elements allows you to style a component based on the `color-scheme` of the parent element when acceptable from security standpoint. +Using `prefers-color-scheme` in embedded elements allows you to style a component based on the `color-scheme` of the parent element. This applies to both same and cross-origin SVG and iframe elements and prevents cases where OS and browser preferences for color schemes are conflicting. +SVG elements must be referenced in [secure animated mode](https://svgwg.org/specs/integration/#secure-animated-mode) to use `prefers-color-scheme`. +SVGs are in secure animated mode when referenced by `` elements, used to define font glyphs, and loaded as resources for `mask`, `pattern`, gradient, or other resource elements. + ## Syntax - `light` From 3959d1e322fb8e80e645f960c4d6bfd2703f744a Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Fri, 7 Oct 2022 10:31:33 +0200 Subject: [PATCH 09/14] Update files/en-us/web/css/@media/prefers-color-scheme/index.md Co-authored-by: Estelle Weyl --- files/en-us/web/css/@media/prefers-color-scheme/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/css/@media/prefers-color-scheme/index.md b/files/en-us/web/css/@media/prefers-color-scheme/index.md index 9aec4ffb45587e4..2d679c9efdcb6cd 100644 --- a/files/en-us/web/css/@media/prefers-color-scheme/index.md +++ b/files/en-us/web/css/@media/prefers-color-scheme/index.md @@ -97,7 +97,7 @@ The following CSS is used to style the elements above: ### Color scheme inheritance The following example shows how to use `prefers-color-scheme` with the `color-scheme` property inherited from a parent element. -A script is used to specify the source of the image elements, this would normally be done in HTML as ``. +A script is used to specify the source of the image elements, this would normally be done in HTML as `circle`. On browsers that support this feature (such as Firefox), you should see three circles, with one drawn in a different color. The first circle inherits the `color-scheme` from the browser or OS and can be toggled using this page's theme switcher. From 42b6f84759d6267555c8c5d268e931ebf4ef0da2 Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Fri, 7 Oct 2022 10:40:39 +0200 Subject: [PATCH 10/14] Update files/en-us/web/css/@media/prefers-color-scheme/index.md Co-authored-by: Estelle Weyl --- files/en-us/web/css/@media/prefers-color-scheme/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/files/en-us/web/css/@media/prefers-color-scheme/index.md b/files/en-us/web/css/@media/prefers-color-scheme/index.md index 2d679c9efdcb6cd..0dcc45c530ea4af 100644 --- a/files/en-us/web/css/@media/prefers-color-scheme/index.md +++ b/files/en-us/web/css/@media/prefers-color-scheme/index.md @@ -101,7 +101,7 @@ A script is used to specify the source of the image elements, this would normall On browsers that support this feature (such as Firefox), you should see three circles, with one drawn in a different color. The first circle inherits the `color-scheme` from the browser or OS and can be toggled using this page's theme switcher. -The second and third circle inherit the `color-scheme` from the embedding element and so the `@media` query allows to specify styles of the embedded content based on the parent element's `color-scheme`. +The second and third circles inherit the `color-scheme` from the embedding element and so the `@media` query allows to specify styles of the embedded content based on the parent element's `color-scheme`. ```html
From 43872c32272a20d66faea43fc15128c1c2ae5eab Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Mon, 10 Oct 2022 14:43:59 +0200 Subject: [PATCH 11/14] chore(docs) Clarify embedded SVG details, links to supporting docs --- .../css/@media/prefers-color-scheme/index.md | 25 +++++++++++-------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/files/en-us/web/css/@media/prefers-color-scheme/index.md b/files/en-us/web/css/@media/prefers-color-scheme/index.md index 0dcc45c530ea4af..22c8edba00a1adb 100644 --- a/files/en-us/web/css/@media/prefers-color-scheme/index.md +++ b/files/en-us/web/css/@media/prefers-color-scheme/index.md @@ -14,14 +14,17 @@ browser-compat: css.at-rules.media.prefers-color-scheme {{QuickLinksWithSubpages("/en-US/docs/Web/CSS/@media/")}} -The **`prefers-color-scheme`** [CSS](/en-US/docs/Web/CSS) [media feature](/en-US/docs/Web/CSS/Media_Queries/Using_media_queries#media_features) is used to detect if the user has requested a light or dark color theme. -The user might indicate this preference through an operating system setting (e.g. light or dark mode) or a user agent setting. +The **`prefers-color-scheme`** [CSS](/en-US/docs/Web/CSS) [media feature](/en-US/docs/Web/CSS/Media_Queries/Using_media_queries#targeting_media_features) is used to detect if a user has requested light or dark color themes. +A user indicates their preference through an operating system setting (e.g. light or dark mode) or a user agent setting. -Using `prefers-color-scheme` in embedded elements allows you to style a component based on the `color-scheme` of the parent element. -This applies to both same and cross-origin SVG and iframe elements and prevents cases where OS and browser preferences for color schemes are conflicting. +## Embedded elements -SVG elements must be referenced in [secure animated mode](https://svgwg.org/specs/integration/#secure-animated-mode) to use `prefers-color-scheme`. -SVGs are in secure animated mode when referenced by `` elements, used to define font glyphs, and loaded as resources for `mask`, `pattern`, gradient, or other resource elements. +For SVG and iframes, `prefers-color-scheme` lets you to set a CSS style for the SVGs or iframe based on the [`color-scheme`](/en-US/docs/Web/CSS/color-scheme) of parent element in the web page. +SVGs must be used embedded (i.e., ``) as opposed to [inlined in HTML](/en-US/docs/Web/SVG/Tutorial/Getting_Started#a_simple_example). +An example of using `prefers-color-scheme` in SVGs can be found in in the [Color scheme inheritance](#color_scheme_inheritance) section. + +Using `prefers-color-scheme` is allowed in SVG and iframe elements used [cross-origin](/en-US/docs/Web/Security/Same-origin_policy#cross-origin_network_access) from a different host than the page that's referencing them. +To learn more about SVGs, see the [SVG documentation](/en-US/docs/Web/SVG) and for more information about iframes, see the [iframe documentation](/en-US/docs/Web/HTML/Element/iframe). ## Syntax @@ -96,12 +99,14 @@ The following CSS is used to style the elements above: ### Color scheme inheritance -The following example shows how to use `prefers-color-scheme` with the `color-scheme` property inherited from a parent element. -A script is used to specify the source of the image elements, this would normally be done in HTML as `circle`. +The following example shows how to use `prefers-color-scheme` with the [`color-scheme` property](/en-US/docs/Web/CSS/color-scheme) inherited from a parent element. +A script is used to set the source of the `` elements, this would normally be done in HTML as ``. On browsers that support this feature (such as Firefox), you should see three circles, with one drawn in a different color. -The first circle inherits the `color-scheme` from the browser or OS and can be toggled using this page's theme switcher. -The second and third circles inherit the `color-scheme` from the embedding element and so the `@media` query allows to specify styles of the embedded content based on the parent element's `color-scheme`. +The first circle inherits the `color-scheme` from the OS and can be toggled using the system OS's theme switcher. + +The second and third circles inherit the `color-scheme` from the embedding element and so the `@media` query allows to set styles of the SVG content based on the parent element's `color-scheme`. +In this case, the parent element with a `color-scheme` CSS property is a `
`. ```html
From c8d5b520ae600f4a1fed71b9a9b301e8ea351c4b Mon Sep 17 00:00:00 2001 From: Brian Thomas Smith Date: Thu, 13 Oct 2022 09:53:56 +0200 Subject: [PATCH 12/14] Apply suggestions from code review Co-authored-by: Estelle Weyl --- .../web/css/@media/prefers-color-scheme/index.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/files/en-us/web/css/@media/prefers-color-scheme/index.md b/files/en-us/web/css/@media/prefers-color-scheme/index.md index 22c8edba00a1adb..f1d119649f90b3d 100644 --- a/files/en-us/web/css/@media/prefers-color-scheme/index.md +++ b/files/en-us/web/css/@media/prefers-color-scheme/index.md @@ -19,11 +19,11 @@ A user indicates their preference through an operating system setting (e.g. ligh ## Embedded elements -For SVG and iframes, `prefers-color-scheme` lets you to set a CSS style for the SVGs or iframe based on the [`color-scheme`](/en-US/docs/Web/CSS/color-scheme) of parent element in the web page. -SVGs must be used embedded (i.e., ``) as opposed to [inlined in HTML](/en-US/docs/Web/SVG/Tutorial/Getting_Started#a_simple_example). +For SVG and iframes, `prefers-color-scheme` lets you to set a CSS style for the SVGs or iframe based on the [`color-scheme`](/en-US/docs/Web/CSS/color-scheme) of the parent element in the web page. +SVGs must be used embedded (i.e., `circle`) as opposed to [inlined in HTML](/en-US/docs/Web/SVG/Tutorial/Getting_Started#a_simple_example). An example of using `prefers-color-scheme` in SVGs can be found in in the [Color scheme inheritance](#color_scheme_inheritance) section. -Using `prefers-color-scheme` is allowed in SVG and iframe elements used [cross-origin](/en-US/docs/Web/Security/Same-origin_policy#cross-origin_network_access) from a different host than the page that's referencing them. +Using `prefers-color-scheme` is allowed in [cross-origin](/en-US/docs/Web/Security/Same-origin_policy#cross-origin_network_access) `` and `` elements, this would normally be done in HTML as ``. +A script is used to set the source of the `` elements and their `alt` attributes. This would normally be done in HTML as `circle`. -On browsers that support this feature (such as Firefox), you should see three circles, with one drawn in a different color. +You should see three circles, with one drawn in a different color. The first circle inherits the `color-scheme` from the OS and can be toggled using the system OS's theme switcher. The second and third circles inherit the `color-scheme` from the embedding element and so the `@media` query allows to set styles of the SVG content based on the parent element's `color-scheme`. @@ -123,6 +123,7 @@ In this case, the parent element with a `color-scheme` CSS property is a `
`