EPUB Type to ARIA Role Authoring Guide

6 July 2016

Document history

1. Introduction

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.

2. Guidelines

2.1 Do Not Overload Roles

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.

2.2 Avoid Unnecessary Repetition

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.

2.3 Supply Labels for Identical Roles

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 epub:type).

Use the 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 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>

2.4 List Roles are for Lists

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>