Skip to content

Add high-level accessibility API for tagged PDF generation#1391

Open
craigmcnamara wants to merge 5 commits intoprawnpdf:masterfrom
mes-amis:section-508-accessability
Open

Add high-level accessibility API for tagged PDF generation#1391
craigmcnamara wants to merge 5 commits intoprawnpdf:masterfrom
mes-amis:section-508-accessability

Conversation

@craigmcnamara
Copy link
Copy Markdown

@craigmcnamara craigmcnamara commented Mar 26, 2026

Summary

Adds Prawn::Accessibility module providing a user-friendly API for generating Section 508 compliant tagged PDFs.

New document options:

  • marked: true — enables tagged PDF mode (structure tree, marked content)
  • language: 'en-US' — sets /Lang on the Catalog

New methods on Prawn::Document:

  • tagged? — check if document is in tagged mode
  • structure(tag, attributes, &block) — wrap content in a structure element with BDC/EMC
  • structure_container(tag, attributes, &block) — container element for nesting (children tag themselves)
  • artifact(type:, &block) — mark decorative content (footers, borders) excluded from screen readers
  • heading(level, text, options) — H1-H6 convenience
  • paragraph(text, options, &block)<P> convenience
  • figure(alt_text:, &block)<Figure> with /Alt

Supported attributes: :Alt, :ActualText, :Lang, :Scope

pdf = Prawn::Document.new(marked: true, language: 'en-US')
pdf.heading(1, 'Document Title')
pdf.paragraph('Body text.')
pdf.structure(:Span, ActualText: 'required') { pdf.text('*') }
pdf.artifact(type: :Pagination) { pdf.text('Page 1') }

Dependency: This PR depends on prawnpdf/pdf-core#67 being merged first. The new accessibility specs require the marked: option and StructureTree class added in that PR. Test failures in CI for release and edge matrix variants are expected until pdf-core#67 is merged and available.

See also companion PR for prawn-table#164.

Addresses prawnpdf/prawn-table#78

Test plan

  • 18 new specs covering tagged mode, structure elements, artifacts, headings, paragraphs, figures, ActualText, and full document round-trip
  • All 912 specs pass locally (896 existing + 18 new, using local pdf-core fork)
  • RuboCop passes
  • CI: release and edge tests will pass once pdf-core#67 is merged
  • Generate a tagged PDF and verify structure in Adobe Acrobat Tags panel
  • Run PAC 2024 accessibility checker

🤖 Generated with Claude Code

craigmcnamara and others added 3 commits March 25, 2026 15:28
Adds Prawn::Accessibility module providing structure(), structure_container(),
artifact(), heading(), paragraph(), and figure() methods for creating
Section 508 compliant tagged PDFs.

Usage:
  pdf = Prawn::Document.new(marked: true, language: 'en-US')
  pdf.heading(1, 'Title')
  pdf.paragraph('Body text.')
  pdf.artifact { pdf.text 'Page 1' }

New options on Prawn::Document.new:
  - marked: true — enables tagged PDF mode
  - language: 'en-US' — sets document language in Catalog

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Tests that ActualText is properly passed through to structure elements,
useful for screen reader replacement text on symbolic characters like
* (required) and X (selected checkbox).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
craigmcnamara and others added 2 commits March 26, 2026 09:59
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant