quarto-dev / quarto-dev/quarto-cli

a11y: appendix `opacity: 0.9` pushes footnote back-links below WCAG AA contrast

Open
#14,679 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

accessibility bug html
Dominant language
JavaScript
Stars
6k
Forks
458
Avg merge
1d 9h
Merged PRs (30d)
41

Description

I have:

Bug description

Quarto dims appendix content (footnotes, citation, reuse) with opacity: 0.9:

https://github.com/quarto-dev/quarto-cli/blob/8577ed1c69b3b9a551f1669c8256abc4a1731266/src/resources/formats/html/bootstrap/_bootstrap-rules.scss#L1875-L1881

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.