Document Structure Roles — Article, Section, Heading and More

In this tutorial, you will learn about Document Structure Roles. We cover key concepts, practical examples, and best practices to help you master this topic.

ARIA document structure roles like article, section, heading, list, and table describe content organization, helping screen readers convey document structure to users.

In this tutorial, you'll learn how to use document structure roles effectively in your ARIA implementations.

What You'll Learn

By the end of this lesson, you'll understand the common document structure roles, their native HTML equivalents, and when to use ARIA roles versus native elements.

Why It Matters

Document structure roles help screen reader users understand the organization of content. Headings, lists, and tables convey meaning beyond text alone.

Real-World Use

Doda Browser's reader mode relies on proper document structure to render articles with correct heading hierarchy, list formatting, and table layout.

Document Structure Hierarchy

flowchart TD
  A[Document Structure] --> B[article]
  A --> C[section]
  A --> D[heading]
  A --> E[list / listitem]
  A --> F[table / grid]
  A --> G[figure / figcaption]
  A --> H[definition / term]
  B --> I[Self-contained composition]
  C --> J[Thematic grouping]
  D --> K[aria-level for nesting]

Common Document Structure Roles

<!-- article: self-contained composition -->
<div role="article">
  <h2 role="heading" aria-level="2">How ARIA Works</h2>
  <p>ARIA modifies the accessibility tree...</p>
</div>

<!-- section: thematic grouping with label -->
<div role="region" aria-labelledby="faq-heading">
  <h2 id="faq-heading">Frequently Asked Questions</h2>
</div>

<!-- heading with explicit level -->
<h3 role="heading" aria-level="3">Advanced Topics</h3>

When ARIA Document Structure Is Necessary

Use ARIA document structure roles when you cannot use native HTML:

<!-- When using a generic element as a heading -->
<span role="heading" aria-level="2">Section Title</span>

<!-- When the native element semantics must be overridden -->
<!-- (rare, typically avoid this) -->
<table role="grid" aria-label="Scan results">
  <tr>
    <th role="columnheader">File</th>
    <th role="columnheader">Status</th>
  </tr>
</table>

Native HTML vs ARIA

Common Mistakes

• Adding role="heading" to native heading elements: Redundant and unnecessary.
• Using role="article" on every content block: Articles should be self-contained, independently distributable content.
• Omitting aria-level on heading roles: Without the level, the screen reader cannot convey heading hierarchy.
• Using role="list" on non-list content: If the content is not semantically a list, do not use the role.
• Confusing role="section" with role="region": Both are document structure roles, but region is a landmark when named.

Practice and Challenge

1. What is the purpose of document structure roles? To describe the organization of content to assistive technologies.

2. What required attribute must a heading role have? aria-level.

3. What is the native HTML equivalent of role="list"? The <ul> or <ol> element.

4. Why should you prefer native HTML over ARIA for document structure? Native elements have built-in browser support, keyboard handling, and implicit ARIA semantics.

5. Challenge: Convert a div-based article layout to use proper document structure roles where native HTML cannot be used.

FAQ

Mini Project

Take an article page and ensure proper heading hierarchy. Use role="heading" with aria-level only where needed, and confirm the hierarchy passes a screen reader test.

What's Next

Continue to Widget Roles to learn about button, link, checkbox, radio, and tab roles.