docs(a11y): action menu a11y migration docs by nikkimk · Pull Request #6162 · adobe/spectrum-web-components

nikkimk · 2026-04-09T20:13:29Z

Description

In spectrum-web-components/CONTRIBUTOR-DOCS/03_project-planning/03_components/action-menu/accessibility-migration-analysis.md:

Documented recommendations for ARIA roles, states, and properties for the 2nd-gen action-menu
Shadow DOM and cross-root ARIA considerations documented, including any limitations or required workarounds (e.g., ElementInternals, cross-root ARIA delegation)
Accessibility tree expectations documented, including expected node roles, names, states, and hierarchy
Keyboard interaction model fully specified, covering focus management, key bindings, roving tabindex or active-descendant patterns, and focus trapping where applicable
Testing requirements defined, including unit tests, integration tests, and manual screen reader testing matrix (JAWS, NVDA, VoiceOver)
Known 1st-gen accessibility issues cataloged with disposition (fix in 2nd-gen, defer, or won't fix) and linked to any open GitHub issues or bugs
Applicable WAI-ARIA design pattern identified with relevant ARIA roles documented
1st-gen component analysis completed, covering current ARIA implementation, keyboard handling, existing test coverage, and known issues with dispositions

Motivation and context

The ticket requests accessibility recommendations for action-menu as part of its migration from 1st-gen to 2nd-gen. The recommendations should produce a comprehensive set of accessibility requirements that the engineering team will use as the specification for the 2nd-gen implementation.

The 2nd-gen migration is an opportunity to address known accessibility gaps, align with the latest WAI-ARIA Authoring Practices, and ensure the component meets WCAG 2.2 AA compliance.

Related issue(s)

fixes SWC-1922

Screenshots (if appropriate)

Author's checklist

I have read the CONTRIBUTING and PULL_REQUESTS documents.
I have reviewed at 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

Review the Action menu accessibility migration analysis

ARIA roles, states, and properties covered
Shadow DOM and cross-root ARIA considerations covered
Accessibility tree documented
Keyboard interaction fully specified
Testing requirements defined
Known 1st-gen issues cataloged with dispositions

changeset-bot · 2026-04-09T20:13:36Z

⚠️ No Changeset found

Latest commit: 5a930d0

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 · 2026-04-09T20:19:30Z

📚 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-6162

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.

cdransf

Looks good! Added a few suggestions ✨

cdransf · 2026-04-23T17:24:02Z

+
+Treat **application command menus** (action menu) and **site navigation** patterns as separate 2nd-gen components or documented compositions. Their keyboard contracts, roles, and user expectations differ; conflating them encourages incorrect `role="menu"` on link lists and confusing screen reader interaction modes.
+
+## Also read


Suggested change

## Also read

### Also read

cdransf · 2026-04-23T17:24:11Z

+
+- [Action menu migration roadmap](./rendering-and-styling-migration-analysis.md) — 2nd-gen DOM, CSS, and API migration (placeholder until expanded).
+
+## What it is not


Suggested change

## What it is not

### What it is not

cdransf · 2026-04-23T19:30:05Z

+- **Action menu (commands):** **`swc-action-menu`** plus **`swc-menu`** with **`menu`** / **`menuitem`** family.
+- **Navigation (links, site structure):** prefer disclosure navigation or menubar navigation examples as separate components or documented patterns; do not reuse **`swc-action-menu`** semantics for pure link navigation without a deliberate APG match.
+
+## Shadow DOM and cross-root accessibility


Suggested change

## Shadow DOM and cross-root accessibility

### Shadow DOM and cross-root accessibility

cdransf · 2026-04-23T19:30:17Z

+- Prefer focusable menu items with roving **`tabindex`** inside the menu root over `aria-activedescendant` pointing across shadow roots.
+- Ensure visible focus rings and high contrast behavior for focused **`menuitem`** rows.
+
+## Tree expectations


Suggested change

## Tree expectations

### Tree expectations

cdransf · 2026-04-23T19:30:30Z

+- **`swc-menu`** root has **`role="menu"`** and an accessible name (from label or **`aria-labelledby`**) when needed.
+- Items expose **`menuitem`** (or checkbox or radio variants) and correct **`aria-checked`** / **`aria-disabled`** as applicable.
+
+## Keyboard


Suggested change

## Keyboard

### Keyboard

cdransf · 2026-04-23T19:30:43Z

+
+When **`swc-menu`** supports **submenus**, also align submenu open/close and cross-level movement with the [menubar pattern keyboard table](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/) (submenu section) or an equivalent documented mapping.
+
+## Assistive technology and Escape


Suggested change

## Assistive technology and Escape

### Assistive technology and Escape

cdransf · 2026-04-23T19:46:34Z

+- **Not** primary site navigation by default: for collections of links that navigate pages, the APG [disclosure navigation menu example](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/) explicitly avoids **`role="menu"`** because typical site navigation does not implement the full menu keyboard contract, and **`menu`** triggers interaction modes screen readers reserve for application widgets.
+- **Not** `aria-activedescendant` for focus in 2nd-gen: cross-root ARIA does not solve active descendant across shadow boundaries reliably, and `aria-activedescendant` has known limitations on iOS VoiceOver. Action menu should use the proposed **`FocusgroupNavigationController`** (and related focus group work) as in [spectrum-web-components#6129](https://github.com/adobe/spectrum-web-components/pull/6129), not `aria-activedescendant`, for roving tabindex and arrow navigation inside the menu.
+
+## Pattern in the WAI-ARIA APG


Should this be updated? (And should it be under ## ARIA and WCAG context? Going off of the skill at .ai/skills/accessibility-migration-analysis/SKILL.md). ✨

Suggested change

## Pattern in the WAI-ARIA APG

### Pattern in the APG

cdransf · 2026-04-23T19:47:14Z

+
+**Takeaway:** use **`menu`** and **`menuitem`** family roles when behavior matches the menu button or menubar patterns. Use disclosure plus native links (or tabs or other patterns) when the primary job is in-page or multi-page navigation without application menu semantics.
+
+## Guidelines


Would this then be updated? ✨

Suggested change

## Guidelines

### Guidelines that apply

cdransf · 2026-04-23T19:48:39Z

+
+<!-- Document content (editable) -->
+
+## Overview


From the skill:

Separate major sections with a horizontal rule (---) where existing docs use it (after Overview, after ARIA and WCAG context, after Related 1st-gen accessibility (Jira) before Recommendations, after Recommendations block before Testing).

Do we need those? ✨

rubencarvalho

Left a few comments given the new menu direction 😄

rubencarvalho · 2026-04-27T13:19:16Z

+
+## Overview
+
+**`<swc-action-menu>`** (2nd-gen) is the Spectrum surface for a **menu button** that opens commands or choices in an overlay. On **smaller viewports** the menu should open in a **tray** by default for touch targets, readability, and escape from cramped layouts; on larger viewports it typically uses a **popover** unless the author **forces** popover (or tray) via API. It composes a trigger (typically a button) with `aria-haspopup="menu"`, `aria-expanded`, and `aria-controls` (or equivalent wiring) and a **`swc-menu`** that exposes **`role="menu"`** to assistive technologies regardless of tray vs popover presentation. The trigger and menu must share one DOM or shadow root because cross-root ARIA is not supported in browsers today.


We found that we won’t have a concept of Tray for now, so this may need some adjustments.

rubencarvalho · 2026-04-27T13:20:53Z

+
+### Composition and labelling
+
+- Always compose **`swc-menu`** inside a parent that provides open/close, focus return to the trigger, and `aria-labelledby` or `aria-label` for the menu where needed.


We will build menu as the current 1st gen action menu, meaning the trigger comes "included", so this may need some adjustments

rubencarvalho · 2026-04-27T13:21:39Z

+- **Trigger and menu must share one root:** the trigger (button) and the **`swc-menu`** surface must live in the same tree root (for example both inside the **`swc-action-menu`** shadow root or the same light-DOM subtree owned by that host). **Cross-root ARIA** — ID references such as **`aria-controls`**, **`aria-labelledby`**, and **`aria-activedescendant`** across separate shadow roots — is not supported in browsers today, so splitting the trigger and menu across unrelated custom element boundaries breaks those relationships.
+- Trigger should mirror APG menu button attributes (`aria-haspopup`, `aria-expanded`, `aria-controls` when appropriate).
+
+### Viewport and presentation (tray vs popover)


2nd-gen mobile drill-down is still WIP on the design side. There are currently no decisions on the future of tray. We will keep these out of scope until we know more.

rubencarvalho · 2026-04-27T13:23:17Z

+<swc-action-menu label="Actions">
+  <swc-menu id="actions-menu">
+    <swc-menu-item>Duplicate</swc-menu-item>
+    <swc-menu-item>Rename</swc-menu-item>
+    <swc-menu-separator></swc-menu-separator>
+    <swc-menu-item>Delete</swc-menu-item>
+  </swc-menu>
+</swc-action-menu>


I believe we may collapse this further, e.g.:

Suggested change

<swc-action-menu label="Actions">

<swc-menu id="actions-menu">

<swc-menu-item>Duplicate</swc-menu-item>

<swc-menu-item>Rename</swc-menu-item>

<swc-menu-separator></swc-menu-separator>

<swc-menu-item>Delete</swc-menu-item>

</swc-menu>

</swc-action-menu>

<swc-menu label="Actions">

<swc-menu-item>Duplicate</swc-menu-item>

<swc-menu-item>Rename</swc-menu-item>

<swc-menu-separator></swc-menu-separator>

<swc-menu-item>Delete</swc-menu-item>

</swc-menu>

nikkimk added 2 commits April 9, 2026 15:45

docs(a11y): updated rules for a11y migration docs

4219f4c

docs(action-menu): a11y migration docs for action menu

a0b7c0f

nikkimk marked this pull request as ready for review April 9, 2026 20:14

nikkimk requested a review from a team as a code owner April 9, 2026 20:14

nikkimk self-assigned this Apr 9, 2026

nikkimk requested a review from rubencarvalho April 9, 2026 20:14

Merge branch 'main' into nikkimk/action-menu-a11y-migration

932f052

caseyisonit added Status:Ready for review PR ready for review or re-review. 2nd gen These issues or PRs map to our 2nd generation work to modernizing infrastructure. High priority PR review PR is a high priority and should be reviewed ASAP labels Apr 20, 2026

nikkimk requested a review from cdransf April 22, 2026 21:03

nikkimk added 2 commits April 22, 2026 17:10

Delete .cursor/rules/accessibility-migration-analysis.mdc

38586f6

Merge branch 'main' into nikkimk/action-menu-a11y-migration

db18ad7

nikkimk enabled auto-merge (squash) April 22, 2026 21:10

nikkimk disabled auto-merge April 22, 2026 21:10

Merge branch 'main' into nikkimk/action-menu-a11y-migration

0390eb3

aramos-adobe approved these changes Apr 23, 2026

View reviewed changes

cdransf approved these changes Apr 23, 2026

View reviewed changes

nikkimk added 2 commits April 24, 2026 11:05

Merge branch 'main' into nikkimk/action-menu-a11y-migration

2fe3ef9

Merge branch 'main' into nikkimk/action-menu-a11y-migration

5a930d0

nikkimk enabled auto-merge (squash) April 27, 2026 13:10

rubencarvalho reviewed Apr 27, 2026

View reviewed changes

nikkimk merged commit 5af55c8 into main Apr 27, 2026
30 checks passed

nikkimk deleted the nikkimk/action-menu-a11y-migration branch April 27, 2026 13:25


		Treat application command menus (action menu) and site navigation patterns as separate 2nd-gen components or documented compositions. Their keyboard contracts, roles, and user expectations differ; conflating them encourages incorrect `role="menu"` on link lists and confusing screen reader interaction modes.

		## Also read


		- [Action menu migration roadmap](./rendering-and-styling-migration-analysis.md) — 2nd-gen DOM, CSS, and API migration (placeholder until expanded).

		## What it is not

	## Shadow DOM and cross-root accessibility
	### Shadow DOM and cross-root accessibility


		When `swc-menu` supports submenus, also align submenu open/close and cross-level movement with the [menubar pattern keyboard table](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/) (submenu section) or an equivalent documented mapping.

		## Assistive technology and Escape

	## Assistive technology and Escape
	### Assistive technology and Escape


		Takeaway: use `menu` and `menuitem` family roles when behavior matches the menu button or menubar patterns. Use disclosure plus native links (or tabs or other patterns) when the primary job is in-page or multi-page navigation without application menu semantics.

		## Guidelines


		## Overview

		`<swc-action-menu>` (2nd-gen) is the Spectrum surface for a menu button that opens commands or choices in an overlay. On smaller viewports the menu should open in a tray by default for touch targets, readability, and escape from cramped layouts; on larger viewports it typically uses a popover unless the author forces popover (or tray) via API. It composes a trigger (typically a button) with `aria-haspopup="menu"`, `aria-expanded`, and `aria-controls` (or equivalent wiring) and a `swc-menu` that exposes `role="menu"` to assistive technologies regardless of tray vs popover presentation. The trigger and menu must share one DOM or shadow root because cross-root ARIA is not supported in browsers today.


		### Composition and labelling

		- Always compose `swc-menu` inside a parent that provides open/close, focus return to the trigger, and `aria-labelledby` or `aria-label` for the menu where needed.

Conversation

nikkimk commented Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and context

Related issue(s)

Screenshots (if appropriate)

Author's checklist

Reviewer's checklist

Manual review test cases

Uh oh!

changeset-bot Bot commented Apr 9, 2026 • 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 Apr 9, 2026 • 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!

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

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

nikkimk commented Apr 9, 2026 •

edited

Loading

changeset-bot Bot commented Apr 9, 2026 •

edited

Loading

github-actions Bot commented Apr 9, 2026 •

edited

Loading