Clarify Accessibility Parent-Child Relationships for menu, group, and menuitem #2483

giacomo-petri · 2025-03-21T14:55:02Z

The current specifications for menu and menubar contradict those for menuitem, menuitemcheckbox, and menuitemradio.

Specifically, the following structure is allowed under the menu role but not when considering the menuitem role:

<div role="menu">
	<div role="group">
		<span role="menuitem">Item 1</span>
		<div role="group">
			<span role="menuitem">Item 2</span>
			<span role="menuitem">Item 3</span>
		</div>
	</div>
</div>

This PR clarifies that this structure is indeed allowed.

Additionally, it explicitly clarifies in a note that the following example, where a group contains a button and an input as accessibility children, is not permitted. This prevents ambiguity by making it clear that having at least one menuitem as an accessibility child of the group does not justify including other unrelated elements, which was not clearly stated.

<div role="menu">
	<div role="group">
		<span role="menuitem">Item 1</span>
		<div role="group">
			<span role="menuitem">Item 2</span>
			<span role="menuitem">Item 3</span>
		</div>
		<button>Test</button>
		<input type="text aria-label="Test">
	</div>
</div>

This update refines the specifications for menu, menubar, menuitem, menuitemcheckbox, and menuitemradio roles consistently.

Test, Documentation and Implementation tracking

Once this PR has been reviewed and has consensus from the working group, tests should be written and issues should be opened on browsers. Add N/A and check when not applicable.

"author MUST" tests:
"user agent MUST" tests:
Browser implementations (link to issue or commit):
- WebKit:
- Gecko:
- Blink:
Does this need AT implementations?
Related APG Issue/PR:
MDN Issue/PR:

Preview | Diff

netlify · 2025-03-21T14:55:21Z

✅ Deploy Preview for wai-aria ready!

Name	Link
🔨 Latest commit	`7048eb6`
🔍 Latest deploy log	https://app.netlify.com/projects/wai-aria/deploys/6894db20b48ac70008cbe264
😎 Deploy Preview	https://deploy-preview-2483--wai-aria.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

index.html

Co-authored-by: Peter Krautzberger <[email protected]>

suggestions applied

index.html

fix typo

spectranaut · 2025-03-27T17:26:52Z

@np-at to review as well!

scottaohara · 2025-03-27T17:28:11Z

actually, taking myself off as a reviewer since we have so many others.

giacomo-petri · 2025-04-03T09:15:27Z

@pkra, I just realized the same issue affects tree/group/treeitem structures. Should we include this change in this PR or create a separate one?

pkra · 2025-04-03T10:05:05Z

@giacomo-petri sounds good. Hopefully it's simpler since #2094 prevents group as child of tree.

pkra · 2025-06-14T11:03:33Z

index.html

+              However, when a <code>group</code> is used in the context of a <rref>listbox</rref>, for example, authors MUST limit its children to <rref>option</rref> elements. Similarly, when a
+              <code>group</code> is used in the context of a <rref>menu</rref> or <rref>menubar</rref>, authors MUST limit its <a>accessibility descendants</a> to <rref>menuitem</rref>,
+              <rref>menuitemcheckbox</rref>, <rref>menuitemradio</rref> and <rref>separator</rref>, with only elements of role <rref>generic</rref>, <rref>group</rref>, and
+              <rref>none</rref> intervening. Therefore, proper handling of <code>group</code> by authors and assistive technologies is determined by the context in which it is provided.


Coming back to this I'm not sure about this addition. "MUST limit its accessibility descendants" seems too strong - groups can have other descendants because, e.g., menuitem does not have any restrictions on its descendants.

IIRC we're really after "donut scoping". If that's the case I'm wondering if this addition is necessary. Does donut scoping not follow from the new requirements on menuitem etc now that we have accessibility ancestor?

If that's the case, then perhaps a note is more appropriate, describing this effect. (There could be a follow up issue to do the same with listbox and option.)

Ah, I think what I wrote is not right either. Maybe children instead of descendants? E.g., "if a group has an accessibility ancestor of role menu, then allowed children are ...".

In the working group meeting, I suggested using "accessibility children", but now I realize that can't quite be used the way I suggested, so I took a try at re-writing this whole section, which doesn't solve Peter's problem of making it "less wordy" but it does make it more clear, at least to me:

A set of user interface objects that is not intended to be included in a page summary or table of contents by assistive technologies.

