a11y: secondary text (blockquotes, captions, asides) fails WCAG AA color contrast in cosmo

[cwickham]

I have:

• searched the issue tracker for similar issues
• installed the latest version of Quarto CLI
• formatted my issue following the Bug Reports guide

Bug description

The body-secondary mixin, which colors blockquotes, figure/table captions, header section numbers, and margin/aside text, derives its color as theme-dim($body-color, 25%) with no contrast check:

quarto-cli/src/resources/formats/html/bootstrap/_bootstrap-mixins.scss

Lines 1 to 7 in 8577ed1

	@mixin body-secondary {
	@if variable-exists(body-secondary) {
	color: $body-secondary;
	} @else {
	color: theme-dim($body-color, 25%);
	}
	}

For theme: cosmo this yields #747a7f on #ffffff = 4.34:1, below the WCAG 2.0 AA (1.4.3) minimum of 4.5:1 — axe-core flags it as color-contrast, impact serious. On quarto.org (a cosmo-derived theme with $body-color: #343a40) the same derivation yields #6d7a86 = 4.39:1, which is how this surfaced in an axe audit of the site.

All five @include body-secondary sites are affected (_bootstrap-rules.scss lines 663, 695, 702, 710, 913), e.g. the blockquote rule:

quarto-cli/src/resources/formats/html/bootstrap/_bootstrap-rules.scss

Lines 909 to 914 in 8577ed1

	.blockquote {
	font-size: inherit;
	padding-left: 1rem;
	padding-right: 1.5rem;
	@include body-secondary;
	}

Quarto already has contrast-guarding machinery — theme-contrast() / accessibleContrast() with an explicit "AA" (4.5:1) level — used for navbar, footer, sidebar, and button foregrounds:

quarto-cli/src/resources/formats/html/bootstrap/_bootstrap-functions.scss

Lines 14 to 54 in 8577ed1

	@function theme-contrast($color, $bgColor, $level: "AAA") {
	// These will be defined in bootstrap, but creating values here
	// That will make this function accessible to callers prior to bootstrap variables
	// being set
	$black: rgb(0, 0, 0) !default;
	$white: rgb(255, 255, 255) !default;
	@if tone($bgColor) == "light" {
	@return accessibleContrast($color, $black, $bgColor, $level);
	} @else {
	@return accessibleContrast($color, $white, $bgColor, $level);
	}
	}
	@function accessibleContrast($startColor, $mixColor, $bgColor, $level: "AAA") {
	// A: 3:1
	// AA: 4.5:1
	// AAA: 7:1
	$goalContrastRatio: 3;
	@if $level == "AA" {
	$goalContrastRatio: 4.5;
	} @else {
	$goalContrastRatio: 7;
	}
	$percentMix: 100;
	$contrastRatio: 0;
	$contrastColor: null;
	@while ($contrastRatio < $goalContrastRatio and $percentMix > 0) {
	$contrastColor: mix(
	$startColor,
	$mixColor,
	percentage(quarto-math.div($percentMix, 100))
	);
	$contrastRatio: quarto-contrast($contrastColor, $bgColor);
	$percentMix: $percentMix - 1;
	}
	@return $contrastColor;
	}

Routing the mixin's fallback through it, e.g. theme-contrast(theme-dim($body-color, 25%), $body-bg, "AA"), would keep the dimmed look while guaranteeing conformance for every theme.

Two notes:

