This document provides guidance for publishers looking to move from the use of the EPUB 3
epub:type attribute to ARIA roles for accessibility.
It is important to understand the differences between the epub:type attribute [[epub-3]] and the role attribute [[wai-aria]] to ensure that
they are properly applied for their intended purposes and audiences.
The key difference is that the role attribute bridges accessibility in content while the
type attribute provides hooks to enable reading system behaviors. Omitting roles lessens the accessibility for users of assistive technologies, in other words, while
omitting types diminishes certain functionality in reading
systems (e.g., pop-up footnotes or special presentations of the content).
The result is that the application of epub:type semantics is largely harmless, but
misapplication of ARIA roles can have negative impacts on the reading experience, from over-announcement
of information to broken rendering for assistive technology users.
It is sometimes helpful to pair the attributes together, but this is only useful when both attributes provide benefits for their respective use cases. For example, it is common to pair footnote roles and types to ensure reading systems can provide pop-up functionality and assistive technologies can announce the type of link the user has encountered.
This guide addresses key authoring differences to be aware of when migrating to ARIA roles from the
epub:type attribute, or when using both attributes together. The goal is to help
publishers avoid the pitfalls of applying ARIA roles like they would epub:type semantics
and breaking the reading experience for users of assistive technologies.
This guide is not intended as a comprehensive overview of ARIA roles. For more information about ARIA and how to apply it to HTML document, refer to [[wai-aria]] and [[html-aria]], respectively.
It also only applies to EPUB content documents.
The epub:type attribute is the only means of adding structural information to media overlay documents so that features like
lists and tables can be navigated more efficiently. It is also required in the EPUB navigation document to identify key
structures.
ARIA roles are more restricted in where you can use them than EPUB's structural semantics. Although there are elements that accept any role, you need to take care to ensure that roles are only used where they will make sense to users of assistive technologies.
The following table maps the semantics from the EPUB Structural Semantics Vocabulary [[epub-ssv-11]] to the corresponding roles in [[wai-aria]] and the [[dpub-aria]] module.
As the use of the epub:type attribute
[[epub-3]] is much more liberal than the role
attribute [[wai-aria]], you cannot interchange types and roles on every HTML element, even when
a role mapping exists. The elements you are allowed to use roles on are identified in the last column of
the table. In addition, refer to the note at the end of the table for the list
of elements that accept any role value.
Refer to the ARIA in HTML [[html-aria]] document for more information about the correct use of ARIA roles, states and properties. It provides the authoritative list of roles that are allowed on an element, and the elements that accept any role.
Only use one digital publishing role per role attribute [[wai-aria]].
If you include a second role, it must be a fallback from [[wai-aria]].
The fallback must not be an Abstract roles
[[wai-aria]]. These roles are never allowed in the role attribute.
Unlike the epub:type attribute
[[epub-3]], the order of roles is important, and only the first recognized role is applied to an
element.
Do not reapply a semantic just because your content has been chunked into separate files.
Although EPUB publications appear as single contiguous documents to users when read, they are typically composed of many individual EPUB content documents. This practice keeps the amount of markup that has to be rendered small to reduce the load time in reading systems (i.e., to minimize the time the user has to wait for a document to appear). It is rare, at least for books, for an EPUB publication to contain only one EPUB content document with all the content in it.
When content is chunked in this way, it often requires restructuring the information to fit within the new file structure. A part, for example, will typically not include all the chapters that belong to it. Instead, the part heading might be separated from each chapter, leaving each chapter in a separate document.
Although visually these restructuring decisions can be hidden from readers, they impact the functionality of assistive technologies. In the case of [[wai-aria]] roles, the result is that only the subset present in the currently-loaded EPUB content document are exposed to users. An assistive technology cannot provide a list of landmarks for the whole publication, as it cannot see outside the current document.
To counteract this destructuring effect, a common bad practice is to re-add or re-identify structures
in the belief that having this information in every document will be helpful to users (e.g., adding
an extra [[html]] section element around a
chapter to indicate it belongs to a part). All this practice does, however, is add repetition that
is not only disruptive when reading but can make the structure of the publication harder to follow.
It is therefore advised not to attempt to rebuild structures in these ways.
For example, consider a book that has five parts and each part contains five chapters. Structurally, each chapter belongs to its part (i.e., is grouped with it), as in the following markup:
<html … >
…
<body>
<section
role="doc-part"
aria-labelledby="p1">
<h1 id="p1">Part 1</h1>
<section
role="doc-chapter"
aria-labelledby="c1">
<h2 id="c1">Chapter 1</h2>
…
</section>
…
</section>
…
</body>
</html>
When more than one instance of a role is included in a document, each has to be uniquely
identified. The aria-labelledby attribute provides the name of each landmark in the
preceding example. The attribute is not required if only one instance is present, so it is
omitted from the following examples.
Since this would lead to a large content file, the part heading is typically split out into its own EPUB content document so that it will appear on its own page:
<html … >
…
<body>
<section
role="doc-part">
<h1 id="p1">Part 1</h1>
</section>
</body>
</html>
Each chapter is then separated into a separate EPUB content document:
<html … >
…
<body>
<section
role="doc-chapter">
<h2>Chapter 1</h2>
…
</section>
</body>
</html>
If another section tag were added around the chapter in the preceding example to
indicate it is in part one (e.g., using the aria-label attribute so the heading is not
visible) users would hear "Part 1 Part 1 Chapter 1" because "Part 1" is also the heading in the
document that precedes the first chapter.
If a landmark role (e.g., doc-chapter, doc-part, doc-index [[dpub-aria]]) does not include a label, assistive technologies
will only announce the generic name of the role in the landmarks.
To include a more descriptive label, use the aria-labelledby attribute [[wai-aria]] to associate the label with the
role.
If a label is not available in the text, you can supply one in an aria-label attribute [[wai-aria]].
If a document contains more than one instance of the same landmark role, each instance needs to be uniquely labelled to allow users to tell them apart.
body elementThe epub:type attribute [[epub-3]] may
be used to inflect sectioning semantics on the [[html]] body element (e.g., to indicate front matter, or to avoid using sectioning
elements), but this practice is both invalid and harmful with ARIA roles.
The body element has the implied role document [[wai-aria]], and you cannot
define any other role on it [[html-aria]]. Changing the role of the body
element can affect the ability to read the content for users of assistive technologies.
Assigning a role to an element overrides its default nature, so use care when applying roles to lists and list items.
Just as [[html]] ol and ul list elements must contain list items,
elements assigned a list role must only contain elements assigned a list item role.
Similarly, a list item must always be enclosed inside of a list.
Due to a change in the [[wai-aria]] roles model, list item roles defined in modules no longer
satisfy the requirement that the list role have
list item children. As a result, use of the doc-biblioentry and doc-endnote roles [[dpub-aria]] is now deprecated.
These roles are now implied on list items within sections that have a doc-bibliography or doc-endnotes role [[dpub-aria]],
respectively.
<section role="doc-bibliography">
<h2>Select Bibliography</h2>
<ol>
<li><-- Implied bibliography entry --></li>
…
</ol>
</section>
Although the doc-cover role [[dpub-aria]] seems
like it should be the same as the cover semantic
[[epub-ssv-11]], it is actually related to the cover-image semantic [[epub-3]] used to identify cover images in the EPUB
package document. The role is used to identify an image that represents the cover.
Do not use this role to identify a section of content containing the cover. Placing
the role on an [[html]] section element,
for example, informs assistive technologies to treat the element like they would an image. In
practical terms, this means that none of its content will be available.
If a section of cover content needs to be identified as a landmark, you can use the aria-label or aria-labelledby attributes [[wai-aria]]
with a section element.
For [[html]] div elements, the
general region role [[wai-aria]] is also needed. For
more information about how to use roles in content, refer to ARIA in HTML [[html-aria]].