Contrast with region, which is a grouping of user interface objects that will be included in a page summary or table of contents. If a section is significant enough to warrant inclusion in the web page's table of contents, the author SHOULD assign it a role of region or a standard landmark role.

Authors SHOULD use a group to form a logical collection of items in a widget, such as children in a tree widget forming a collection of siblings in a hierarchy. Authors MAY nest group elements.

The proper handling of group by authors and assistive technologies is determined by the context in which it is provided. For example, when a group is the accessibility child of a menu or menubar, authors MAY nest additional groups, however, the accessibility children of the innermost group MUST be limited to menuitems, menuitemcheckboxs, menuitemradios and separators. Whereas when a group is the accessibility child of a listbox, authors MUST NOT nest groups and MUST limit the groups accessibility children to option elements.

I don't think "accessibility descendant" quite works here, because we never want to say something about all descendants.

Applied @spectranaut suggestion

pkra · 2025-06-14T11:05:37Z

index.html

@@ -6200,6 +6202,10 @@ <h4>Plain HTML or Polyfill DOM Result of the MathML Quadratic Formula</h4>
            </p>
            <p>To be <a>keyboard accessible</a>, authors SHOULD manage focus of descendants for all instances of this <a>role</a>, as described in <a href="#managingfocus">Managing Focus</a>.</p>
            <p>Elements with the role <code>menu</code> have an implicit <pref>aria-orientation</pref> value of <code>vertical</code>.</p>
+            <p class="note">
+              The <code>menu</code> <a>role</a> allows only role <rref>menuitem</rref>, <rref>menuitemcheckbox</rref>, <rref>menuitemradio</rref>, and <rref>separator</rref> as
+              <a>accessibility descendants</a>, with only elements of role <rref>generic</rref>, <rref>group</rref>, and <rref>none</rref> intervening.


As above, I think menu can have other descendants (below e.g. menuitem). In which case this should be rephrased to describe the effects of donut scoping.

Reading this I think I finally understand your concern @pkra. This is hard to write.

But since it's a note, maybe it can be more informal, here is a suggestion:

Let's call the elements that are contained in a menu and have roles menuitems, menuitemcheckboxes, menuitemradios or separator the "items" of that menu. These items can be arranged for logical purposes with groups, or styling purposes with generics. However, no semantically meaningful elements other than group are allowed between the individual items of the menu and the element with role menu. This is similar to the definition and constraints of "accessibility children", however, along with allowing intervening elements of role generic or none, we allow intervening elements of role group.

Also, I realize, the "allowed accessibility children" isn't clear enough. "Allowed accessibility children" only tells you what the next accessibility child should be. So if we add to that list "group with the accessibility child of group", then it's not clear that the child of THAT group MUST be either a group or (....). Is it possible to say this without being recursive?

@pkra, @spectranaut

@spectranaut, I think your suggestion of replacing the term "accessibility descendants" with "accessibility children" reflects the intended requirement. The "first level of accessibility children" of a menu must consist only of menuitem, menuitemcheckbox, menuitemradio, or separator, and generic, group, or none are permitted as structural elements between these roles and the menu (but they do not count as "first-level accessibility children". While this is always true for generic and none, it's not inherently true for group, so we may want to add a note to clarify that explicitly).

To make this clearer, we may also add a note stating that other roles may appear as descendants of a menu, but they must not be accessibility children of the menu itself. We can refer to @spectranaut’s example involving the group role in this comment with other examples to illustrate that point in a note.

Did you want to iterate on the note to add your suggestions, then? Would be nice to get this landed soon :)

@spectranaut @pkra,
please take another look to see if it works now.

looks good to me!

pkra · 2025-06-14T11:06:21Z

index.html

@@ -6304,6 +6312,10 @@ <h4>Plain HTML or Polyfill DOM Result of the MathML Quadratic Formula</h4>
            </p>
            <p>To be <a>keyboard accessible</a>, authors SHOULD manage focus of descendants for all instances of this <a>role</a>, as described in <a href="#managingfocus">Managing Focus</a>.</p>
            <p>Elements with the role <code>menubar</code> have an implicit <pref>aria-orientation</pref> value of <code>horizontal</code>.</p>
+            <p class="note">
+              The <code>menubar</code> <a>role</a> allows only role <rref>menuitem</rref>, <rref>menuitemcheckbox</rref>, <rref>menuitemradio</rref>, and <rref>separator</rref> as
+              <a>accessibility descendants</a>, with only elements of role <rref>generic</rref>, <rref>group</rref>, and <rref>none</rref> intervening.


