Add aria-actions focus handling wording by smhigley · Pull Request #2845 · w3c/aria

smhigley · 2026-07-16T00:12:57Z

🚀 Netlify Preview:
🔄 this PR updates the following sspecs:

core-aam preview — core-aam diff
ARIA preview — ARIA diff

This is a PR into the aria-actions branch, not into main. It's split out into its own PR for ease of reviewing this specific update.

I tried to put our agreed-on focus bounce behavior into spec language. In plain language, what happens is:

The browser (not ATs) allow DOM focus to move to the action following the click event, but don't fire API focus events, so screen reader cursors will stay on the referencing element. After a short delay (maybe one tick, maybe a small timeout), browsers will move focus back to the referencing element unless focus has moved somewhere else in the meantime. The API focus event still won't be called, so from a screen reader user's perspective, there have been no focus changes at all. But from a page javascript perspective, the normal events have fired.

I didn't include any wording about what happens if a page author does preventDefault on the click or on the first focus event, since that seems too far into the weeds of DOM behavior for ARIA (and more of a JS/eventing concern). Let me know if anyone feels that should be here, though.

github-actions · 2026-07-16T00:14:55Z

🚀 Deployed on https://deploy-preview-2845--wai-aria.netlify.app

spectranaut · 2026-07-16T17:13:33Z

@twilco I can't add you to the review list but if you can take a look

cookiecrook · 2026-07-20T23:55:59Z

          <h4 id="ariaActions"><code>aria-actions</code></h4>
-          <table aria-labelledby="ariaActions">
+          <p>
+            After an action is invoked, browsers MUST NOT fire the API's <a href="#focus_state_event_table">focus event</a> when the referenced action node receives focus.


Suggested change

After an action is invoked, browsers MUST NOT fire the API's <a href="#focus_state_event_table">focus event</a> when the referenced action node receives focus.

After an action is invoked, browsers SHOULD NOT fire the system or accessibility-specific <a href="#focus_state_event_table">focus event</a> when the referenced action node receives focus.

Also I think this should be focus "Notification" or "Signals" rather than "Events"? My understanding is that, for most native platform APIs "Event" is referring to an input event like a click (most often user-triggered), but the subsequent broadcasts that goes out over the system would be called "Notifications" on Windows and Apple systems, or "Signals" on GTK.

I don't have a strong preference here but wanted to note that core-aam already uses the term "Focus event" for these platform mappings. If we want to use "Notification" or "Signals" instead, we should change this everywhere for consistency.

cookiecrook · 2026-07-21T00:00:51Z

-          <table aria-labelledby="ariaActions">
+          <p>
+            After an action is invoked, browsers MUST NOT fire the API's <a href="#focus_state_event_table">focus event</a> when the referenced action node receives focus.
+            The browser MUST subsequently return DOM focus to the referencing node also without firing an API <a href="#focus_state_event_table">focus event</a>,


"subsequently" may be too vague here. does this happen in the same runloop? If not, how long could/should an implementation wait before it's non-compliant?

Also, same issue as above wrt "event" vs "notification" and "system or accessibility-specific" vs "API"

There should not be a comma before the word 'unless':

Suggested change

The browser MUST subsequently return DOM focus to the referencing node also without firing an API <a href="#focus_state_event_table">focus event</a>,

The browser MUST subsequently return DOM focus to the referencing node also without firing an API <a href="#focus_state_event_table">focus event</a>

cookiecrook · 2026-07-21T00:03:04Z

              <li>User Agents SHOULD use the accessible names of elements referenced by <code>aria-actions</code> to determine the names of actions that are exposed in a platform accessibility API.</li>
              <li>User Agents MUST NOT expose <code>aria-actions</code> if the Author MUST's are not followed.</li>
            </ul>
+            <p>In order to allow users to invoke actions while remaining on the referencing element, browsers MUST do the following steps to manage focus once an action is invoke via the <code>aria-actions</code> API:</p>


Suggested change

In order to allow users to invoke actions while remaining on the referencing element, browsers MUST do the following steps to manage focus once an action is invoke via the <code>aria-actions</code> API:

In order to allow users to invoke actions while remaining on the referencing element, browsers MUST perform the following steps to manage focus once an action is invoked via <code>aria-actions</code>:

In addition to the first two editorial diffs here, I wasn't sure "the aria-actions API" sounded quite right to me. I'm not set on that final diff through if you want it back.

Suggested change:

To prevent unexpected focus change away from the referencing element after users invoke actions, browsers MUST perform the following steps to manage focus once an action is invoked via <code>aria-actions</code>:

I suggest changing the initial phrase to clarify both:

that the user is not on the referencing element, the focus is on the referencing element.

The intent is to maintain focus after the action is invoked if doing so is xpected.

