PDF Accessibility skill for Codex

An accessible PDF is done when veraPDF’s PDF/UA profile reports no failures, PAC (or Acrobat’s checker) agrees, and a manual pass confirms what machines cannot: alt text says something useful, the reading order matches the visual order, and headings and tables make sense to a screen-reader user.

The rule that saves the most time

Fix accessibility at the source and regenerate. Remediating an untagged PDF by hand (or by script) is slow, fragile and lost on the next export. Only remediate when the source is gone, and say so in the report.

Requirements checklist (PDF/UA-1 plus WCAG essentials)

Requirement	Where it lives in the file
Tagged, with all real content inside the structure tree	/MarkInfo << /Marked true >>, /StructTreeRoot
Decorative content marked as artifacts (headers, footers, page numbers, rules)	Artifact marked content in page streams
Logical heading hierarchy, no skipped levels	H1..H6 (or H in PDF 2.0) structure elements
Alt text on every informative figure, none on decorative ones (artifact instead)	/Alt on Figure
Tables with header cells and scope	Table / TR / TH with /Scope / TD
Lists as lists	L / LI / Lbl / LBody
Document language	Catalog /Lang (and on spans in another language)
Title shown in the window, from metadata	XMP dc:title plus /ViewerPreferences << /DisplayDocTitle true >>
PDF/UA identifier	XMP pdfuaid:part = 1
Fonts embedded with Unicode mapping	Every font embedded, ToUnicode present
Bookmarks for documents longer than a few pages	/Outlines
Links and form fields labelled	Link elements with /Contents, field /TU tooltips
Colour not the only cue, contrast at least 4.5:1 for body text	Design, checked visually
Tab order follows structure	Page /Tabs /S

Workflow