Sames as above for menu.

updated together with menu

pkra · 2025-06-14T11:15:07Z

index.html

                    <li><rref>group</rref> with <a>accessibility child</a> <rref>menuitem</rref></li>
                    <li><rref>group</rref> with <a>accessibility child</a> <rref>menuitemradio</rref></li>
                    <li><rref>group</rref> with <a>accessibility child</a> <rref>menuitemcheckbox</rref></li>
+                    <li><rref>group</rref> with <a>accessibility child</a> <rref>separator</rref></li>


I think we should be able to reduce this to just group's again.

@pkra

what about phrasing it as
"group as intervening role"
?

My concern is that if we just list "group" without clarification, some authors, especially those who skip over the note, might incorrectly assume that this kind of structure is valid:

<div role="menu"> <div role="group"> <a href="...">...</a> <input type="checkbox" ...> </div> </div>

Since WCAG notes are non-normative, there's a real chance the note will be overlooked entirely. By explicitly mentioning "intervening role," we at least raise a red flag and prompt them to think twice (and read the note).

I like that idea!

spectranaut · 2025-07-03T17:52:39Z

Discussed in today's meeting: https://www.w3.org/2025/07/03-aria-minutes.html#3a9f

spectranaut

Thanks for this effort @giacomo-petri! I've contributed some ideas...

spectranaut · 2025-07-03T18:18:00Z

index.html

+              However, when a <code>group</code> is used in the context of a <rref>listbox</rref>, for example, authors MUST limit its children to <rref>option</rref> elements. Similarly, when a
+              <code>group</code> is used in the context of a <rref>menu</rref> or <rref>menubar</rref>, authors MUST limit its <a>accessibility descendants</a> to <rref>menuitem</rref>,
+              <rref>menuitemcheckbox</rref>, <rref>menuitemradio</rref> and <rref>separator</rref>, with only elements of role <rref>generic</rref>, <rref>group</rref>, and
+              <rref>none</rref> intervening. Therefore, proper handling of <code>group</code> by authors and assistive technologies is determined by the context in which it is provided.


In the working group meeting, I suggested using "accessibility children", but now I realize that can't quite be used the way I suggested, so I took a try at re-writing this whole section, which doesn't solve Peter's problem of making it "less wordy" but it does make it more clear, at least to me:

A set of user interface objects that is not intended to be included in a page summary or table of contents by assistive technologies.

Contrast with region, which is a grouping of user interface objects that will be included in a page summary or table of contents. If a section is significant enough to warrant inclusion in the web page's table of contents, the author SHOULD assign it a role of region or a standard landmark role.

Authors SHOULD use a group to form a logical collection of items in a widget, such as children in a tree widget forming a collection of siblings in a hierarchy. Authors MAY nest group elements.

The proper handling of group by authors and assistive technologies is determined by the context in which it is provided. For example, when a group is the accessibility child of a menu or menubar, authors MAY nest additional groups, however, the accessibility children of the innermost group MUST be limited to menuitems, menuitemcheckboxs, menuitemradios and separators. Whereas when a group is the accessibility child of a listbox, authors MUST NOT nest groups and MUST limit the groups accessibility children to option elements.

I don't think "accessibility descendant" quite works here, because we never want to say something about all descendants.

spectranaut · 2025-07-03T18:35:07Z

index.html

@@ -6200,6 +6202,10 @@ <h4>Plain HTML or Polyfill DOM Result of the MathML Quadratic Formula</h4>
            </p>
            <p>To be <a>keyboard accessible</a>, authors SHOULD manage focus of descendants for all instances of this <a>role</a>, as described in <a href="#managingfocus">Managing Focus</a>.</p>
            <p>Elements with the role <code>menu</code> have an implicit <pref>aria-orientation</pref> value of <code>vertical</code>.</p>
+            <p class="note">
+              The <code>menu</code> <a>role</a> allows only role <rref>menuitem</rref>, <rref>menuitemcheckbox</rref>, <rref>menuitemradio</rref>, and <rref>separator</rref> as
+              <a>accessibility descendants</a>, with only elements of role <rref>generic</rref>, <rref>group</rref>, and <rref>none</rref> intervening.


Reading this I think I finally understand your concern @pkra. This is hard to write.

But since it's a note, maybe it can be more informal, here is a suggestion:

