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
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
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.
Only use one digital publishing role per attribute:
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.
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.
Although landmarks will be announced by their role name, if a document includes the same role multiple times
(e.g., multiple chapters, appendixes or indexes in one file), it is best practice to include a label to
differentiate them. A label provides context when deciding which to navigate to (similar capabilities are
not available for
aria-labelledby attribute to associate a label with the role.
<section role="index" aria-labelledby="idx01"> <h1 id="idx01">Name Index</h1> … </section> <section role="index" aria-labelledby="idx02"> <h1 id="idx02">Topical Index</h1> … </section>
If no label is available, one can be supplied in an
<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>
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>