• The mixin already honors a $body-secondary SCSS variable when defined — quarto.org uses that as a workaround (Fix WCAG AA color contrast: muted text and appendix links (light theme) quarto-web#2102). It appears to be undocumented; worth documenting regardless of the fix here.
• Not every built-in theme fails: the default theme's body color dims to #5a6570 = 5.95:1, which passes. The failure depends on where $body-color lands, which is exactly why a contrast guard rather than a per-theme tweak seems right.

Related: the axe-finding family in #14373 and the accessibility epic #8706.

Investigated with AI assistance grounded in a local clone of quarto-cli (per CONTRIBUTING.md, "Using AI tools to investigate").

Steps to reproduce

---
title: repro
format:
  html:
    theme: cosmo
    axe:
      output: document
---

> A blockquote.

Render, open in a browser.

Actual behavior

The blockquote text renders at #747a7f on #ffffff = 4.34:1. axe-core reports:

Serious · WCAG 2.0 AA (1.4.3): Ensure the contrast between foreground and background colors meets WCAG 2 AA minimum contrast ratio thresholds
Elements must meet minimum color contrast ratio thresholds
p

The same color applies to figcaption/caption/.table-caption, .header-section-number, and margin/aside text.

Expected behavior

Text colors derived by Quarto for built-in themes meet the WCAG AA 4.5:1 minimum, e.g. by passing the body-secondary fallback through the existing theme-contrast(..., "AA") machinery.

Your environment

• IDE: Positron 2026.07.0 (build 352)
• OS: macOS 26.5.1 (build 25F80)

Quarto check output

Quarto 1.10.12
[✓] Checking environment information...
      Quarto cache location: /Users/charlottewickham/Library/Caches/quarto
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.8.3: OK
      Dart Sass version 1.87.0: OK
      Deno version 2.7.14: OK
      Typst version 0.14.2: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.10.12
      Path: /Applications/quarto/bin
[✓] Checking tools....................OK
      TinyTeX: v2026.04
      Chrome Headless Shell: 150.0.7871.115
      VeraPDF: 1.28.2
[✓] Checking LaTeX....................OK
      Using: TinyTex
      Path: /Users/charlottewickham/Library/TinyTeX/bin/universal-darwin
      Version: 2026
[✓] Checking Chrome Headless....................OK
      Using: Chrome Headless Shell installed by Quarto
      Path: /Users/charlottewickham/Library/Application Support/quarto/chrome-headless-shell/chrome-headless-shell-mac-arm64/chrome-headless-shell
      Version: 150.0.7871.115
[✓] Checking basic markdown render....OK
[✓] Checking R installation...........OK
      Version: 4.6.0
      Path: /Library/Frameworks/R.framework/Versions/4.6/Resources
      LibPaths:
        - /Users/charlottewickham/Library/R/arm64/4.6/library
        - /Library/Frameworks/R.framework/Versions/4.6/Resources/library
      knitr: 1.51
      rmarkdown: 2.31
[✓] Checking Knitr engine render......OK
[✓] Checking Python 3 installation....OK
      Version: 3.12.2
      Path: /Users/charlottewickham/.pyenv/versions/3.12.2/bin/python3
      Jupyter: 5.9.1
      Kernels: python3
[✓] Checking Jupyter engine render....OK
[✓] Checking Julia installation...

[cwickham]

Survey of all 26 built-in themes, measured from the actual compiled CSS (the .blockquote color rule and --bs-body-color vs --bs-body-bg) on Quarto 1.10.12 — a minimal blockquote doc rendered per theme.

Headline: 12 themes have fully conformant base text but non-conformant secondary text — that's the set a contrast guard on the derivation would fix. Two more (morph, spacelab) fail on secondary text too, but their base text already fails WCAG AA, so they're arguably broken upstream in Bootswatch rather than by this derivation.

Base text passes, secondary text fails (12):

theme	base text	secondary/blockquote
quartz	#ffffff on #686dc3 4.60:1 ✓	#bfbfbf 2.50:1 ✗
minty	#5a5a5a on #ffffff 6.90:1 ✓	#9a9a9a 2.81:1 ✗
lux	#55595c on #ffffff 7.07:1 ✓	#94999c 2.88:1 ✗
solar	#adb5bd on #002b36 7.24:1 ✓	#697582 3.19:1 ✗
cerulean	#495057 on #ffffff 8.18:1 ✓	#869099 3.25:1 ✗
zephyr	#495057 on #ffffff 8.18:1 ✓	#869099 3.25:1 ✗
materia	#444444 on #ffffff 9.74:1 ✓	#848484 3.74:1 ✗
pulse	#444444 on #ffffff 9.74:1 ✓	#848484 3.74:1 ✗
sandstone	#3e3f3a on #ffffff 10.62:1 ✓	#7f8177 3.96:1 ✗
cyborg	#adafae on #060606 9.19:1 ✓	#6d706e 4.05:1 ✗
cosmo	#373a3c on #ffffff 11.46:1 ✓	#747a7f 4.35:1 ✗
litera	#343a40 on #ffffff 11.51:1 ✓	#6d7a86 4.39:1 ✗

Base text already fails (2):

theme	base text	secondary/blockquote
morph	#7b8ab8 on #d9e3f1 2.63:1 ✗	#ced3e5 1.15:1 ✗
spacelab	#777777 on #ffffff 4.48:1 ✗	#b7b7b7 2.01:1 ✗

Both pass (12): united 4.74:1, slate 5.47:1, simplex 5.82:1, flatly/sketchy/default 5.95:1, journal/lumen/yeti 6.12:1, vapor 6.37:1, superhero 6.82:1, darkly 8.65:1 (secondary-text ratios).

Notes:

• morph is nearly illegible — 1.15:1 secondary text is background-on-background.
• Not light-theme-only: solar (3.19:1) and cyborg (4.05:1) fail on dark backgrounds.
• slate inverts: its base text fails (3.65:1) while its "dimmed" secondary passes (5.47:1) — on a dark background the dimming direction can raise contrast. The derivation's relationship to the background tone is unpredictable in both directions.
• Some of the flat-gray failures (quartz, minty) look like they come from theme-supplied variables rather than the theme-dim($body-color, 25%) fallback, so a guard on the fallback alone wouldn't catch all of these — the mixin's $body-secondary branch may need the same contrast treatment.

[mpjashby]

That's a fantastically helpful write-up of the issue – especially the link to the workaround and the list of themes that are/aren't affected. Makes it very easy to workaround while waiting for a roll-out of the eventual fix. Thanks!