1. Use Roles on Allowed Elements

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.

2. 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.

3. 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.

4. 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>

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

5. Do Not Override the body Element

The 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.

6. 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>

7. Cover Role is for Images

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.)