Skip to content

docs: clarify aside complementary role mapping - #44629

Open
ishaanlabs-gg wants to merge 1 commit into
mdn:mainfrom
ishaanlabs-gg:docs-aside-conditional-role
Open

docs: clarify aside complementary role mapping#44629
ishaanlabs-gg wants to merge 1 commit into
mdn:mainfrom
ishaanlabs-gg:docs-aside-conditional-role

Conversation

@ishaanlabs-gg

Copy link
Copy Markdown

Description

Clarifies that <aside> maps to complementary only conditionally when nested in sectioning content.

Motivation

This matches the HTML-AAM mapping for <aside> and addresses reader confusion in the <aside> and complementary role pages.

Additional details

  • HTML-AAM maps <aside> scoped to body or main to complementary.
  • HTML-AAM maps <aside> scoped to sectioning content to complementary only when it has an accessible name; otherwise it maps to generic.

Validation:

  • git diff --check
  • source guard for the new conditional role wording

Related issues and pull requests

Fixes #40664

@ishaanlabs-gg
ishaanlabs-gg requested review from a team as code owners July 2, 2026 20:17
@ishaanlabs-gg
ishaanlabs-gg requested review from estelle and hamishwillee and removed request for a team July 2, 2026 20:17
@github-actions github-actions Bot added Content:HTML Hypertext Markup Language docs Content:Accessibility Accessibility docs size/s [PR only] 6-50 LoC changed labels Jul 2, 2026
@hamishwillee
hamishwillee removed their request for review July 2, 2026 23:10
@github-actions

github-actions Bot commented Jul 8, 2026

Copy link
Copy Markdown
Contributor


> [!NOTE]
> Using the {{HTMLElement('aside')}} element will automatically communicate a section has a role of `complementary`. Developers should always prefer using the correct semantic HTML element over using ARIA.
> Using the {{HTMLElement('aside')}} element will usually communicate a section has a role of `complementary`. When an `<aside>` is nested in sectioning content, it maps to `complementary` only if it has an accessible name. Developers should always prefer using the correct semantic HTML element over using ARIA.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can make it shorter. does this work?

Suggested change
> Using the {{HTMLElement('aside')}} element will usually communicate a section has a role of `complementary`. When an `<aside>` is nested in sectioning content, it maps to `complementary` only if it has an accessible name. Developers should always prefer using the correct semantic HTML element over using ARIA.
> Using the {{HTMLElement('aside')}} element will communicate a section has a role of `complementary` when the `<aside>` has an accessible name and is nested in sectioning content. Developers should always prefer using the correct semantic HTML element over using ARIA.

@estelle estelle left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks. a few suggestions for wording and linking

### Prefer HTML

Using the {{HTMLElement('aside')}} element will automatically communicate that the element has a role of `complementary`. If possible, prefer using the semantic `<aside>` element instead of the `complementary` role.
Using the {{HTMLElement('aside')}} element will usually communicate that the element has a role of `complementary`. If an `<aside>` is nested in sectioning content, it maps to `complementary` only if it has an accessible name. If possible, prefer using the semantic `<aside>` element instead of the `complementary` role.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Using the {{HTMLElement('aside')}} element will usually communicate that the element has a role of `complementary`. If an `<aside>` is nested in sectioning content, it maps to `complementary` only if it has an accessible name. If possible, prefer using the semantic `<aside>` element instead of the `complementary` role.
Using the {{HTMLElement('aside')}} element will communicate a section has a role of `complementary` when the `<aside>` has an accessible name and is nested in sectioning content. If possible, prefer using the semantic `<aside>` element instead of the `complementary` role.

>complementary</a
></code
>
>, or <code>generic</code> when nested in sectioning content without an accessible name

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
>, or <code>generic</code> when nested in sectioning content without an accessible name
>, or <code
><a href="/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/generic_role"
>generic</a
></code
> when nested in sectioning content without an accessible name

## Usage notes

- Do not use the `<aside>` element to tag parenthesized text, as this kind of text is considered part of the main flow.
- The implicit ARIA role of `<aside>` is `complementary` when it is scoped to the {{HTMLElement("body")}} or {{HTMLElement("main")}} element. If it is nested in sectioning content, such as an {{HTMLElement("article")}}, {{HTMLElement("section")}}, or another `<aside>`, it maps to the `complementary` role only if it has an accessible name. Otherwise, it maps to the `generic` role.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- The implicit ARIA role of `<aside>` is `complementary` when it is scoped to the {{HTMLElement("body")}} or {{HTMLElement("main")}} element. If it is nested in sectioning content, such as an {{HTMLElement("article")}}, {{HTMLElement("section")}}, or another `<aside>`, it maps to the `complementary` role only if it has an accessible name. Otherwise, it maps to the `generic` role.
- The implicit ARIA role of `<aside>` is `complementary` when it is scoped to the {{HTMLElement("body")}} or {{HTMLElement("main")}} element. If it is nested in sectioning content, such as an {{HTMLElement("article")}}, {{HTMLElement("section")}}, or another `<aside>`, it maps to the `complementary` role only if it has an accessible name. Otherwise, it maps to the [`generic`](/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/generic_role) role.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Content:Accessibility Accessibility docs Content:HTML Hypertext Markup Language docs size/s [PR only] 6-50 LoC changed

Projects

None yet

Development

Successfully merging this pull request may close these issues.

<aside> implicit role="complementary" is conditional

3 participants