EPUB Type to ARIA Role Authoring Guide
22 November 2019
Document history
22 November 2019
It is important to understand the differences between the epub:type attribute and the ARIA
role attribute to ensure that they are properly applied for
their intended purposes and audiences.
Arguably the biggest difference is in their primary applications. The epub:type attribute has evolved to facilitate reading system behaviors and to aid publisher
workflows. Although it could be used to expose information to assistive technologies (AT),
in practice it is not. The primary purpose of the role attribute, on the
other hand, is to expose information to AT. Although it
could be used to facilitate user agent behaviors, in practice it is not.
The result of these differences 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 HTML rendering for AT users.
This guide is not intended as a comprehensive overview of ARIA roles. It only addresses key authoring differences to be aware of when using one or both attributes in EPUB Content Documents.
ARIA roles are more restricted in where they can be used than EPUB's structural semantics. Although there are a number of elements that accept any role, care needs to be taken to ensure that roles are only used where they will make sense to users of assistive technologies.
The following mapping table identifies the elements that each DPUB-ARIA role can be used with.
The following table maps the semantics from the EPUB Structural Semantics Vocabulary to the corresponding roles in ARIA and the DPUB-ARIA module.
As the use of the epub:type attribute is much more liberal than the ARIA
role attribute, not every semantic can be used on every HTML element, even if
it has a mapping. Specific elements that roles can be used 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.
See also the ARIA in HTML document for more information about the correct use of ARIA roles, states and properties.
Only use one digital publishing role per attribute:
<section role="doc-chapter">
If you include a second role, it has to be a fallback from ARIA 1.1:
<section role="doc-chapter region">
Note that the fallback must not be one of the ARIA 1.1 Abstract roles. These are never allowed in the role attribute.
Unlike the epub:type attribute, 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.
For example, ensure that the doc-part role is only applied to the section
that contains the heading for the part. Do not reapply the part role for each chapter that belongs
to the part, as it will be announced to users of assistive technologies each time it occurs, causing
confusion.
If a landmark role (e.g., doc-chapter, doc-part, doc-index)
does not include a label, assistive technologies will not include it in the list of landmarks. A
label provides context when deciding which landmark to navigate to (similar capabilities are not
available for epub:type).
Use the aria-labelledby attribute to associate a label with the role.
<section role="doc-index" aria-labelledby="idx01"> <h1 id="idx01">Name Index</h1> … </section> <section role="doc-index" aria-labelledby="idx02"> <h1 id="idx02">Topical Index</h1> … </section>
If a label is not available in the text, one can be supplied in an aria-label attribute.
<section role="chapter" aria-label="chapter 1"> <p>Once upon a time …</p> … </section> <section role="chapter" aria-label="chapter 2"> <p>When the forest opened up …</p> … </section>
body ElementThe epub:type attribute 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, and no other roles can be defined on the element.
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/ul 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.
For example, the doc-biblioentry role inherits from listitem. As a result, it has to be used inside of a list:
<ul> <li role="doc-biblioentry">…</li> … </ul>
or else a list role needs to be applied to an element that encloses all the note:
<div role="list"> <p role="doc-biblioentry">…</li> … </div>
Although the doc-cover role from the DPUB-ARIA module seems like it should be the same
as the cover semantic from the EPUB Structural Semantics Vocabulary, it is actually
related to the cover-image semantic used to identify cover images in the EPUB package
document. The role is used to identify an image that represents the cover.
<img role="doc-cover"
src="cover.jpg"
alt="..."/>
This role is not used to identify a section of content containing the cover. Placing
the role on a section, 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, the aria-label
or aria-labelledby attributes can be used with the `section` element:
<section aria-label="Cover: As I Lay Dying. William Faulkner."< … </section>
(For `div` elements, the general `region` role is also needed. For more information about how to use roles in content, refer to ARIA in HTML.)