respect-user-color-scheme: take prefers-color-schema instead of author default

gordonwoodhull · gordonwoodhull · commit 9c0016deaa35 · 2025-04-02T15:55:28.000-04:00
fixes #1470 respect-user-color-schema defaults to false use static tests for user default color scheme since we do not support dynamic change of prefers-color-scheme yet
diff --git a/news/changelog-1.7.md b/news/changelog-1.7.md
@@ -61,6 +61,7 @@ All changes included in 1.7:
 - ([#12277](https://github.com/quarto-dev/quarto-cli/pull/12277)): Provide light and dark plot and table renderings with `renderings: [light,dark]`
 - ([#11860](https://github.com/quarto-dev/quarto-cli/issues/11860)): ES6 modules that import other local JS modules in documents with `embed-resources: true` are now correctly embedded.
 - ([#1325](https://github.com/quarto-dev/quarto-cli/issues/1325)): Dark Mode pages should not flash light on reload. (Nor should Light Mode pages flash dark.)
+- ([#1470](https://github.com/quarto-dev/quarto-cli/issues/1470)): `respect-user-color-scheme` enables checking the media query `prefers-color-scheme` for user preference. This is only on page load, not dynamically. Author preference still influences stylesheet order and therefore NoJS experience. Defaults to `false`, leaving to author preference.
 - ([#12307](https://github.com/quarto-dev/quarto-cli/issues/12307)): Tabsets using `tabby.js` in non-boostrap html (`theme: pandoc`, `theme: none` or `minimal: true`) now correctly render reactive content when `server: shiny` is used.
 - ([#12356](https://github.com/quarto-dev/quarto-cli/issues/12356)): Remove duplicate id in HTML document when using `#lst-` prefix label for using Quarto crossref.
 
diff --git a/src/config/constants.ts b/src/config/constants.ts
@@ -142,6 +142,7 @@ export const kHtmlTableProcessing = "html-table-processing";
 export const kHtmlPreTagProcessing = "html-pre-tag-processing";
 export const kCssPropertyProcessing = "css-property-processing";
 export const kBrandMode = "brand-mode";
+export const kRespectUserColorScheme = "respect-user-color-scheme";
 export const kUseRsvgConvert = "use-rsvg-convert";
 export const kValidateYaml = "validate-yaml";
 
diff --git a/src/format/html/format-html.ts b/src/format/html/format-html.ts
@@ -24,14 +24,15 @@ import {
   kFigResponsive,
   kFilterParams,
   kHeaderIncludes,
-  kIncludeBeforeBody,
   kIncludeAfterBody,
+  kIncludeBeforeBody,
   kIncludeInHeader,
   kLinkExternalFilter,
   kLinkExternalIcon,
   kLinkExternalNewwindow,
   kNotebookLinks,
   kNotebookViewStyle,
+  kRespectUserColorScheme,
   kTheme,
 } from "../../config/constants.ts";
 
@@ -343,6 +344,8 @@ export async function htmlFormatExtras(
   options.codeTools = formatHasCodeTools(format);
   options.darkMode = formatDarkMode(format);
   options.darkModeDefault = darkModeDefault(format.metadata);
+  options.respectUserColorScheme = format.metadata[kRespectUserColorScheme] ||
+    false;
   options.linkExternalIcon = format.render[kLinkExternalIcon];
   options.linkExternalNewwindow = format.render[kLinkExternalNewwindow];
   options.linkExternalFilter = format.render[kLinkExternalFilter];
@@ -502,7 +505,7 @@ export async function htmlFormatExtras(
       renderEjs(
         formatResourcePath("html", join("hypothesis", "hypothesis.ejs")),
         { hypothesis: options.hypothesis },
-      )
+      ),
     );
     includeInHeader.push(hypothesisHeader);
   }
@@ -516,10 +519,12 @@ export async function htmlFormatExtras(
     !!options[option]
   );
   if (quartoHtmlRequired) {
-    for(const {dest, ejsfile} of [
-      {dest: includeBeforeBody, ejsfile: "quarto-html-before-body.ejs"},
-      {dest: includeAfterBody, ejsfile: "quarto-html-after-body.ejs"}
-    ]) {
+    for (
+      const { dest, ejsfile } of [
+        { dest: includeBeforeBody, ejsfile: "quarto-html-before-body.ejs" },
+        { dest: includeAfterBody, ejsfile: "quarto-html-after-body.ejs" },
+      ]
+    ) {
       const quartoHtmlScript = temp.createFile();
       const renderedHtml = renderEjs(
         formatResourcePath("html", join("templates", ejsfile)),
diff --git a/src/resources/formats/html/templates/quarto-html-before-body.ejs b/src/resources/formats/html/templates/quarto-html-before-body.ejs
@@ -128,7 +128,12 @@
         return localAlternateSentinel;
       }
     }
-    const darkModeDefault = <%= darkModeDefault %>;
+    <% if (respectUserColorScheme) { %>
+      const darkModeDefault = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    <% } else { %>
+      const darkModeDefault = <%= darkModeDefault %>;
+    <% } %>
+      
     let localAlternateSentinel = darkModeDefault ? 'alternate' : 'default';
 
     // Dark / light mode switch
diff --git a/src/resources/schema/document-options.yml b/src/resources/schema/document-options.yml
@@ -84,6 +84,18 @@
     formats: [$html-doc]
   description: Enables smooth scrolling within the page.
 
+- name: respect-user-color-scheme
+  schema: boolean
+  default: false
+  tags:
+    formats: [$html-doc]
+  description:
+    short: "Whether the `prefers-color-scheme` media query controls dark mode."
+    long: |
+      Whether to use the `prefers-color-scheme` media query to determine whether to show
+      the user a dark or light page. Otherwise the author preference (order of `light`
+      and `dark` in `theme` or `brand`) determines what is shown to the user at first visit.
+
 - name: html-math-method
   tags:
     formats: [$html-doc, $epub-all, gfm]
diff --git a/tests/docs/playwright/html/dark-brand/project-dark/_quarto.yml b/tests/docs/playwright/html/dark-brand/project-dark/_quarto.yml
diff --git a/tests/docs/playwright/html/dark-brand/project-dark/blue-background.yml b/tests/docs/playwright/html/dark-brand/project-dark/blue-background.yml
diff --git a/tests/docs/playwright/html/dark-brand/project-dark/brand-false.qmd b/tests/docs/playwright/html/dark-brand/project-dark/brand-false.qmd
diff --git a/tests/docs/playwright/html/dark-brand/project-dark/brand-under-theme.qmd b/tests/docs/playwright/html/dark-brand/project-dark/brand-under-theme.qmd
diff --git a/tests/docs/playwright/html/dark-brand/project-dark/red-background.yml b/tests/docs/playwright/html/dark-brand/project-dark/red-background.yml
diff --git a/tests/docs/playwright/html/dark-brand/project-dark/simple-respect-color-scheme.qmd b/tests/docs/playwright/html/dark-brand/project-dark/simple-respect-color-scheme.qmd
@@ -0,0 +1,55 @@
+---
+title: "dark brand - ggplot"
+format:
+  html:
+    respect-user-color-scheme: true
+execute:
+  echo: false
+  warning: false
+---
+
+```{r}
+#| echo: false
+#| warning: false
+library(ggplot2)
+
+ggplot_theme <- function(bgcolor, fgcolor) {
+  theme_minimal(base_size = 11) %+%
+    theme(
+      panel.border = element_blank(),
+      panel.grid.major.y = element_blank(),
+      panel.grid.minor.y = element_blank(),
+      panel.grid.major.x = element_blank(),
+      panel.grid.minor.x = element_blank(),
+      text = element_text(colour = fgcolor),
+      axis.text = element_text(colour = fgcolor),
+      rect = element_rect(colour = bgcolor, fill = bgcolor),
+      plot.background = element_rect(fill = bgcolor, colour = NA),
+      axis.line = element_line(colour = fgcolor),
+      axis.ticks = element_line(colour = fgcolor)
+    )
+}
+
+brand_ggplot <- function(brand_yml) {
+  brand <- yaml::yaml.load_file(brand_yml)
+  ggplot_theme(brand$color$background, brand$color$foreground)
+}
+
+blue_theme <- brand_ggplot("blue-background.yml")
+red_theme <- brand_ggplot("red-background.yml")
+
+colour_scale <- scale_colour_manual(values = c("darkorange", "purple", "cyan4"))
+```
+
+
+```{r}
+#| renderings: [light, dark]
+ggplot(mtcars, aes(mpg, wt)) +
+  geom_point(aes(colour = factor(cyl))) +
+  blue_theme +
+  colour_scale
+ggplot(mtcars, aes(mpg, wt)) +
+  geom_point(aes(colour = factor(cyl))) +
+  red_theme +
+  colour_scale
+```
diff --git a/tests/docs/playwright/html/dark-brand/project-dark/simple.qmd b/tests/docs/playwright/html/dark-brand/project-dark/simple.qmd
diff --git a/tests/docs/playwright/html/dark-brand/project-light/_quarto.yml b/tests/docs/playwright/html/dark-brand/project-light/_quarto.yml
@@ -0,0 +1,5 @@
+project:
+  type: default
+brand:
+  light: blue-background.yml
+  dark: red-background.yml
diff --git a/tests/docs/playwright/html/dark-brand/project-light/blue-background.yml b/tests/docs/playwright/html/dark-brand/project-light/blue-background.yml
@@ -0,0 +1,3 @@
+color:
+  background: "#ccddff"
+  foreground: "#336644"
diff --git a/tests/docs/playwright/html/dark-brand/project-light/red-background.yml b/tests/docs/playwright/html/dark-brand/project-light/red-background.yml
@@ -0,0 +1,3 @@
+color:
+  background: "#42070b"
+  foreground: "#cceedd"
diff --git a/tests/docs/playwright/html/dark-brand/project-light/simple-respect-color-scheme.qmd b/tests/docs/playwright/html/dark-brand/project-light/simple-respect-color-scheme.qmd
@@ -0,0 +1,55 @@
+---
+title: "dark brand - ggplot"
+format:
+  html:
+    respect-user-color-scheme: true
+execute:
+  echo: false
+  warning: false
+---
+
+```{r}
+#| echo: false
+#| warning: false
+library(ggplot2)
+
+ggplot_theme <- function(bgcolor, fgcolor) {
+  theme_minimal(base_size = 11) %+%
+    theme(
+      panel.border = element_blank(),
+      panel.grid.major.y = element_blank(),
+      panel.grid.minor.y = element_blank(),
+      panel.grid.major.x = element_blank(),
+      panel.grid.minor.x = element_blank(),
+      text = element_text(colour = fgcolor),
+      axis.text = element_text(colour = fgcolor),
+      rect = element_rect(colour = bgcolor, fill = bgcolor),
+      plot.background = element_rect(fill = bgcolor, colour = NA),
+      axis.line = element_line(colour = fgcolor),
+      axis.ticks = element_line(colour = fgcolor)
+    )
+}
+
+brand_ggplot <- function(brand_yml) {
+  brand <- yaml::yaml.load_file(brand_yml)
+  ggplot_theme(brand$color$background, brand$color$foreground)
+}
+
+blue_theme <- brand_ggplot("blue-background.yml")
+red_theme <- brand_ggplot("red-background.yml")
+
+colour_scale <- scale_colour_manual(values = c("darkorange", "purple", "cyan4"))
+```
+
+
+```{r}
+#| renderings: [light, dark]
+ggplot(mtcars, aes(mpg, wt)) +
+  geom_point(aes(colour = factor(cyl))) +
+  blue_theme +
+  colour_scale
+ggplot(mtcars, aes(mpg, wt)) +
+  geom_point(aes(colour = factor(cyl))) +
+  red_theme +
+  colour_scale
+```
diff --git a/tests/docs/playwright/html/dark-brand/project-light/simple.qmd b/tests/docs/playwright/html/dark-brand/project-light/simple.qmd
@@ -0,0 +1,52 @@
+---
+title: "dark brand - ggplot"
+execute:
+  echo: false
+  warning: false
+---
+
+```{r}
+#| echo: false
+#| warning: false
+library(ggplot2)
+
+ggplot_theme <- function(bgcolor, fgcolor) {
+  theme_minimal(base_size = 11) %+%
+    theme(
+      panel.border = element_blank(),
+      panel.grid.major.y = element_blank(),
+      panel.grid.minor.y = element_blank(),
+      panel.grid.major.x = element_blank(),
+      panel.grid.minor.x = element_blank(),
+      text = element_text(colour = fgcolor),
+      axis.text = element_text(colour = fgcolor),
+      rect = element_rect(colour = bgcolor, fill = bgcolor),
+      plot.background = element_rect(fill = bgcolor, colour = NA),
+      axis.line = element_line(colour = fgcolor),
+      axis.ticks = element_line(colour = fgcolor)
+    )
+}
+
+brand_ggplot <- function(brand_yml) {
+  brand <- yaml::yaml.load_file(brand_yml)
+  ggplot_theme(brand$color$background, brand$color$foreground)
+}
+
+blue_theme <- brand_ggplot("blue-background.yml")
+red_theme <- brand_ggplot("red-background.yml")
+
+colour_scale <- scale_colour_manual(values = c("darkorange", "purple", "cyan4"))
+```
+
+
+```{r}
+#| renderings: [light, dark]
+ggplot(mtcars, aes(mpg, wt)) +
+  geom_point(aes(colour = factor(cyl))) +
+  blue_theme +
+  colour_scale
+ggplot(mtcars, aes(mpg, wt)) +
+  geom_point(aes(colour = factor(cyl))) +
+  red_theme +
+  colour_scale
+```
diff --git a/tests/integration/playwright/tests/html-dark-mode-defaultdark.spec.ts b/tests/integration/playwright/tests/html-dark-mode-defaultdark.spec.ts
@@ -0,0 +1,51 @@
+import { test, expect } from '@playwright/test';
+
+async function check_backgrounds(page, class_, primary, secondary) {
+  const locatr = await page.locator('body').first();
+  await expect(locatr).toHaveClass(`fullcontent ${class_}`);
+  await expect(locatr).toHaveCSS('background-color', primary);
+  await page.locator("a.quarto-color-scheme-toggle").click();
+  const locatr2 = await page.locator('body').first();
+  await expect(locatr2).toHaveCSS('background-color', secondary);
+}
+
+test.use({
+  colorScheme: 'dark'
+});
+
+const blue = 'rgb(204, 221, 255)';
+const red = 'rgb(66, 7, 11)';
+
+
+// brands used in these documents have background colors
+
+test('Dark and light brand after user themes', async ({ page }) => {
+  // brand overrides theme background color
+  await page.goto('./html/dark-brand/brand-after-theme.html');
+  await check_backgrounds(page, 'quarto-dark', red, blue);
+});
+
+// project tests
+
+test('Project specifies light and dark brands', async ({ page }) => {
+  await page.goto('./html/dark-brand/project-light/simple.html');
+  await check_backgrounds(page, 'quarto-light', blue, red);
+});
+
+
+test('Project specifies dark and light brands', async ({ page }) => {
+  await page.goto('./html/dark-brand/project-dark/simple.html');
+  await check_backgrounds(page, 'quarto-dark', red, blue);
+});
+
+
+test('Project specifies light and dark brands and respect-user-color-scheme', async ({ page }) => {
+  await page.goto('./html/dark-brand/project-light/simple-respect-color-scheme.html');
+  await check_backgrounds(page, 'quarto-dark', red, blue);
+});
+
+
+test('Project specifies dark and light brands and respect-user-color-scheme', async ({ page }) => {
+  await page.goto('./html/dark-brand/project-dark/simple-respect-color-scheme.html');
+  await check_backgrounds(page, 'quarto-dark', red, blue);
+});
diff --git a/tests/integration/playwright/tests/html-dark-mode-defaultlight.spec.ts b/tests/integration/playwright/tests/html-dark-mode-defaultlight.spec.ts
@@ -0,0 +1,49 @@
+import { test, expect } from '@playwright/test';
+
+async function check_backgrounds(page, class_, primary, secondary) {
+  const locatr = await page.locator('body').first();
+  await expect(locatr).toHaveClass(`fullcontent ${class_}`);
+  await expect(locatr).toHaveCSS('background-color', primary);
+  await page.locator("a.quarto-color-scheme-toggle").click();
+  const locatr2 = await page.locator('body').first();
+  await expect(locatr2).toHaveCSS('background-color', secondary);
+}
+
+test.use({
+  colorScheme: 'light'
+});
+
+const blue = 'rgb(204, 221, 255)';
+const red = 'rgb(66, 7, 11)';
+
+// brands used in these documents have background colors
+
+test('Dark and light brand after user themes', async ({ page }) => {
+  // brand overrides theme background color
+  await page.goto('./html/dark-brand/brand-after-theme.html');
+  await check_backgrounds(page, 'quarto-dark', red, blue);
+});
+
+// project tests
+
+test('Project specifies light and dark brands', async ({ page }) => {
+  await page.goto('./html/dark-brand/project-light/simple.html');
+  await check_backgrounds(page, 'quarto-light', blue, red);
+});
+
+
+test('Project specifies dark and light brands', async ({ page }) => {
+  await page.goto('./html/dark-brand/project-dark/simple.html');
+  await check_backgrounds(page, 'quarto-dark', red, blue);
+});
+
+
+test('Project specifies light and dark brands and respect-user-color-scheme', async ({ page }) => {
+  await page.goto('./html/dark-brand/project-light/simple-respect-color-scheme.html');
+  await check_backgrounds(page, 'quarto-light', blue, red);
+});
+
+test('Project specifies dark and light brands and respect-user-color-scheme', async ({ page }) => {
+  await page.goto('./html/dark-brand/project-dark/simple-respect-color-scheme.html');
+  await check_backgrounds(page, 'quarto-light', blue, red);
+});
diff --git a/tests/integration/playwright/tests/html-dark-mode-nojs.spec.ts b/tests/integration/playwright/tests/html-dark-mode-nojs.spec.ts
@@ -25,7 +25,7 @@ test('Light brand default, no JS', async ({ page }) => {
 test('Project dark brand default, no JS', async ({ page }) => {
   // This document use a custom theme file that change the background color of the title banner
   // Same user defined color should be used in both dark and light theme
-  await page.goto('./html/dark-brand/project-light-dark/simple.html');
+  await page.goto('./html/dark-brand/project-dark/simple.html');
   const locatr = await page.locator('body').first();
   await expect(locatr).toHaveClass('fullcontent quarto-dark');
   await expect(locatr).toHaveCSS('background-color', 'rgb(66, 7, 11)');
diff --git a/tests/integration/playwright/tests/html-dark-mode.spec.ts b/tests/integration/playwright/tests/html-dark-mode.spec.ts

Original file line number	Diff line number	Diff line change
`@@ -128,7 +128,12 @@`
`128`	`128`	`return localAlternateSentinel;`
`129`	`129`	`}`
`130`	`130`	`}`
`131`		`- const darkModeDefault = <%= darkModeDefault %>;`
	`131`	`+ <% if (respectUserColorScheme) { %>`
	`132`	`+ const darkModeDefault = window.matchMedia('(prefers-color-scheme: dark)').matches;`
	`133`	`+ <% } else { %>`
	`134`	`+ const darkModeDefault = <%= darkModeDefault %>;`
	`135`	`+ <% } %>`
	`136`	`+`
`132`	`137`	`let localAlternateSentinel = darkModeDefault ? 'alternate' : 'default';`
`133`	`138`
`134`	`139`	`// Dark / light mode switch`