docs(tray): improve a11y of tray docs examples #5888

marissahuysentruyt · 2025-11-13T21:04:06Z

Description

This PR removes the menu examples found on the tray documentation page. The menu examples are partial and unrealistically used within the tray, so removing them resolves the accessibility concerns regarding aria-current/aria-checked.

Motivation and context

Screen readers were not announcing the selected state for menu items with role="menuitem", causing confusion for users relying on assistive technology. But because our examples were not realistic examples, (menus are usually children of popovers instead), removing the menu examples from the tray docs is most accurate.

Related issue(s)

Fixes SWC-1108

Author's checklist

I have read the CONTRIBUTING and PULL_REQUESTS documents.
I have reviewed the Accessibility Practices for this feature, see: Aria Practices
I have added automated tests to cover my changes.
I have included a well-written changeset if my change needs to be published.
I have included updated documentation if my change required it.

Reviewer's checklist

Includes a Github Issue with appropriate flag or Jira ticket number without a link
Includes thoughtfully written changeset if changes suggested include patch, minor, or major features
Automated tests cover all use cases and follow best practices for writing
Validated on all supported browsers
All VRTs are approved before the author can update Golden Hash

Manual review test cases

Tray docs no longer have menu examples
1. Go to sp-tray documentation.
2. Navigate to the 'Anatomy' section.
3. Verify the tabs are no longer present, and only the dialog example remains.
4. The new documentation is technically and grammatically accurate and follows Spectrum content standards.
5. Navigate to the 'Accessibility' section.
6. Validate the behavior of the tray in the "Content has no buttons" tab remains unchanged (i.e. the visually hidden dismiss buttons are still keyboard navigable and get announced properly by a screen reader).
  i. Verify the accessibility of the select element. It is implicitly associated to the label as a child of the label, and all options have value attributes.
~~Screen reader announces selected state for menuitem~~
1. ~~Go to sp-tray documentation~~
2. ~~Navigate to the 'Anatomy' section, 'Dialog' tab, and select the 'Menu' tab~~
3. ~~Activate the "Toggle menu" button and navigate to a selected menu item using a screen reader (NVDA, JAWS, or VoiceOver)~~
  i. ~~In the bug ticket, they are specifically using NVDA on a Windows machine, so I was using AssitivLabs during development. ~~
4. ~~Expect the screen reader to announce the selected/current state (e.g., "Deselect, current, 1 of 6")~~
~~aria-current attribute is correctly applied~~
1. ~~Inspect a selected sp-menu-item with role="menuitem" in browser DevTools~~
2. ~~Verify it has aria-current="true" attribute~~
3. ~~Inspect a non-selected sp-menu-item with role="menuitem"~~
4. ~~Verify it does NOT have an aria-current attribute (not set to "false")~~
5. ~~Manually remove the selected attribute from the first item.~~
6. ~~Verify the corresponding aria-current attribute is removed.~~
~~Other menu item roles are unaffected~~
1. ~~Test menu items with role="menuitemradio" and role="menuitemcheckbox"~~
2. ~~Verify they still use aria-checked (not aria-current)~~
3. ~~Test menu items with role="option" in a listbox context~~
4. ~~Verify they still use aria-selected (not aria-current)~~
~~New unit tests pass in CI.~~
1. ~~"sets aria-current to true if the item has selected property"~~
2. ~~"removes aria-current if the item is deselected"~~
3. "updates aria-current when the selected item changes"~~
~~New documentation for menu item is technically and grammatically accurate and follows Spectrum content standards.~~

Device review

Did it pass in Desktop?
Did it pass in (emulated) Mobile?
Did it pass in (emulated) iPad?

changeset-bot · 2025-11-13T21:04:12Z

⚠️ No Changeset found

Latest commit: b26aa22

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2025-11-13T21:06:10Z

📚 Branch Preview

🔍 Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

Deployed to Azure Blob Storage: pr-5888

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

