Alt text is a short text alternative that serves the same purpose as the image for a reader who cannot see it. In an EPUB it is not optional: it is required through the accessibility specification, decorative images must carry an empty alt attribute rather than a description, and a visible caption never satisfies the requirement.
That last point is the one most tools get wrong, including, partly, Deckle.
Where the Requirement Comes From
EPUB Accessibility 1.1, a W3C Recommendation dated 17 October 2024, contains no standalone alt text clause. The obligation arrives through its incorporation of WCAG:
"To conform to this specification, an EPUB publication: MUST, at the minimum, meet the requirements of WCAG 2.0, but it is strongly recommended that it meet the requirements of the latest recommended version of WCAG 2. MUST, for whichever version of WCAG 2 selected, meet the requirements of Level A, but it is strongly recommended that it meet the requirements of Level AA."
The operative rule is therefore WCAG success criterion 1.1.1, Non-text Content, at Level A:
"All non-text content that is presented to the user has a text alternative that serves the equivalent purpose, except for the situations listed below."
Two consequences people miss. The requirement applies to the whole publication, not file by file: EPUB Accessibility 1.1 states that creators "MUST evaluate the WCAG guidelines... against the full EPUB publication, not only against each EPUB content document within it." And you cannot escape it with a fallback, since "If an EPUB creator uses fallbacks, both the primary content and its fallback(s) MUST meet the requirements for the conformance level claimed."
Deciding What to Write
The W3C's decision tree resolves in a fixed order. Simplified for books:
Is the image purely decorative? An ornament, a rule, a texture, a scene break glyph. Use an empty alt: alt="". This is not laziness, it is the correct answer, and DAISY is explicit that you should "Ensure that decorative images are not presented to users." Adding "decorative flourish" as alt text makes the book worse to listen to.
Is it an image of text? Put the text in the alt attribute. Better still, avoid the image: WCAG 1.4.5 at Level AA requires that "If the technologies being used can achieve the visual presentation, text is used to convey information rather than images of text", with logos excepted as essential.
Does it convey meaning? Write a brief description. DAISY's guidance is to answer "who, what, where, when, why and how" but "in as few words as possible", and it sets a boundary worth remembering: the description "should not introduce facts that are not discernible from the visual depiction." Describe the photograph, not the history behind it.
Is it complex, like a chart or a diagram? A short alt plus an extended description elsewhere. DAISY's advice is to first ask whether the long description is needed at all: "Ask yourself if the description... will add pertinent information that aids in the understanding, or is it detail for details sake?"
Is it redundant with adjacent text? Empty alt. If the paragraph beside it already says what it shows, describing it again is repetition.
A Caption Is Not Alt Text
This distinction gets collapsed constantly, and DAISY states it flatly: "Providing a caption is not a substitute for making the content within the figure accessible."
They do different jobs. A caption is visible to everyone and adds context, attribution or commentary. Alt text replaces the image for someone who cannot see it. A screen reader announces both, so if they are identical the listener hears the same sentence twice.
The practical rule: the caption says what a sighted reader needs to know in addition to seeing the image. The alt text says what they would have got from seeing it.
Long Descriptions, and the Technique to Avoid
For charts and complex diagrams, DAISY's preferred technique is aria-details pointing at a visible <details> element, or a link to a separate description document.
It specifically warns against the technique most tools emit. Support for aria-describedby "is poor in EPUB", and "This technique is not recommended if the description contains structured markup like tables or lists, as all tagging is stripped and only the text content read to users." A described table becomes an unpunctuated run of numbers.
What Deckle Does
Deckle does have an alt text field, and it does reach the file. When you insert an image, the modal offers a field labelled "Alt text (accessibility)", and what you type there is emitted as the alt attribute in the exported EPUB.
Decorative images are handled correctly and automatically. Chapter ornaments, scene break glyphs and full-page background images are all written with alt="", and the full-bleed background additionally carries aria-hidden="true". That is exactly what the guidance above requires, and it is done without you having to think about it.
Deckle also declares this in the file's metadata. It claims the alternativeText accessibility feature only when every body image in the manuscript has a text alternative, so one undescribed image silently withdraws the claim rather than overstating it.
The remaining limitation is the distinction in the section above. The image dialog writes one string, so the text you enter serves as both the alt text and the visible <figcaption>. Where captions are switched on, a screen reader user hears the same sentence twice.
The practical workaround: if the image needs a caption, write the caption and accept that it doubles as the alt text, which is usually adequate for a simple photograph. If it needs a description rather than a caption, turn captions off in the Styler, and your text stays in the alt attribute where it belongs while nothing appears on the page.
One image type to watch. A full page bleed image is rendered through a different path that emits no alt attribute at all, so a book containing one will never claim alternativeText. If the image is decorative that is correct. If it carries meaning, describe it in the surrounding prose.
There is no long-description mechanism, so a complex chart is better described in the surrounding prose, which is also what the W3C's decision tree recommends for graphs: "Include the information contained in the image elsewhere on the page."
For what else conformance requires, see accessible EPUB structure and reading order and European EPUB requirements. For getting the images themselves export-ready, see preparing images for export.
Common Mistakes
- Describing decorative images. An empty alt is the correct answer for an ornament.
- Repeating the caption as alt text. The listener hears it twice.
- Writing "image of" or "photo of". The reading system already announces that it is an image.
- Describing what the image cannot show. Stick to what is visually discernible.
- Using
aria-describedbyfor long descriptions. DAISY says support is poor and markup is stripped. - Assuming a file-by-file check is enough. Conformance is evaluated across the whole publication.
FAQ
Q: Is alt text legally required? A: EPUB Accessibility 1.1 requires WCAG Level A conformance, which includes it. Accessibility legislation in the EU and US makes this commercially significant.
Q: What about purely decorative images?
A: Empty alt, alt="". That is the requirement, not a shortcut.
Q: How long should alt text be? A: As short as conveys the purpose. DAISY says answer who, what, where, when, why and how in as few words as possible.
Q: Does a caption count? A: No. DAISY states a caption is not a substitute.
Q: What about the cover image? A: It should have alt text too, conventionally the book's title.