Let's call the elements that are contained in a menu and have roles menuitems, menuitemcheckboxes, menuitemradios or separator the "items" of that menu. These items can be arranged for logical purposes with groups, or styling purposes with generics. However, no semantically meaningful elements other than group are allowed between the individual items of the menu and the element with role menu. This is similar to the definition and constraints of "accessibility children", however, along with allowing intervening elements of role generic or none, we allow intervening elements of role group.

Also, I realize, the "allowed accessibility children" isn't clear enough. "Allowed accessibility children" only tells you what the next accessibility child should be. So if we add to that list "group with the accessibility child of group", then it's not clear that the child of THAT group MUST be either a group or (....). Is it possible to say this without being recursive?

spectranaut

One minor thing!

index.html

Co-authored-by: Valerie Young <[email protected]>

spectranaut

I approve, with removing the extra rows for group and just put "group as intervening role" -- thought I wonder now if we should define "intervening" somewhere...

giacomo-petri · 2025-08-07T16:55:37Z

@spectranaut, I agree that we likely need a definition for "intervening," but it's already used 7 times in the specs, though always referring to generic or none. That said, I think the current wording for group doesn't add complexity and still aligns with the intent of the others, even if the context and outcome differ. Should we consider trying adding that definition (since it also impacts generic intervening) in a separate PR?

pkra · 2025-08-27T08:05:25Z

index.html

            <p>
-              Authors MAY nest <code>group</code> elements. If a section is significant enough to warrant inclusion in the web page's table of contents, the author SHOULD assign it a <a>role</a> of
-              <rref>region</rref> or a <a href="#landmark_roles">standard landmark role</a>.
+              Authors SHOULD use a <code>group</code> to form a logical collection of items in a <a>widget</a>, such as children in a tree widget forming a collection of siblings in a hierarchy.


Suggested change

Authors SHOULD use a <code>group</code> to form a logical collection of items in a <a>widget</a>, such as children in a tree widget forming a collection of siblings in a hierarchy.

Authors SHOULD use a <code>group</code> to form a logical collection of items in a <a>widget</a>, such as children in a treeitem forming a collection of siblings in a hierarchy.

group is not allowed in tree, only treeitem (I realize this was not a change in this PR).

pkra · 2025-08-27T08:20:12Z

index.html

+	    </p>
+	    <p>
+	      The proper handling of <code>group</code> by authors and assistive technologies is determined by the context in which it is provided. For example, when a <code>group</code> is the 
+	      <a>accessibility child</a> of a <code>menu</code> or <code>menubar</code>, authors MAY nest additional <code>group</code> elements. However, the <a>accessibility children</a> of the 


I think the new content (However, ...) is good addition but it should be a note and not using normative language. As my suggestion for tree widgets shows, it's easy for such language to be out of date. I think normative statements on roles should be limited to their own sections.

pkra · 2025-08-27T08:21:41Z

index.html

+	      <code>menu</code>. This allows authors to organize menus logically using groups or to style them using generic containers. However, aside from <rref>group</rref>, no other semantically 
+	      meaningful roles may intervene between the allowed child roles and the <code>menu</code>. This structure mirrors the concept of "accessibility children", but explicitly permits 
+	      <rref>group</rref> in addition to <rref>generic</rref> and <rref>none</rref> as intervening elements.
+            </p>


I admit I'm still unhappy with this.

I don't like how the second sentence contradicts the first sentence's "allows only roles". I don't like "structural" in "structural element" nor how generics are mentioned (which can always be added after all so here a reader might wonder what is special about mentioning them again).

I also do not like the duplication of this language in menubar; it will invariably fall out of sync.

I realize we cannot get to something as tight as we have for trees, but I think we should work on this concept rather than adding more complicated language like this throughout the spec.

Still, I don't want to keep blocking this.

pkra · 2025-08-27T08:22:10Z

index.html

-                    <li><rref>group</rref> with <a>accessibility child</a> <rref>menuitem</rref></li>
-                    <li><rref>group</rref> with <a>accessibility child</a> <rref>menuitemradio</rref></li>
-                    <li><rref>group</rref> with <a>accessibility child</a> <rref>menuitemcheckbox</rref></li>
+                    <li><rref>group</rref> as intervening role</li>


I second the idea of adding a definition (later).

pkra · 2025-08-27T08:26:05Z

I'm not sure why my last review is marked "requesting changes" - I'm guessing the suggested change is to blame.

I don't oppose merging this as is, despite remaining somewhat unhappy with the language.

Update index.html

269e806

giacomo-petri added the spec:aria label Mar 21, 2025

chore: prettier

e980d4b