caseyisonit

Gorg

Rajdeepc

Good fix!! One thing was to test that updateAriaSelected() is also called whenever the selected property changes which I see it is happening on

if (changes.has('selected')) {
    this.updateAriaSelected();
}

majornista · 2025-11-14T15:43:46Z

1st-gen/packages/menu/menu-item.md


+#### Roles and ARIA attributes
+
+When a menu item with `role="menuitem"` is selected, the `aria-current="true"` attribute is automatically applied to indicate the current item to screen reader users. This ensures assistive technology properly announces the selected state of menu items.


The appropriate way to indicate a selected state for an item in a menu is to use either role="menuitemcheckbox" for multi-selectable items, or role="menuitemradio" for mutually exclusive selection, with the aria-checked attribute to indicate the selected state. An element with role="menuitem" does not support the aria-checked or aria-selected property. See the supported states and properties for a menu item: https://w3c.github.io/aria/#menuitem.

An menuitem can support aria-current, but only in an appropriate context. See https://w3c.github.io/aria/#aria-current, which explains appropriate usage of aria-current:

aria-current state
Indicates the element that represents the current item within a container or set of related elements.

The aria-current attribute is a token type. Any value not included in the list of allowed values SHOULD be treated by assistive technologies as if the value true had been provided. If the attribute is not present or its value is the empty string or undefined, the default value of false applies and the aria-current state MUST NOT be exposed by user agents or assistive technologies.

The aria-current attribute is used when an element within a set of related elements is visually styled to indicate it is the current item in the set. For example:

A page token used to indicate a page within a set of pages, where the element is visually styled to represent the current page.

A step token used to indicate a step within a step-based process, where the element is visually styled to represent the current step.

A location token used to indicate the element that is visually styled as the current component, such as within a flow chart.

A date token used to indicate the current date within a calendar or other date collection.

A time token used to indicate the current time within a timetable or other time collection.
Authors SHOULD only mark one element in a set of elements as current with aria-current.

Authors SHOULD NOT use the aria-current attribute as a substitute for aria-selected in widgets where aria-selected has the same meaning. For example, in a tablist, aria-selected is used on a tab to indicate the currently-displayed tabpanel.

Note how the WAI-ARIA spec explicitly states that "Authors SHOULD NOT use the aria-current attribute as a substitute for aria-selected in widgets where aria-selected has the same meaning."

Let me rework this to come up with a solution that better fits how you're seeing the solution!

Is this an issue with the menu component or the docs themselves?

Menu already correctly assigns aria-selected (for role="option" menu items) and aria-checked (for role="menuitemcheckbox" or role="menuitemradio").

However, if the selects property is not defined, the default role for our menu items is menuitem, which doesn't support aria-checked/aria-selected. I think that because those menu examples on the tray docs didn't have the selects property (and therefore assigned menuitem roles to the sp-menu-items), we weren't announcing the selected state of the menu items correctly (because they don't hook into aria-checked).

I'm understanding Michael's comment below to be asking that question- if selects isn't on an sp-menu, how do we appropriately mark role="menuitem" elements as selectable (without using aria-current incorrectly).

This is what I'm imagining we would research in a separate ticket.

majornista · 2025-11-14T16:13:23Z

1st-gen/packages/menu/src/MenuItem.ts

+        if (role === 'menuitem') {
+            if (this.selected) {
+                this.setAttribute('aria-current', 'true');
+            } else {
+                this.removeAttribute('aria-current');
+            }
+        }


I'd prefer to keep aria-current as a separate concern from selection.

role is determined by either the role on the containing sp-menu or the selects property on the parent sp-menu or sp-menu-group. If the selected state is indicated on a menuitem without selects="multiple", selects="single" or selects="inherit" on the parent sp-menu or sp-menu-group, we should maybe change the role for the sp-menu-item to menuitemcheckbox. This gets messy though, because then the question becomes, what then is the role for the unselected state, and how do we indicate that an unselected item is selectable?

