Updated information for an aside element to define a complementary landmark by jongund · Pull Request #3436 · w3c/aria-practices

jongund · 2026-04-16T17:14:07Z

Updated based on the HTML Accessibility API Mappings:

aside element in context of body or main element
aside element with accessible name in context of article, aside, nav or section element
Updated region and form landmark information for consistency for landmarks requiring a label
Removes links to landmark examples

Preview updated Complementary Landmark Pages

WAI Preview Link (Last built on Wed, 30 Sep 2026 03:59:53 GMT).

…ia-label

…erence to match examples

jnurthen

We need to clarify what we state about accessible names for these landmark regions. In my tests title did indeed make these landmarks which matches html-aam.
While we would not want to promote this we should be clear as to what actually happens.

jongund · 2026-04-27T21:42:25Z

@jnurthen
James,
If you have a few minutes could you review step 3 in General Principles?
General Principles Preview

mcking65

@jongud; I reviewed a substantial portion of the changes; can look at the rest later.

This PR goes beyond the aside mapping update. We should discuss scope.

mcking65 · 2026-09-16T06:09:11Z

-                  <p>Use the HTML <code>aside</code> element to define a <code>complementary</code> landmark.</p>
+                  <ul>
+                    <li>The HTML <code>aside</code> element defines a <code>complementary</code> landmark when its context is the <code>body</code> or <code>main</code> element.</li>
+                    <li>An HTML <code>aside</code> element with a label defines a <code>complementary</code> landmark when its context is an <code>article</code>, <code>aside</code>, <code>nav</code> or <code>section</code> element.  A label is defined using <code>aria-labelledby</code> or <code>aria-label</code>.</li>


This isn't accurate. An aside with a label will also be complementary when the context is main or body.

I think you mean to say something more like ...

Aside elements without a label define a complementary landmark only if their context is body or main.

Aside elements with a lable define a complementary landmark when their context is body, main, article, ....

mcking65 · 2026-09-16T06:10:36Z

+                  </ul>

                  <h3>HTML Example: One Complementary Landmark on Page</h3>
                  <p>When only one complementary landmark on a page, a label is optional.</p>


Suggested change

When only one complementary landmark on a page, a label is optional.

When there is only one complementary landmark on a page, a label is optional.

mcking65 · 2026-09-16T06:30:27Z

              <li>Use the <code>search</code> landmark instead of the <code>form</code> landmark when the form is used for search functionality.</li>
              <li>A <code>form</code> landmark should have a label to help users understand the purpose of the form.</li>
-              <li>A label for the <code>form</code> landmark should be identified using <code>aria-labelledby</code> to visible heading element (e.g. an <code>h1-h6</code> element).</li>
+              <li>A label for the <code>form</code> landmark should be identified using <code>aria-labelledby</code> to visible heading element (e.g. an <code>h1-h6</code>) or <code>legend</code> element.</li>


seems like there are some words missing from this sentence; it doesn't quite make sense.

It seems to me that this labeling guidance may be overly prescriptive. Perhaps the guidance that a label is helpful is sufficient. Perhaps we could delete this line?

mcking65 · 2026-09-16T06:34:04Z

-                  <p>If a <code>form</code> element has an accessible name it is considered <code>form</code> landmark.</p>
+                  <ul>
+                    <li>Use a <code>form</code> element with a label to create a <code>form</code> landmark.</li>
+                    <li>Use an <code>aria-labelledby</code> reference to visible heading element (e.g. an <code>h1-h6</code>) or <code>legend</code> element for the label.</li>


Like above, this seems very prescriptive.

mcking65 · 2026-09-16T06:41:43Z

              The use of landmark roles supports keyboard navigation to the structure of a web page for screen reader users and provides targets for author-supplied "skip links" and browser extensions that enhance keyboard navigation.
            </p>
-            <p>This section is intended to assist designers, developers and quality assurance staff in defining and understanding the importance of logical, usable, and accessible layout for assistive technologies
+            <p>This page is intended to assist designers, developers and quality assurance staff in defining and understanding the importance of logical, usable, and accessible layout for assistive technologies