cookiecrook · 2026-07-21T00:06:51Z

+                 If the referenced action node is focusable and receives focus as a result of an <code>aria-actions</code> invocation:
+                <ul>
+                  <li>Allow the DOM focus events to fire on the referenced action node as a result of invoking it.</li>
+                  <li>Do not fire the <a>desktop focus event</a>.</li>


Suggested change

<li>Do not fire the <a>desktop focus event</a>.</li>

<li>Do not fire the <a>system or accessibility-specific focus notification</a>.</li>

Caveat: keep this in line with whatever prose decision is made above on this same issue.

this one was a bit on purpose, since the wording "desktop focus event" is used for this elsewhere in the spec & there's a definition for it as well

cookiecrook · 2026-07-21T00:11:32Z

+                  <li>Do not fire the <a>desktop focus event</a>.</li>
+                </ul>
+              </li>
+              <li>If focus is moved either programmatically or via a user interaction, handle that focus change as normal, and do not perform any further <code>aria-actions</code> focus steps.</li>


If focus is moved either programmatically or via a user interaction,

I presume you're not counting an aria-actions invocation here as a "user interaction" so I would recommend a different term that more clearly excludes it.

handle that focus change as normal

Is there language in the HTML or DOM specs that phrases these more precisely?

I think if a second aria-actions invocation happened here, then presumably this set of focus steps should be abandoned and that aria-actions focus behavior should be kicked off, so I think it still applies 😅

Still open to better or more precise wording in both cases though

cookiecrook · 2026-07-21T00:12:47Z

+                </ul>
+              </li>
+              <li>If focus is moved either programmatically or via a user interaction, handle that focus change as normal, and do not perform any further <code>aria-actions</code> focus steps.</li>
+              <li>If focus has not moved, the browser MUST move DOM focus back to the referencing element, again without firing a <a>desktop focus event</a>.</li>


But focus did move to get here, right? So the "if focus has not moved" clause would never be invoked.

