quarto-dev / quarto-dev/quarto-cli
a11y: appendix `opacity: 0.9` pushes footnote back-links below WCAG AA contrast
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 6k
- Forks
- 458
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 41
Description
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
Quarto dims appendix content (footnotes, citation, reuse) with opacity: 0.9:
Opacity composites every descendant toward the page background, so it silently erodes the contrast of colors that pass WCAG on their own. Link colors are the first casualty because they sit closest to the 4.5:1 line — including the default theme, which fails out of the box:
| theme | $link-color |
unfaded | after opacity: 0.9 |
effective ratio |
|---|---|---|---|---|
| default (built-in) | #0d6efd |
4.50:1 ✓ | #257dfd |
3.86:1 ✗ |
| cosmo (built-in) | #2761e3 |
5.38:1 ✓ | #3d71e6 |
4.46:1 ✗ |
| quarto.org | #39729E |
5.15:1 ✓ | #4d80a8 |
4.22:1 ✗ |
axe-core flags the footnote back-links (a.footnote-back[role="doc-backlink"]) as color-contrast, WCAG 2.0 AA 1.4.3, impact serious. This is how it surfaced in an axe audit of quarto.org; the site is working around it by restoring opacity: 1 on appendix content in its light theme (quarto-dev/quarto-web#2102). Any link inside footnote text is equally affected, and the fade also compounds the appendix <summary> contrast failure reported in #14383.
A fix that keeps the dimmed design without the conformance risk: derive a dimmed color (the theme-contrast(..., "AA") machinery in _bootstrap-functions.scss provides a contrast floor) instead of using opacity, which no theme author can counteract from a descendant element.
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:
axe:
output: document
---
Some text with a footnote.[^1]
[^1]: A footnote.
Render (default theme, no customization) and check the effective color of the ↩︎ back-link in the footnotes section. To see the failure with a comfortably conformant link color, add theme: cosmo ($link-color #2761e3, 5.38:1 on white) — the back-link still lands at 4.46:1.
Actual behavior
With the default theme, the back-link composites to an effective #257dfd on #ffffff = 3.86: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
.footnote-back
In-body links on the same page pass (default $link-color #0d6efd is 4.5:1 unfaded) — only the appendix-faded ones fail.
Expected behavior
Appendix links keep at least 4.5:1 effective contrast whenever the theme's $link-color is itself conformant — dimming should not undo a contrast-safe color.
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...
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the appendix rule in src/resources/formats/html/bootstrap/_bootstrap-rules.scss and the theme-contrast machinery in _bootstrap-functions.scss. Render the provided footnote repro with the axe output enabled, then verify that appendix links retain at least 4.5:1 contrast when the theme link color is conformant.】【。
Written by the indexing model from the issue text.
Assessment
- Tech stack
- scss
- Domain
- accessibility, frontend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 74/100