Skip to content

PDF Accessibility (PDF UA, WCAG, Section 508) Support

Jump to bottom Edit New page
danfickle edited this page Jul 12, 2021 · 8 revisions

Note: PDF/UA only documents have not been compliant in recent releases due to missing Dublin Core metadata (see #707. This will be fixed in version 1.0.10. In the meantime PDF/UA documents which also use PDF/A compliance should continue to work.

This project is now able to produce PDF documents which are accessible to screen readers, in compliance with standards like PDF/UA, Section 508 and WCAG 2. As well as being important to screen-reader users, many governments now require that PDF documents submitted be accessible.

HTML example

<html lang="EN-US">
<head>
  <title>All-in-one PDF/UA Testcase</title>
  <meta name="subject" content="PDF/UA all-in-one"/>
  <meta name="author" content="openhtmltopdf.com team"/>
  <meta name="description" content="An example containing everything for easy testing"/>
  
  <bookmarks>
   <bookmark name="Simple Paragraphs" href="#para"/>
   <bookmark name="Lists" href="#lists">
     <bookmark name="Ordered" href="#ordered"/>
     <bookmark name="Unordered" href="#unordered"/>
   </bookmark>
   <bookmark name="Images" href="#images"/>
   <bookmark name="Links" href="#links"/>
   <bookmark name="Tables" href="#tables"/>
   <bookmark name="Backgrounds" href="#backgrounds"/>
   <bookmark name="Conclusion" href="#conclusion"/>
  </bookmarks>
    
  <style>
  @page {
    margin: 30px 20px;
    
    @top-center {
       font-family: 'TestFont'; /* Font provided with builder. */
       font-size: 16px;
       color: blue;
       content: "This is PDF/UA page " counter(page) " of " counter(pages) ".";
    }
  }
  body {
    margin: 0;
    font-family: 'TestFont'; /* Font provided with builder. */
    font-size: 15px;
  }
  </style>
</head>
<body style="">
 <h1 id="title">All-in-one accessible (PDF/UA, Section 508, WCAG) PDF example</h1>

 <h2 id="para">Simple paragraphs</h2>

 <p>Paragraph one. Some text that goes over multiple lines. OK, this is getting to the required length. Need another sentence to get there in the end.</p>
 <p>Paragraph two. Some text that goes over multiple lines. OK, this is getting to the required length. Need another sentence to get there in the end.</p>
 <p>Paragraph three. Some text that goes over multiple lines. OK, this is getting to the required length. Need another sentence to get there in the end.</p>

 <h2 id="lists">Lists</h2>

 <h3 id="ordered">Ordered</h3>
 <ol>
   <li>One</li>
   <li>Two</li>
   <li>Three</li>
 </ol>

 <h3 id="unordered">Unordered</h3>
 <ul>
   <li>Bullet item one</li>
   <li>And two</li>
   <li>And three</li>
 </ul>
 
 <h2 id="images">Images</h2>
 <img src="../../demos/images/flyingsaucer.png" alt="The FlyingSaucer logo. We should get our own!"/>

 <h2 id="links">Links</h2>
 <p>This is an external link to the project <a title="The openhtmltopdf.com homepage" href="https://openhtmltopdf.com">homepage</a>.</p>
 <p>This is an internal link to the <a title="Go to top" href="#title">top</a> of the document.</p>
 
 <h2 id="tables">Tables</h2>
  <table>
   <caption>Simple table example with fake data</caption>
   
   <thead>
     <tr><th>Col One</th><th>Col Two</th></tr>
   </thead>
   
   <tbody>
     <tr><td>One</td><td>Two</td></tr>
     <tr><td>Three</td><td>Four</td></tr>
     <tr><td>Five</td><td>Six</td></tr>
   </tbody>
   
   <tfoot>
     <tr><td>Footer1</td><td>Footer2</td></tr>
     <tr><td>Footer3</td><td>Footer4</td></tr>
   </tfoot> 
  </table>

 <h2 id="backgrounds">Backgrounds</h2>
  <div style="background-color: red; height: 40px; border-radius: 10px; border: 1px solid gray;">
    <p>Some text on a background. Remember to use a good contrast if using background colors.</p>
  </div>

 <h2 id="conclusion">Conclusion</h2>
 <p>Remember to keep it simple for PDF/UA compliance.</p>
 
</body>
</html>

Builder example

        try (FileOutputStream os = new FileOutputStream("/path/to/doc.pdf")) {
            PdfRendererBuilder builder = new PdfRendererBuilder();
            builder.useFastMode(); // required
            builder.usePdfUaAccessbility(true); // required
            builder.usePdfAConformance(PdfRendererBuilder.PdfAConformance.PDFA_3_U); // may be required: select the level of conformance
            // Remember to add one or more fonts.
            builder.useFont(new File("path/to/font.ttf"), "TestFont");
            builder.withHtmlContent(html, baseUrl);
            builder.toStream(os);
            builder.run();
        }

Guidelines

  • Provide a lang attribute on the html element with the document language as an ISO code.
  • Provide a proper title in the title element.
  • Provide a meta description, subject and author.
  • Provide bookmarks linking to the sections of your document, especially for documents larger than a handful of pages.
  • Provide a page header or footer with page number information.
  • Content in page margins and fixed position elements is marked as pagination artefacts so avoid putting critical information in such places.
  • If using background colors or images, remember to use a good contrast for text over them.
  • Images and other replaced elements like SVG are required to have an alt attribute with alternate text.
  • Links are required to have a title attribute with a description of the link target.
  • PDF/UA prohibits the use of built-in fonts so make sure to provide a font and specify it for the body element and any page margin rules (eg. @top-center).
  • Avoid using overflow:hidden. The PDF specification makes it very hard to include clips in tagged content and this implementation is not expected to be clip compatible.
  • Avoid using transforms in content (you can use them in running boxes such as the page margin and fixed position elements).
  • Avoid using position with relative or absolute. Out-of-flow content upsets the reading order. Again you can use them in running elements.
  • Use the float property with caution, it can upset the reading order of the document.
  • Avoid using table elements for layout. Instead, if desiring a table based layout, use a div with display: table, display: table-row, etc.
  • Avoid, if possible, images over two or more pages.
  • Nest header levels correctly (h1, h2, etc).
  • This implementation does not yet cover form controls, such as the input element.

Testing

  • Test your output documents with the PDF Accessibility Checker or PAC. This is Windows software and is free (though not open-source). Pay special attention to the screen-reader preview (making sure the text in the proper order and markup).
  • Test with Acrobat Pro, if available.
  • Also consider testing with actual screen-reader software.

Further Resources

Implementation

You can see:

Acknowledgments

This PDF/UA implementation is indebted to the work of @chris271 at StackOverflow and Github.

Thank you for using this project.

Add a custom sidebar
Clone this wiki locally