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 biggest of these differences is in their primary applications. The epub:type
attribute
has evolved to aid publisher workflows. It has limited use enabling reading system behaviors outside of
some core functionality of EPUB (identifying navigation elements and enhancing media overlay documents).
Although it was hoped the attribute would also expose information to assistive technologies, in practice
it does not.
The primary purpose of the role
attribute, on the other hand, is to expose information to
assistive technologies. It is not to facilitate user agent behaviors.
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 rendering for assistive technology users.
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.
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.
For example, ensure that the doc-part
role [[dpub-aria]] 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
[[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]].