@majornista ah- thank you! I did see the note in the W3C docs about not substituting aria-current for aria-selected, but the ticket specifically called out aria-current as the solution, which is why I went this route.

@majornista To immediately solve the issue, can I make sure that the menu as display in this tray has the selects property? Then we can hook into the existing aria-checked logic, I can remove the aria-current logic I added, and the screen reader announces the selected item properly (which I think was the underlying complaint in the ticket).

I could also add more documentation guidelines around ensuring the selects property is added to the parent sp-menu, and describe the accessibility errors/failures that happen regarding sp-menu-items when selects is missing.

I'm going to bring this up with our team this morning as well to chat about a solution!

Update: these examples with a menu in a tray don't really make sense since they're only partial examples anyways. The team's preference is to remove the menu examples instead, resolving the ticket with documentation only 👍

Should this be a separate issue for menu instead of the scope of a tray docs PR?

I can make a new ticket! I have a local branch that should still have some of this previous work.

marissahuysentruyt · 2025-11-17T18:25:11Z

1st-gen/packages/tray/README.md

-        <sp-menu style="width: 100%">
-            <sp-menu-item selected>Deselect</sp-menu-item>
-            <sp-menu-item>Select Inverse</sp-menu-item>
-            <sp-menu-item focused>Feather...</sp-menu-item>
-            <sp-menu-item>Select and Mask...</sp-menu-item>
-            <sp-menu-divider></sp-menu-divider>
-            <sp-menu-item>Save Selection</sp-menu-item>
-            <sp-menu-item disabled>Make Work Path</sp-menu-item>
-        </sp-menu>


In context, this menu doesn't really make- it's only a partial implementation and would normally be rendered within a popover instead.

After discussing with the team, we decided to leave out the tray examples with menus in favor of other content.

marissahuysentruyt · 2025-11-17T18:25:50Z

1st-gen/packages/tray/README.md

    </sp-button>
    <sp-tray slot="click-content" has-keyboard-dismiss>
-        <p>
+        <p style="margin: 16px;">


I added this solely to make it look a little nicer inside the tray.

github-actions · 2025-11-17T18:30:23Z

📚 Branch Preview Links

🔍 First Generation Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

Deployed to Azure Blob Storage: pr-5888

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

caseyisonit · 2025-11-17T19:52:42Z

1st-gen/packages/tray/README.md

-<sp-tabs selected="dialog" auto label="Using tray's slot">
-<sp-tab value="dialog">Dialog</sp-tab>
-<sp-tab-panel value="dialog">
+A tray has a single default `slot`. Expected content typically includes dialogs and their content, plain text, forms and/or form elements, and some native HTML elements. Always ensure that your tray's content is accessible according to WCAG standards.


Clean language, love it

caseyisonit · 2025-11-17T19:53:36Z

1st-gen/packages/tray/README.md

+        <div style="display: flex; flex-direction: column; margin: 16px;">
+            <p style="margin-block-start: 0;">
+                Custom content that doesn't have dismiss functionality, so the
+                tray detects it needs the visually-hidden dismiss buttons.


yessss kween to incorporating contextual documentation in the example!! we should flag this as a good practice to continue!

caseyisonit

GLORIOUS 🔥

marissahuysentruyt changed the title ~~fix(menuitem): add aria-current logic~~ fix(menuitem): improve a11y of selected items with aria-current Nov 13, 2025

marissahuysentruyt self-assigned this Nov 13, 2025

marissahuysentruyt added 1.0.0 Issues that should be addressed for a 1.0 release! a11y Issues or PRs related to accessibility SEV 2 significant problem re: design, usability, or functionality of the system/components for some users labels Nov 13, 2025

marissahuysentruyt marked this pull request as ready for review November 13, 2025 22:51

marissahuysentruyt requested a review from a team as a code owner November 13, 2025 22:51

