19449 prefers color scheme (#20886)

* docs(CSS): prefers-color-scheme for embedded content * docs(CSS): minor fix for coloer-scheme * chore(build) replace Prettier config * docs(CSS): add example of embedded SVG for prefers-color-scheme * docs(CSS): add xrefs for color-scheme & prefers-color-scheme * docs(CSS): improve wording for prefers-color-scheme docs * typo fix * docs(CSS) add details on secure animated mode for SVGs * Update files/en-us/web/css/@media/prefers-color-scheme/index.md Co-authored-by: Estelle Weyl <[email protected]> * Update files/en-us/web/css/@media/prefers-color-scheme/index.md Co-authored-by: Estelle Weyl <[email protected]> * chore(docs) Clarify embedded SVG details, links to supporting docs * Apply suggestions from code review Co-authored-by: Estelle Weyl <[email protected]> * docs(CSS): Link to more appropriate inline SVG example, minor copy fix * grammar Co-authored-by: Estelle Weyl <[email protected]>
mdn · Oct 13, 2022 · b85094c · b85094c
1 parent f7b0b24
commit b85094c
Show file tree

Hide file tree

Showing 3 changed files with 61 additions and 8 deletions.
diff --git a/.prettierignore b/.prettierignore
@@ -2,4 +2,3 @@ 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
@@ -14,9 +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 **`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.
 
-The user might indicate this preference through an operating system setting (e.g. light or dark mode) or a user agent setting.
+## Embedded elements
+
+For SVG and iframes, `prefers-color-scheme` lets you set a CSS style for the SVG 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., `<img src="circle.svg" alt="circle" />`) as opposed to [inlined in HTML](/en-US/docs/Web/SVG/Tutorial/SVG_In_HTML_Introduction#basic_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 [cross-origin](/en-US/docs/Web/Security/Same-origin_policy#cross-origin_network_access) `<svg>` and `<iframe>` elements. Cross-origin elements are elements retrieved from a different host than the page that is 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
 
@@ -27,9 +35,10 @@ The user might indicate this preference through an operating system setting (e.g
 
 ## 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
 <div class="day">Day (initial)</div>
@@ -42,7 +51,7 @@ The elements below have an initial color theme. They can be further themed accor
 <div class="night dark-scheme">Night (changes in dark scheme)</div>
 ```
 
-### CSS
+The following CSS is used to style the elements above:
 
 ```css
 .day {
@@ -86,9 +95,53 @@ 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](/en-US/docs/Web/CSS/color-scheme) inherited from a parent element.
+A script is used to set the source of the `<img>` elements and their `alt` attributes. This would normally be done in HTML as `<img src="circle.svg" alt="circle" />`.
+
+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; the `@media` query allows setting 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 `<div>`.
+
+```html
+<div>
+  <img />
+</div>
+
+<div style="color-scheme: light">
+  <img />
+</div>
+<div style="color-scheme: dark">
+  <img />
+</div>
+
+<!-- Embed an SVG for all <img> elements -->
+<script>
+  for (let img of document.querySelectorAll("img")) {
+    img.alt = "circle";
+    img.src =
+      "data:image/svg+xml;base64," +
+      btoa(`
+      <svg width="32" height="32" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
+        <style>
+          :root { color: blue }
+          @media (prefers-color-scheme: dark) {
+            :root { color: purple }
+          }
+        </style>
+        <circle fill="currentColor" cx="16" cy="16" r="16"/>
+      </svg>
+    `);
+  }
+</script>
+```
 
-{{EmbedLiveSample("Examples")}}
+{{EmbedLiveSample("Color_scheme_inheritance")}}
 
 ## Specifications
 

diff --git a/files/en-us/web/css/color-scheme/index.md b/files/en-us/web/css/color-scheme/index.md
@@ -83,6 +83,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")}}
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2,4 +2,3 @@ build/

		# Ignore markdown files till full pass is made on each folder
		*.md