From 80f817dfdb64798991f619207793468cbcf26b67 Mon Sep 17 00:00:00 2001 From: Benjamin Mako Hill Date: Thu, 13 Aug 2026 16:42:01 -0700 Subject: [PATCH] Document what the accessibility support does and does not do Slides-only builds validate as PDF/UA-2, which is what upload targets check for, but only frame titles and links are actually tagged. Say so rather than leaving the veraPDF pass to imply more than it means. Co-Authored-By: Claude Opus 5 (1M context) --- slides_template/README | 39 +++++++++++++++++++++++++++++++++++++ slides_template/example.tex | 2 ++ 2 files changed, 41 insertions(+) diff --git a/slides_template/README b/slides_template/README index a28e56d..894d556 100644 --- a/slides_template/README +++ b/slides_template/README @@ -46,6 +46,45 @@ everything needed. The template uses the Metropolis Beamer theme, bundled in the template/ directory along with the OpenSans and RobotoMono fonts it requires. +================================ +=== Accessibility ============== +================================ + +Slides are built as tagged PDFs that validate against PDF/UA-2 +(ISO 14289-2), which is what upload targets like Canvas check for. Check +a file with veraPDF (https://verapdf.org/): + + verapdf -f ua2 my-talk.pdf + +The pieces that do this work are: + + * \DocumentMetadata declares PDF/UA-2, PDF 2.0, and the document + language. The language tag tells a screen reader how to pronounce + the text. + * tagpdf with activate-all turns tagging on. + * The frametitle template is patched to emit H1 tags, since Beamer + does not treat frame titles as headings on its own. + * unicode-math replaces the Computer Modern math fonts, which carry no + Unicode mappings and leave formulas unreadable to assistive software. + * \hypersetup{pdfdisplaydoctitle=true} makes viewers announce the + document title instead of the filename. + * The tikz overlays behind \credit, \marktopleft, and \markbottomright + are marked as artifacts so they stay out of the reading order. + +Use a slides-only build (make slides) for anything shared. Builds that +include speaker notes do not validate, because Beamer repeats the frame +title and section headings on the notes half of each page. + +Validating is not the same as being accessible, and this template does +the first better than the second. Frame titles and links are tagged; +body text, lists, and figures are not, so a screen reader gets the +outline of a talk rather than its contents. Closing that gap needs +automatic tagging from the LaTeX kernel (\DocumentMetadata{tagging=on}), +which requires TeX Live 2025 or later and is waiting on Overleaf to +support it, and Beamer support in the LaTeX Tagging Project, which does +not exist yet. The alt={...} arguments in the template are written for +that day; they are dropped by the current toolchain. + ================================ === Scripts ==================== ================================ diff --git a/slides_template/example.tex b/slides_template/example.tex index 325b48f..ebeef9f 100644 --- a/slides_template/example.tex +++ b/slides_template/example.tex @@ -153,6 +153,8 @@ BoldItalicFont = *-BoldItalic } % packages i use in essentially every document +% give every \includegraphics an alt={...} description. the current +% toolchain drops it, but it will be used once tagging is available \usepackage{graphicx} \usepackage{url} % \usepackage{dcolumn}