caseyisonit approved these changes Nov 13, 2025

View reviewed changes

Rajdeepc approved these changes Nov 14, 2025

View reviewed changes

Rajdeepc added the Status: Ready for merge PR has 2 approvals, all tests pass, and is ready to merge label Nov 14, 2025

majornista requested changes Nov 14, 2025

View reviewed changes

majornista reviewed Nov 14, 2025

View reviewed changes

marissahuysentruyt force-pushed the marissahuysentruyt/swc-1108-aria-current-on-selected-menu-item branch 2 times, most recently from 7b19176 to ae793d0 Compare November 17, 2025 18:23

marissahuysentruyt commented Nov 17, 2025

View reviewed changes

marissahuysentruyt marked this pull request as draft November 17, 2025 18:27

marissahuysentruyt removed the Status: Ready for merge PR has 2 approvals, all tests pass, and is ready to merge label Nov 17, 2025

marissahuysentruyt force-pushed the marissahuysentruyt/swc-1108-aria-current-on-selected-menu-item branch 2 times, most recently from ec8ab7b to 8538ccd Compare November 17, 2025 18:55

marissahuysentruyt requested review from Rajdeepc, caseyisonit and majornista November 17, 2025 19:14

marissahuysentruyt added the Status: Ready for review PR ready for review or re-review. label Nov 17, 2025

marissahuysentruyt marked this pull request as ready for review November 17, 2025 19:16

marissahuysentruyt changed the title ~~fix(menuitem): improve a11y of selected items with aria-current~~ docs(tray): improve a11y of tray docs examples Nov 17, 2025

caseyisonit reviewed Nov 17, 2025

View reviewed changes

caseyisonit approved these changes Nov 17, 2025

View reviewed changes

majornista approved these changes Nov 18, 2025

View reviewed changes

marissahuysentruyt force-pushed the marissahuysentruyt/swc-1108-aria-current-on-selected-menu-item branch from 8538ccd to 56a68e3 Compare November 19, 2025 16:56

docs(tray): replace menu examples with more appropriate content

b26aa22

marissahuysentruyt force-pushed the marissahuysentruyt/swc-1108-aria-current-on-selected-menu-item branch from 56a68e3 to b26aa22 Compare November 19, 2025 17:09

marissahuysentruyt merged commit 8a00f23 into main Nov 19, 2025
21 checks passed

marissahuysentruyt deleted the marissahuysentruyt/swc-1108-aria-current-on-selected-menu-item branch November 19, 2025 17:32


		#### Roles and ARIA attributes

		When a menu item with `role="menuitem"` is selected, the `aria-current="true"` attribute is automatically applied to indicate the current item to screen reader users. This ensures assistive technology properly announces the selected state of menu items.

docs(tray): improve a11y of tray docs examples #5888

docs(tray): improve a11y of tray docs examples #5888

Uh oh!

Conversation

marissahuysentruyt commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and context

Related issue(s)

Author's checklist

Reviewer's checklist

Manual review test cases

Device review

Uh oh!

changeset-bot bot commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions bot commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Branch Preview

🔍 Visual Regression Test Results

Uh oh!

caseyisonit left a comment

Choose a reason for hiding this comment

Uh oh!

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

marissahuysentruyt Nov 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!

github-actions bot commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Branch Preview Links

🔍 First Generation Visual Regression Test Results

Uh oh!

Choose a reason for hiding this comment

Uh oh!

caseyisonit Nov 17, 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!

caseyisonit left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

marissahuysentruyt commented Nov 13, 2025 •

edited

Loading

changeset-bot bot commented Nov 13, 2025 •

edited

Loading

github-actions bot commented Nov 13, 2025 •

edited

Loading

marissahuysentruyt Nov 14, 2025 •

edited

Loading

github-actions bot commented Nov 17, 2025 •

edited

Loading

caseyisonit Nov 17, 2025 •

edited

Loading