Accessibility and structure / Alt text on images
Alt text on images in a PDF
A text description attached to a figure structure element, which is what a screen reader speaks in place of an image it cannot see.
Where this API stands
This API does not produce this standard, and there is no option that would. What follows is what the requirement actually is and where a rendered document stands against it. This API writes no structure elements, so no /Alt is written for anything. The `alt` attribute in your markup is nonetheless the thing that matters, because it is what a remediation pass promotes into /Alt when one runs, and because writing it now costs nothing while retrofitting it across a template library later costs a week. Note also that `alt=""` is not the same as a missing `alt`: the empty string is a declaration that the image is decorative and should be skipped, which is a decision, and a missing attribute is an omission that a tool has to guess about.
What the standard requires
The requirements as a checker enforces them, rather than as a procurement document paraphrases them. A file satisfies all of these or it satisfies none of them.
- The description sits in /Alt on the structure element wrapping the image, not on the image XObject itself.
- /ActualText is a different field for a different job: it replaces content with its text equivalent, which is what you want for a word rendered as a logo, not for a photograph.
- An image that carries no information is marked as an artifact rather than given an empty /Alt, and the two are not interchangeable.
- A chart or diagram needs a description of what it shows, and where the underlying numbers matter, they belong in the document as a table rather than in a description of one.
- PDF/UA has no exemption for decorative images: every image is either described or explicitly an artifact, and an image that is neither is a failure.
Who asks for this
Every accessibility audit, and it is usually the first finding because it is the easiest thing to check mechanically. It also comes up in plain content review: a report emailed to a client who reads it with a screen reader is a support conversation you only have once.
What it looks like in a file
The concrete form of the thing being described, so you can recognise it in a document you have been handed rather than only in a specification.
<!-- Informative: the description carries what the image says. -->
<figure>
<img src="revenue.svg"
alt="Revenue by quarter, rising from 1.2M in Q1 to 2.9M in Q4.">
<figcaption>Figure 3. Revenue by quarter</figcaption>
</figure>
<!-- Decorative: an explicit declaration, not an omission. A rule, a
watermark or a background flourish belongs here. -->
<img src="divider.svg" alt="" role="presentation">
<!-- Text rendered as an image: this wants the text equivalent, which
maps to /ActualText rather than /Alt when the file is tagged. -->
<img src="wordmark.svg" alt="Northwind Trading">What to do about it
Put a real `alt` on every image in the template now, and an explicit `alt=""` plus `role="presentation"` on the ones that are decoration. When the tagging step happens later, the descriptions are already there and the remediation is mechanical. For charts rendered as images, put the same description in the `alt` and consider shipping the source numbers as a table elsewhere in the document, which helps sighted readers too.
How to check a file rather than assume
PAC 2024 lists every figure element and whether it has alternative text, and flags the ones that do not. Acrobat's accessibility check does the same under "Figures alternate text". Neither can judge whether the text is any good, so read a sample of them out loud and see whether the sentence makes sense on its own.
The mistake people make here
Describing the file rather than the content. "chart.png", "Figure 3" and "company logo" are all technically alternative text and all useless. The test is whether a person who cannot see the image learns the same thing from the sentence that a person who can see it learns from the picture.
Frequently asked
Does this API produce Alt text on images?
Not produced by this API. This API writes no structure elements, so no /Alt is written for anything. The `alt` attribute in your markup is nonetheless the thing that matters, because it is what a remediation pass promotes into /Alt when one runs, and because writing it now costs nothing while retrofitting it across a template library later costs a week. Note also that `alt=""` is not the same as a missing `alt`: the empty string is a declaration that the image is decorative and should be skipped, which is a decision, and a missing attribute is an omission that a tool has to guess about.
Can I turn on the pdf_a option and be done?
No. The option writes an XMP packet declaring PDF/A-1b into the document catalogue, and the render response comes back carrying a warning that says in as many words that this is best-effort and that full conformance requires tagged structure and an embedded ICC profile. It is a claim written into the file, not a certificate earned by it, and a validator checks the claim against the bytes. Read the warning array in the response rather than taking the absence of an error as a pass.
Should I convert before rendering or after?
After, always. A conformance converter rewrites colour, embeds profiles, sets boxes and stamps metadata on a finished PDF. Trying to satisfy a conformance target from the source side means guessing at what the converter would have done, and the guesses that go wrong are expensive: flattening transparency you did not need to flatten changes what the page looks like.
Standards this one is confused with
The neighbours that matter are the ones people mistake for this, not the ones that sort next to it.
PDF artifacts: page furniture that is not content
The distinction between content that belongs in the reading order and page furniture that does not, marked in the content stream so a screen reader can skip the furniture.
PDF/UA-1 compliance for a generated PDF
ISO 14289-1: the standard that says a PDF is usable by assistive technology, which in practice means it carries a complete and correct structure tree.
The logical structure tree in a PDF
The tree of typed elements, Document at the root and paragraphs, lists, tables and figures below it, that describes what the document is made of.
How to tell if a PDF is tagged
A tagged PDF carries a second, invisible copy of itself: a tree of headings, paragraphs, lists and cells that says what the content is, rather than where the ink goes.
Reading order in an accessible PDF
The sequence a screen reader speaks the document in, which comes from the order of elements in the structure tree and not from where anything sits on the page.
Every standard, with what this API does about it
The full list, grouped by what the requirement is for, each marked with how far this API gets.
What this API actually does
One page per option and endpoint that exists, with nothing that does not.
Conformance is decided after a file exists. Render the document, then check it, then convert only what the checker actually flags.