- [ ] 1. Probe the existing PDF (or the generator's output)
- [ ] 2. Decide: regenerate from source, or remediate
- [ ] 3. Fix the source and export with tagging/PDF-UA options
- [ ] 4. Validate: veraPDF PDF/UA, then PAC or Acrobat
- [ ] 5. Manual checks a validator cannot do
- [ ] 6. Report with residual issues

1. Probe

Quick structural probe with pikepdf (pip install pikepdf, needs network):

import sys
from collections import Counter
import pikepdf

pdf = pikepdf.open(sys.argv[1])
root = pdf.Root
report = {
    "tagged": "/StructTreeRoot" in root and bool(root.get("/MarkInfo", {}).get("/Marked", False)),
    "lang": str(root.get("/Lang", "")) or None,
    "display_doc_title": bool(root.get("/ViewerPreferences", {}).get("/DisplayDocTitle", False)),
    "pdfua_id": b"pdfuaid:part" in (root.Metadata.read_bytes() if "/Metadata" in root else b""),
    "outlines": "/Outlines" in root,
}
with pdf.open_metadata() as meta:
    report["xmp_title"] = meta.get("dc:title")

roles, missing_alt = Counter(), 0
def walk(node, depth=0):
    global missing_alt
    if depth > 200:
        return
    if isinstance(node, pikepdf.Array):
        for k in node:
            walk(k, depth + 1)
    elif isinstance(node, pikepdf.Dictionary):
        s = node.get("/S")
        if s is not None:
            roles[str(s)] += 1
            if str(s) == "/Figure" and "/Alt" not in node and "/ActualText" not in node:
                missing_alt += 1
        if "/K" in node:
            walk(node["/K"], depth + 1)

if "/StructTreeRoot" in root:
    walk(root.StructTreeRoot.get("/K"))
print(report, dict(roles.most_common(15)), "figures without alt:", missing_alt)

Read the result:

• tagged: False means a screen reader guesses the order from the content stream. Regenerate if at all possible.
• Roles only P and Span, no H1..H6: the source used manual formatting instead of heading styles.
• Custom role names (e.g. /Heading1) are fine only if /RoleMap maps them to standard types.
• fonts: also run pdffonts file.pdf (poppler); every row needs emb yes and uni yes.

2. Decide

Situation	Action
Source available (DOCX, ODT, HTML, Typst, LaTeX)	Fix source, regenerate (step 3)
Scanned PDF	OCR first (ocrmypdf), then remediate; a scan has no structure
Source lost, short document	Remediate in Acrobat Pro or similar by hand; scripts cannot infer reading order reliably
Source lost, long document	Rebuild the source (convert to DOCX/HTML, fix, re-export); usually faster than remediation
Fillable form	Fix field tooltips (/TU), tab order, and tag form fields (Form elements)

3. Generate tagged PDFs

Source	Export
Word (Microsoft 365)	Save As PDF, Options: “Document structure tags for accessibility” on, “Create bookmarks using headings”; run Check Accessibility first
LibreOffice	soffice --headless --convert-to 'pdf:writer_pdf_Export:{"UseTaggedPDF":{"type":"boolean","value":"true"},"PDFUACompliance":{"type":"boolean","value":"true"}}' doc.odt (LibreOffice 7.4+ JSON filter options)
Typst 0.14+	Tagged by default; typst compile --pdf-standard ua-1 doc.typ adds PDF/UA checks and fails on violations; set alt: on images and set document(title: ...)
HTML via Chromium (Playwright)	page.pdf({ tagged: true, outline: true, ... }); semantic HTML drives the tags
HTML via WeasyPrint	weasyprint --pdf-variant pdf/ua-1 in.html out.pdf (check weasyprint --help for variants in the installed version)
LaTeX	Kernel tagging via \DocumentMetadata{lang=en, pdfversion=2.0, pdfstandard=ua-2, testphase=latest} (recent TeX Live, LuaLaTeX preferred); still maturing, so verify with veraPDF before claiming conformance

Source fixes that matter more than export flags:

• Use real heading styles in order (one H1 or title, then H2, H3 without gaps).
• Write alt text that states the point of the image (“Revenue doubled from 2023 to 2025”), not its appearance (“bar chart”). Decorative images: mark as decorative.
• Mark table header rows (Word: “Repeat as header row”; HTML: <th scope="col">). Avoid merged cells and nested tables; split complex tables.
• Set the document title in properties/metadata, and the document language.
• In HTML, use <h1>..<h6>, <ul>/<ol>, <table> with <th>, <figure> with <img alt>, lang on <html>. Avoid div-soup; tags follow the DOM.
• Text in images is invisible to screen readers; use real text.

4. Validate

verapdf --flavour ua1 --format text doc.pdf       # veraPDF CLI, needs Java; install needs network
verapdf --flavour ua1 --format html doc.pdf > verapdf-report.html

veraPDF checks the machine-checkable PDF/UA rules (Matterhorn Protocol failure conditions). Then run PAC (free, Windows) or Acrobat Pro’s “Full Check” if the user has them; ask the user to run them when you cannot.

5. Manual checks

Machines cannot judge these; do them and record the result:

• Read the tag tree order (Acrobat Tags panel, PAC’s logical structure view, or the probe’s role walk) against the visual order on 3 representative pages.
• Read every alt text: meaningful, concise, no “image of”.
• Check that headers, footers, page numbers and watermarks are artifacts, not content.
• Check table header association on the most complex table.
• Zoom to 400% (reflow) and check contrast on coloured backgrounds.
• If available, listen to two pages with NVDA, JAWS or VoiceOver.

Gotchas

• A PDF can be “tagged” and still useless: auto-tagging often marks everything as P and reads multi-column pages across columns.
• Post-processing tools (Ghostscript compression, some merge tools, printing to PDF) strip tags. Merge with qpdf or pypdf and recheck; never “print to PDF”.
• PDF/A and PDF/UA are different; PDF/A-1a/2a requires tagging, but PDF/A-2b does not. Claim only what you validated.
• Adding pdfuaid:part to metadata does not make a file conformant; it only claims it.
• Mathematical formulas need Formula tags with alt text (or MathML in PDF 2.0 workflows).
• Links need meaningful text in context; “click here” passes validators and fails users.

Output

## PDF accessibility: annual-report-2026.pdf
- Route: regenerated from annual-report.docx (Word heading styles fixed, 12 alt texts added)
- Probe: tagged yes, lang en-GB, DisplayDocTitle yes, pdfuaid 1, bookmarks yes, fonts embedded
- veraPDF ua1: 0 failed rules (was 143); PAC: passed (run by user)
- Manual: reading order ok on p.3/7/22; 2 decorative images artifacted; table 4 split into two
- Residual: chart on p.18 has a summary alt text; full data table added in appendix