ditto prose for "desktop focus event" (these notifications also aren't limited to "desktops")

This is the spec definition for "desktop focus event", should we change the wording or add an additional term that shares the same def?

Event from/to the host operating system via the accessibility API, notifying of a change of input focus.

Suggested change

<li>If focus has not moved, the browser MUST move DOM focus back to the referencing element, again without firing a <a>desktop focus event</a>.</li>

<li>If the referenced action node is focusable and received focus, move DOM focus back to the referencing element without firing a <a>desktop focus event</a>.</li>

This list item needs the same 'if' condition as the first list item. It does not need to state that it is the result of the action invocation or that the browser must do the focus change because those things are stated before the start of the list.

cookiecrook · 2026-07-21T00:14:01Z

+              </li>
+              <li>If focus is moved either programmatically or via a user interaction, handle that focus change as normal, and do not perform any further <code>aria-actions</code> focus steps.</li>
+              <li>If focus has not moved, the browser MUST move DOM focus back to the referencing element, again without firing a <a>desktop focus event</a>.</li>
+              <li>If the referencing element can no longer be focused, the browser MAY keep focus on the referenced action element and fire a <a>desktop focus event</a>.</li>


mcking65

I've made a few suggestions. While they effect meaning, I don't think they change the intended meaning.

mcking65 · 2026-08-10T03:11:26Z

-          <table aria-labelledby="ariaActions">
+          <p>
+            After an action is invoked, browsers MUST NOT fire the API's <a href="#focus_state_event_table">focus event</a> when the referenced action node receives focus.
+            The browser MUST subsequently return DOM focus to the referencing node also without firing an API <a href="#focus_state_event_table">focus event</a>,


There should not be a comma before the word 'unless':

Suggested change

The browser MUST subsequently return DOM focus to the referencing node also without firing an API <a href="#focus_state_event_table">focus event</a>,

The browser MUST subsequently return DOM focus to the referencing node also without firing an API <a href="#focus_state_event_table">focus event</a>

mcking65 · 2026-08-10T03:27:30Z

              <li>User Agents SHOULD use the accessible names of elements referenced by <code>aria-actions</code> to determine the names of actions that are exposed in a platform accessibility API.</li>
              <li>User Agents MUST NOT expose <code>aria-actions</code> if the Author MUST's are not followed.</li>
            </ul>
+            <p>In order to allow users to invoke actions while remaining on the referencing element, browsers MUST do the following steps to manage focus once an action is invoke via the <code>aria-actions</code> API:</p>


Suggested change:

To prevent unexpected focus change away from the referencing element after users invoke actions, browsers MUST perform the following steps to manage focus once an action is invoked via <code>aria-actions</code>:

mcking65 · 2026-08-10T03:31:09Z

              <li>User Agents SHOULD use the accessible names of elements referenced by <code>aria-actions</code> to determine the names of actions that are exposed in a platform accessibility API.</li>
              <li>User Agents MUST NOT expose <code>aria-actions</code> if the Author MUST's are not followed.</li>
            </ul>
+            <p>In order to allow users to invoke actions while remaining on the referencing element, browsers MUST do the following steps to manage focus once an action is invoke via the <code>aria-actions</code> API:</p>


I suggest changing the initial phrase to clarify both:

that the user is not on the referencing element, the focus is on the referencing element.

The intent is to maintain focus after the action is invoked if doing so is xpected.

mcking65 · 2026-08-10T03:36:16Z

+            <p>In order to allow users to invoke actions while remaining on the referencing element, browsers MUST do the following steps to manage focus once an action is invoke via the <code>aria-actions</code> API:</p>
+            <ol>
+              <li>
+                 If the referenced action node is focusable and receives focus as a result of an <code>aria-actions</code> invocation:


Suggested change

If the referenced action node is focusable and receives focus as a result of an <code>aria-actions</code> invocation:

If the referenced action node is focusable and received focus as a result of an <code>aria-actions</code> invocation:

mcking65 · 2026-08-10T03:40:38Z

+                </ul>
+              </li>
+              <li>If focus is moved either programmatically or via a user interaction, handle that focus change as normal, and do not perform any further <code>aria-actions</code> focus steps.</li>
+              <li>If focus has not moved, the browser MUST move DOM focus back to the referencing element, again without firing a <a>desktop focus event</a>.</li>


Suggested change

<li>If focus has not moved, the browser MUST move DOM focus back to the referencing element, again without firing a <a>desktop focus event</a>.</li>

<li>If the referenced action node is focusable and received focus, move DOM focus back to the referencing element without firing a <a>desktop focus event</a>.</li>

mcking65 · 2026-08-10T03:43:56Z

+                </ul>
+              </li>
+              <li>If focus is moved either programmatically or via a user interaction, handle that focus change as normal, and do not perform any further <code>aria-actions</code> focus steps.</li>
+              <li>If focus has not moved, the browser MUST move DOM focus back to the referencing element, again without firing a <a>desktop focus event</a>.</li>


This list item needs the same 'if' condition as the first list item. It does not need to state that it is the result of the action invocation or that the browser must do the focus change because those things are stated before the start of the list.

add aria-actions focus-handling wording to ARIA and Core AAM

64579bf

github-actions Bot added spec:core-aam spec:aria labels Jul 16, 2026

github-actions Bot temporarily deployed to pull request July 16, 2026 00:14 Inactive

spectranaut requested review from cookiecrook, janewman, jcsteh and mcking65 July 16, 2026 17:10

cookiecrook requested changes Jul 21, 2026

View reviewed changes

mcking65 approved these changes Aug 10, 2026

View reviewed changes

	After an action is invoked, browsers MUST NOT fire the API's <a href="#focus_state_event_table">focus event</a> when the referenced action node receives focus.
	After an action is invoked, browsers SHOULD NOT fire the system or accessibility-specific <a href="#focus_state_event_table">focus event</a> when the referenced action node receives focus.

	The browser MUST subsequently return DOM focus to the referencing node also without firing an API <a href="#focus_state_event_table">focus event</a>,
	The browser MUST subsequently return DOM focus to the referencing node also without firing an API <a href="#focus_state_event_table">focus event</a>

	<p>In order to allow users to invoke actions while remaining on the referencing element, browsers MUST do the following steps to manage focus once an action is invoke via the <code>aria-actions</code> API:</p>
	<p>In order to allow users to invoke actions while remaining on the referencing element, browsers MUST perform the following steps to manage focus once an action is invoked via <code>aria-actions</code>:</p>

	<li>Do not fire the <a>desktop focus event</a>.</li>
	<li>Do not fire the <a>system or accessibility-specific focus notification</a>.</li>

	<li>If focus has not moved, the browser MUST move DOM focus back to the referencing element, again without firing a <a>desktop focus event</a>.</li>
	<li>If the referenced action node is focusable and received focus, move DOM focus back to the referencing element without firing a <a>desktop focus event</a>.</li>

	If the referenced action node is focusable and receives focus as a result of an <code>aria-actions</code> invocation:
	If the referenced action node is focusable and received focus as a result of an <code>aria-actions</code> invocation:

Uh oh!

Conversation

smhigley commented Jul 16, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 16, 2026

Uh oh!

spectranaut commented Jul 16, 2026

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!

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!

smhigley Jul 23, 2026 • 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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

smhigley commented Jul 16, 2026 •

edited by github-actions Bot

Loading

smhigley Jul 23, 2026 •

edited

Loading