From 8907015cf7f1cb3cece00fd69ee5f5439a04c1b9 Mon Sep 17 00:00:00 2001
From: Ishaan Kapur <64529428+ishaanlabs-gg@users.noreply.github.com>
Date: Fri, 3 Jul 2026 01:46:23 +0530
Subject: [PATCH] docs: clarify aside complementary role mapping

---
 .../aria/reference/roles/complementary_role/index.md          | 4 ++--
 files/en-us/web/html/reference/elements/aside/index.md        | 3 ++-
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/files/en-us/web/accessibility/aria/reference/roles/complementary_role/index.md b/files/en-us/web/accessibility/aria/reference/roles/complementary_role/index.md
index f36dd885ae51cd7..fac0846eab21659 100644
--- a/files/en-us/web/accessibility/aria/reference/roles/complementary_role/index.md
+++ b/files/en-us/web/accessibility/aria/reference/roles/complementary_role/index.md
@@ -25,7 +25,7 @@ This is a sidebar containing links to project sponsors.
 The `complementary` role is [a landmark](/en-US/docs/Web/Accessibility/ARIA/Guides/Techniques#landmark_roles) role. Landmarks can be used by assistive technology to quickly identify and navigate to large sections of the document. Content listed within a container with the `complementary` landmark role should make sense if separated from the main content of the document.
 
 > [!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.
 
 ## Examples
 
@@ -54,7 +54,7 @@ The `complementary` role is [a landmark](/en-US/docs/Web/Accessibility/ARIA/Guid
 
 ### 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.
 
 ### Labeling landmarks
 
diff --git a/files/en-us/web/html/reference/elements/aside/index.md b/files/en-us/web/html/reference/elements/aside/index.md
index b93b5f92f1f299c..0371d80e5aa333b 100644
--- a/files/en-us/web/html/reference/elements/aside/index.md
+++ b/files/en-us/web/html/reference/elements/aside/index.md
@@ -52,6 +52,7 @@ This element only includes the [global attributes](/en-US/docs/Web/HTML/Referenc
 ## 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.
 
 ## Examples
 
@@ -128,7 +129,7 @@ This example uses `<aside>` to mark up a paragraph in an article. The paragraph
           ><a href="/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/complementary_role"
             >complementary</a
           ></code
-        >
+        >, or <code>generic</code> when nested in sectioning content without an accessible name
       </td>
     </tr>
     <tr>