fix(html/axe): use literal overlay colors to avoid clobbering brand (#14471)

* fix(html/axe): use literal colors in axe overlay so it doesn't clobber brand (#14468)

The axe report's sass bundle declared `$body-bg`, `$body-color`, and
`$link-color` defaults in its user SassLayer, which precede brand's user
defaults during sass compilation and so clobbered brand colors on the
page. Since the axe report is developer chrome (not document content),
its overlay rules now use literal hex values instead of theme-derived
SCSS variables. Brand and theme colors win on the page; the overlay
stays readable regardless of how the page is themed.

Same treatment applied to the revealjs report slide (force #fff slide
background via data-background-color and #222 text) and the dashboard
report offcanvas (override --bs-offcanvas-bg/-color to axe defaults).

* Update changelog entry to lead with the UI behavior change

* Move axe entry under new ## Accessibility heading

* Use WCAG AA-safe link color in axe overlay (#0a58ca)

* Use WCAG AAA-passing link color in axe overlay (#0747a6)

Author: cwickham

news/changelog-1.10.md

@@ -7,6 +7,10 @@ All changes included in 1.10:
 - ([#14298](https://github.com/quarto-dev/quarto-cli/issues/14298)): Fix `quarto preview` browse URL including output filename (e.g., `hello.html`) for single-file documents, breaking Posit Workbench proxied server access.
 - ([rstudio/rstudio#17333](https://github.com/rstudio/rstudio/issues/17333)): Fix `quarto inspect` on standalone files emitting project metadata that breaks RStudio's publishing wizard.
 
+## Accessibility
+
+- ([#14468](https://github.com/quarto-dev/quarto-cli/issues/14468)): The `axe` accessibility report UI (HTML overlay, revealjs report slide, dashboard offcanvas) now uses its own theme-independent colors instead of inheriting from `brand` or theme. Keeps the report readable regardless of page styling, and stops `axe` from clobbering brand colors set via `_brand.yml`.
+
 ## Formats
 
 ### `pdf`

src/format/html/format-html-axe.ts

@@ -35,26 +35,27 @@ export function axeFormatDependencies(
 ): FormatExtras {
   if (!options) return {};
 
-  // Use reveal-theme for revealjs, bootstrap for other HTML formats.
-  // Note: For revealjs, sass-bundles compile separately from the theme
-  // (which compiles in format-reveal-theme.ts), so the !default values
-  // below are used instead of actual theme colors. This is a known
-  // limitation - see GitHub issue for architectural context.
+  // The axe report is developer chrome, not document content, so its colors
+  // are literals here rather than theme-derived (`$body-bg` etc.). This keeps
+  // the overlay readable regardless of the page's brand or theme — which
+  // matters most when the user is auditing exactly those colors.
   const isRevealjs = isRevealjsOutput(format.pandoc);
   const isDashboard = isHtmlDashboardOutput(format.identifier["base-format"]);
   const sassDependency = isRevealjs ? "reveal-theme" : "bootstrap";
 
-  // Base overlay rules shared by all formats (also serves as fallback for revealjs)
+  // Base overlay rules shared by all formats. For revealjs, the `var(--r-*)`
+  // lookups pick up the slide's actual colors at runtime; the literal
+  // fallbacks apply everywhere else.
   const baseRules = `
 body div.quarto-axe-report {
   position: fixed;
   bottom: 3rem;
   right: 3rem;
   padding: 1rem;
-  border: 1px solid var(--r-main-color, $body-color);
+  border: 1px solid var(--r-main-color, #222);
   z-index: 9999;
-  background-color: var(--r-background-color, $body-bg);
-  color: var(--r-main-color, $body-color);
+  background-color: var(--r-background-color, #fff);
+  color: var(--r-main-color, #222);
   max-height: 50vh;
   overflow-y: auto;
 }
@@ -63,7 +64,7 @@ body div.quarto-axe-report {
 .quarto-axe-violation-selector { padding-left: 1rem; }
 .quarto-axe-violation-target {
   padding: 0.5rem;
-  color: $link-color;
+  color: #0747a6;
   text-decoration: underline;
   cursor: pointer;
 }
@@ -73,21 +74,26 @@ body div.quarto-axe-report {
   border: 2px solid red;
 }`;
 
-  // RevealJS: override overlay styles when report is embedded as a slide
+  // RevealJS: override overlay styles when report is embedded as a slide.
+  // The slide's white background is set by the JS via data-background-color;
+  // here we only need to keep text/link colors readable on white.
   const revealjsRules = isRevealjs
     ? `
 .reveal .slides section.quarto-axe-report-slide {
   text-align: left;
   font-size: 0.55em;
+  color: #222;
   h2 {
     margin-bottom: 0.5em;
     font-size: 1.8em;
+    color: #222;
   }
   div.quarto-axe-report {
     position: static;
     padding: 0;
     border: none;
     background-color: transparent;
+    color: #222;
     max-height: none;
     overflow-y: visible;
     z-index: auto;
@@ -102,15 +108,20 @@ body div.quarto-axe-report {
 }`
     : "";
 
-  // Dashboard: report inside offcanvas sidebar (not fixed overlay)
+  // Dashboard: report inside offcanvas sidebar (not fixed overlay).
+  // Override Bootstrap's themed offcanvas vars so the panel keeps axe's own
+  // colors regardless of brand/theme.
   const dashboardRules = isDashboard
     ? `
 .quarto-dashboard .offcanvas.quarto-axe-offcanvas {
+  --bs-offcanvas-bg: #fff;
+  --bs-offcanvas-color: #222;
   .quarto-axe-report {
     position: static;
     padding: 0;
     border: none;
     background-color: transparent;
+    color: #222;
     max-height: none;
     overflow-y: visible;
     z-index: auto;
@@ -148,11 +159,7 @@ body div.quarto-axe-report {
           dependency: sassDependency,
           user: [{
             uses: "",
-            defaults: `
-$body-color: #222 !default;
-$body-bg: #fff !default;
-$link-color: #2a76dd !default;
-`,
+            defaults: "",
             functions: "",
             mixins: "",
             rules: baseRules + revealjsRules + dashboardRules,

src/resources/formats/html/axe/axe-check.js

@@ -140,6 +140,10 @@ class QuartoAxeDocumentReporter extends QuartoAxeReporter {
 
     const section = document.createElement("section");
     section.className = "slide quarto-axe-report-slide scrollable";
+    // Force a white slide background so the report stays readable regardless
+    // of the deck's brand/theme colors. Reveal applies this to the slide's
+    // generated `.slide-background` element during sync().
+    section.setAttribute("data-background-color", "#fff");
 
     const title = document.createElement("h2");
     title.textContent = "Accessibility Report";

tests/docs/smoke-all/2026/05/01/issue-14468-axe-brand.qmd

@@ -0,0 +1,23 @@
+---
+title: "Issue 14468 - axe must not clobber brand colors"
+format:
+  html:
+    axe: 
+      output: document
+brand:
+  color:
+    background: "#5e1717"
+  typography:
+    link:
+      color: "#18a918"
+_quarto:
+  tests:
+    html:
+      ensureCssRegexMatches:
+        - ['--bs-body-bg:\s*#5e1717', '--bs-link-color:\s*#18a918', 'quarto-axe-report\s*\{[^}]*background-color:\s*var\(--r-background-color,\s*#fff\)']
+        - ['--bs-body-bg:\s*#fff[\s;]']
+---
+
+## Section
+
+Some [link](http://example.org) text.

tests/docs/smoke-all/2026/05/01/issue-14468-axe-dashboard.qmd

@@ -0,0 +1,25 @@
+---
+title: "Issue 14468 - axe must not clobber brand colors (dashboard)"
+format:
+  dashboard:
+    axe: 
+      output: document
+brand:
+  color:
+    background: "#5e1717"
+  typography:
+    link:
+      color: "#18a918"
+_quarto:
+  tests:
+    dashboard:
+      ensureCssRegexMatches:
+        - ['--bs-body-bg:\s*#5e1717', '--bs-link-color:\s*#18a918', 'quarto-axe-offcanvas\s*\{[^}]*--bs-offcanvas-bg:\s*#fff']
+        - ['--bs-body-bg:\s*#fff[\s;]']
+---
+
+## Row
+
+Content for accessibility checking.
+
+[example](http://example.org)

tests/docs/smoke-all/2026/05/01/issue-14468-axe-no-brand.qmd

@@ -0,0 +1,15 @@
+---
+title: "Issue 14468 - axe defaults still work without brand"
+format:
+  html:
+    axe: true
+_quarto:
+  tests:
+    html:
+      ensureCssRegexMatches:
+        - ['--bs-body-bg:\s*#fff', '\.quarto-axe-report']
+---
+
+## Section
+
+Some [link](http://example.org) text.

tests/docs/smoke-all/2026/05/01/issue-14468-axe-revealjs.qmd

@@ -0,0 +1,28 @@
+---
+title: "Issue 14468 - axe sass bundle still compiles for revealjs"
+format:
+  revealjs:
+    axe: 
+      output: document
+brand:
+  color:
+    background: "#5e1717"
+    foreground: "#d6c50f"
+  typography:
+    link:
+      color: "#18a918"
+_quarto:
+  tests:
+    revealjs:
+      ensureCssRegexMatches:
+        - ['\.quarto-axe-report', 'quarto-axe-report-slide\s*\{[^}]*color:\s*#222']
+        - ['\$body-bg', '\$body-color', '\$link-color']
+---
+
+## Slide 1
+
+Content for accessibility checking. <http://example.org>.
+
+## Slide 2
+
+More content.