docs: clarify aside complementary role mapping - #44629
Open
ishaanlabs-gg wants to merge 2 commits into
Open
Conversation
ishaanlabs-gg
requested review from
estelle and
hamishwillee
and removed request for
a team
July 2, 2026 20:17
github-actions
Bot
added
Content:HTML
hamishwillee
removed their request for review
July 2, 2026 23:10
Contributor
estelle
reviewed
Jul 8, 2026
|
|
||
| > [!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. |
Member
There was a problem hiding this comment.
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. |
Member
There was a problem hiding this comment.
This changes the sentence's meaning. If you really want to shorten it this way, it would have to be:
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>` either isn't nested in sectioning content or has an accessible name. Developers should always prefer using the correct semantic HTML element over using ARIA. |
But that's really a mouthful.
(Same for below.)
estelle
reviewed
Jul 8, 2026
estelle
left a comment
estelle
left a comment
Member
There was a problem hiding this comment.
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. |
Member
There was a problem hiding this comment.
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. |
Co-authored-by: Estelle Weyl <estelle@openwebdocs.org>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Clarifies that
<aside>maps tocomplementaryonly conditionally when nested in sectioning content.Motivation
This matches the HTML-AAM mapping for
<aside>and addresses reader confusion in the<aside>andcomplementaryrole pages.Additional details
<aside>scoped tobodyormaintocomplementary.<aside>scoped to sectioning content tocomplementaryonly when it has an accessible name; otherwise it maps togeneric.Validation:
git diff --checkRelated issues and pull requests
Fixes #40664