I am not sure how the changes on this page are related to the PR. Is the general idea to better align the content with the practice page? If so, maybe the best thing to do is just delete the page from the examples section with this PR. Then, we only need to modify/review this content in one place.

mcking65 · 2026-09-16T06:47:34Z

            <h2>Design Patterns</h2>
            <ul>
-              <li>A <code>region</code> landmark must have a label.</li>
+              <li>A <code>region</code> landmark must have label using <code>aria-labelledby</code> or <code>aria-label</code>.</li>


Suggested change

<li>A <code>region</code> landmark must have label using <code>aria-labelledby</code> or <code>aria-label</code>.</li>

<li>A <code>region</code> landmark needs to be labeled using <code>aria-labelledby</code> or <code>aria-label</code>.</li>

mcking65 · 2026-09-16T06:51:28Z

              <div class = "tab-content">
                <div  id="tabpanel2" aria-labelledby="tab2" role="tabpanel" class="tab-pane active">
-                  <p>Use the HTML <code>section</code> element to define a <code>region</code> landmark.</p>
+                  <p>Use the HTML <code>section</code> element with a label using <code>aria-labelledby</code> or <code>aria-label</code> to define a <code>region</code> landmark.</p>


Suggested change

Use the HTML <code>section</code> element with a label using <code>aria-labelledby</code> or <code>aria-label</code> to define a <code>region</code> landmark.

to define a <code>region</code> landmark, label an HTML <code>section</code> element with <code>aria-labelledby</code> or <code>aria-label</code>.

mcking65 · 2026-09-16T06:56:12Z

                </div>
                <div id="tabpanel1" aria-labelledby="tab1" role="tabpanel" class="tab-pane">
-                  <p>A <code>role="region"</code> attribute is used to define a <code>region</code> landmark.</p>
+                  <p>Use a <code>role="region"</code> attribute with a label using <code>aria-labelledby</code> or <code>aria-label</code> to define a <code>region</code> landmark.</p>


Suggested change

Use a <code>role="region"</code> attribute with a label using <code>aria-labelledby</code> or <code>aria-label</code> to define a <code>region</code> landmark.

To define a <code>region</code> landmark, set <code>role="region"</code> and specify a label with <code>aria-labelledby</code> or <code>aria-label</code>.

jongund · 2026-09-20T18:53:55Z

@mcking65
I made some updates to include information on AT and other resources, so it is ready for you or other people to review. I am planning to update the images, to and use the APG as the website being navigated. Currently using images form the old example site.

mcking65 · 2026-09-30T04:56:50Z

+            <ul>
+              <li>Use the HTML <code>aside</code> element to define a <code>complementary</code> landmark when its context is the <code>body</code> element.</li>
+              <li>
+                The HTML <code>aside</code> element is <em>not</em> considered a <code>complementary</code> landmark when it is following contexts:


This language is used in several places. It is in a passive voice. "is not considered" is vague. Don't we mean that browsers do not create a landmark? Maybe we should change to something like the following ...

Suggested change

The HTML <code>aside</code> element is not considered a <code>complementary</code> landmark when it is following contexts:

Browsers do not create a complementary landmark when an HTML <code>aside</code> element is in the following contexts:

updated how a aside element defines a complementary landmark

43977ae

w3cgruntbot mentioned this pull request Apr 16, 2026

apg/update-aside-landmarks generated by aria-practices w3c/wai-aria-practices#460

Draft

jongund added 2 commits April 16, 2026 14:57

edits

a177925

restored file

a11e06d

jongund changed the title ~~updated how a aside element defines a complementary landmark~~ Updated information for an aside element to define a complementary landmark Apr 16, 2026

jongund added 5 commits April 17, 2026 14:42

edited changes

b4660c4

improved consistency of labeling language with aria-labelledby and ar…

8ebfd87

…ia-label

updated form for consistency with other landmarks

ca79513

harmonizing form landmark guidance