pkra added the clarification clarifying or correcting language that is either confusing, misleading or under-specified label Mar 21, 2025

pkra reviewed Mar 21, 2025

View reviewed changes

index.html Outdated Show resolved Hide resolved

pkra reviewed Mar 21, 2025

View reviewed changes

index.html Outdated Show resolved Hide resolved

pkra previously requested changes Mar 21, 2025

View reviewed changes

index.html Outdated Show resolved Hide resolved

index.html Outdated Show resolved Hide resolved

index.html Outdated Show resolved Hide resolved

index.html Outdated Show resolved Hide resolved

giacomo-petri and others added 4 commits March 21, 2025 20:53

Update index.html

6ff9aad

Co-authored-by: Peter Krautzberger <[email protected]>

Update index.html

6678aef

Co-authored-by: Peter Krautzberger <[email protected]>

Update index.html

c5ee99a

chore: prettier

0237660

giacomo-petri requested a review from pkra March 21, 2025 20:14

giacomo-petri and others added 4 commits March 25, 2025 13:06

Update index.html

6e9a04b

chore: prettier

79f6da9

Update index.html

db5ed08

chore: prettier

d14eff8

giacomo-petri commented Mar 25, 2025

View reviewed changes

index.html Outdated Show resolved Hide resolved

Update index.html

cecd778

fix typo

spectranaut requested review from MelSumner, scottaohara and mcking65 March 27, 2025 17:25

scottaohara removed their request for review March 27, 2025 17:27

pkra mentioned this pull request Apr 8, 2025

add term "accessibility ancestor" #2016

Open

spectranaut moved this to All PRS in ARIA Normative PR Tracking Jun 13, 2025

spectranaut added this to ARIA Normative PR Tracking Jun 13, 2025

spectranaut moved this from All PRS to Needs Consensus/Review in ARIA Normative PR Tracking Jun 13, 2025

pkra requested changes Jun 14, 2025

View reviewed changes

pkra added the Agenda label Jun 14, 2025

spectranaut reviewed Jul 3, 2025

View reviewed changes

jnurthen removed the Agenda label Jul 15, 2025

edit to group def, implementing Valerie's suggetion

2b66bd0

spectranaut self-requested a review August 4, 2025 15:47

spectranaut requested changes Aug 4, 2025

View reviewed changes

index.html Outdated Show resolved Hide resolved

giacomo-petri and others added 2 commits August 5, 2025 08:33

Update index.html

e155a27

Co-authored-by: Valerie Young <[email protected]>

updated menu and menubar notes

35bfe75

spectranaut approved these changes Aug 7, 2025

View reviewed changes

replaced group with specific acc desc with group as intervening

7048eb6

spectranaut requested a review from pkra August 26, 2025 20:25

pkra reviewed Aug 27, 2025

View reviewed changes

pkra mentioned this pull request Aug 27, 2025

Define "intervening element" #2612

Open

	Authors SHOULD use a <code>group</code> to form a logical collection of items in a <a>widget</a>, such as children in a tree widget forming a collection of siblings in a hierarchy.
	Authors SHOULD use a <code>group</code> to form a logical collection of items in a <a>widget</a>, such as children in a treeitem forming a collection of siblings in a hierarchy.

Clarify Accessibility Parent-Child Relationships for menu, group, and menuitem #2483

Are you sure you want to change the base?

Clarify Accessibility Parent-Child Relationships for menu, group, and menuitem #2483

Uh oh!

Conversation

giacomo-petri commented Mar 21, 2025 • edited by pr-preview bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test, Documentation and Implementation tracking

Uh oh!

netlify bot commented Mar 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for wai-aria ready!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

spectranaut commented Mar 27, 2025

Uh oh!

scottaohara commented Mar 27, 2025

Uh oh!

giacomo-petri commented Apr 3, 2025

Uh oh!

pkra commented Apr 3, 2025

Uh oh!

pkra Jun 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pkra Jun 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

pkra Jun 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

giacomo-petri Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

spectranaut commented Jul 3, 2025

Uh oh!

spectranaut 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!

spectranaut left a comment

Choose a reason for hiding this comment

Uh oh!

giacomo-petri commented Mar 21, 2025 •

edited by pr-preview bot

Loading

netlify bot commented Mar 21, 2025 •

edited

Loading

pkra Jun 14, 2025 •

edited

Loading

pkra Jun 14, 2025 •

edited

Loading

pkra Jun 14, 2025 •

edited

Loading

giacomo-petri Aug 5, 2025 •

edited

Loading