EPUB Type to ARIA Role Authoring Guide

21 February 2018

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

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 role="doc-index" aria-labelledby="idx02">
   <h1 id="idx02">Topical Index</h1>

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 role="chapter" aria-label="chapter 2">
   <p>When the forest opened up …</p>

2.4 Do Not Override the body Element

Older guidance for the epub:type attribute has indicated it 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 already 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.

Use of the epub:type attribute on the body element is now also strongly discouraged.

Note: neither epubcheck nor the Ace by DAISY validators report the use of the role attribute on the body element as an error. Manual inspection is required until they are updated.

2.5 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:

   <li role="doc-biblioentry">…</li>

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>