6c0b991

update form landmark to include using legend as a aria-labelledby ref…

7262155

…erence to match examples

jongund requested review from jnurthen and mcking65 April 18, 2026 17:51

jongund added 6 commits April 19, 2026 12:17

update AT examples for SkipTo.js

4690a06

updated skipto.js example

f35d4be

added link to SkipTo.js documentation

ed0cfac

added link to SkipTo.js documentation

9924b0f

updated link

d5c7937

updated screenshots to use figure and figcaption

2617d02

jnurthen requested changes Apr 22, 2026

View reviewed changes

jongund added 6 commits April 24, 2026 16:49

Made edits based on James Nurlen's feedback

69c4aca

Made edits based on James Nurlen's feedback

1199459

Made edits based on James Nurlen's feedback

364e277

Made edits based on James Nurlen's feedback

55e3dd4

broke up a listitem

cf1d2ff

added legend as a potential label for a form region

4171cfc

jongund requested a review from jnurthen April 27, 2026 21:42

jongund and others added 2 commits September 15, 2026 15:25

removed example links

b6a1f55

Merge remote-tracking branch 'origin/main' into update-aside-landmarks

f737186

mcking65 reviewed Sep 16, 2026

View reviewed changes

jongund added 17 commits September 19, 2026 13:02

update aside element information

d5b906a

update aside element information

344db23

added at and resource sections

4710dce

added ids

9877b58

editorial edit

d08bc4a

fixed id issue

99a5ca5

add css for figures

ea9eb48

updated css for figures

bcfa429

updated css for figures

92a8940

updated css for figures

3c46f97

updated css for figures

6df73b8

updated css for figures

e848423

updated css for figures

d9f502f

updated css for figures

dc44274

fixed bugs in complementary landmark section

c9747bc

updated to use 'contexts' instead of descendants

1eeabc0

fixed spelling mistake

b32212f

jongund and others added 10 commits September 20, 2026 13:59

added example resource

a0088fc

updated 2 images for landmarks

7b4849c

restored image

55e7bea

updated voice over screen shot

880911e

updated jaws screen shot

fc9ab14

updated nvda screen shot

c3ee2cf

updated orca screen shot

a17963f

Editorial clarification to labeling guidance

2fa4f34

fix grammar error

5c0a662

Replace '"' inside of code elements with quote characters.

8d60fbf

mcking65 requested changes Sep 30, 2026

View reviewed changes

mcking65 added this to the 2026 November publication milestone Sep 30, 2026

	<p>When only one complementary landmark on a page, a label is optional.</p>
	<p>When there is only one complementary landmark on a page, a label is optional.</p>

	<li>A <code>region</code> landmark must have label using <code>aria-labelledby</code> or <code>aria-label</code>.</li>
	<li>A <code>region</code> landmark needs to be labeled using <code>aria-labelledby</code> or <code>aria-label</code>.</li>

	<p>Use the HTML <code>section</code> element with a label using <code>aria-labelledby</code> or <code>aria-label</code> to define a <code>region</code> landmark.</p>
	<p>to define a <code>region</code> landmark, label an HTML <code>section</code> element with <code>aria-labelledby</code> or <code>aria-label</code>.</p>

	<p>Use a <code>role="region"</code> attribute with a label using <code>aria-labelledby</code> or <code>aria-label</code> to define a <code>region</code> landmark.</p>
	<p>To define a <code>region</code> landmark, set <code>role="region"</code> and specify a label with <code>aria-labelledby</code> or <code>aria-label</code>.</p>

	The HTML <code>aside</code> element is <em>not</em> considered a <code>complementary</code> landmark when it is following contexts:
	Browsers do not create a complementary landmark when an HTML <code>aside</code> element is in the following contexts:

Conversation

jongund commented Apr 16, 2026 • edited by w3cgruntbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jnurthen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jongund commented Apr 27, 2026

Uh oh!

mcking65 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jongund commented Sep 20, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jongund commented Apr 16, 2026 •

edited by w3cgruntbot

Loading