check mappings and a11y of HTMLButtonElement's declarative scroll commands

[davidsgrogan]

@danielsakhapov has written Explainer: add declarative scroll commands to HTMLButtonElement for a new small web feature, and has consulted with @lucasradaelli on the a11y section but they want ARIA's thoughts also. The most relevant sections are excerpted here, but the entire Explainer is not very long.

---

Summary

This proposal introduces a set of new command values for the HTMLButtonElement to declaratively control the scroll position of a target element. This allows authors to create custom scrolling UI (e.g., for carousels or galleries) without requiring JavaScript, improving accessibility and simplifying implementation.

[snip]

Accessibility & keyboard interaction

This proposal standardizes declarative scrolling by moving state management from custom scripts to the browser engine. To ensure these buttons are accessible by default, the following behaviors are required:

Implicit semantic mapping

The commandfor attribute creates a direct relationship between the button and its scroll container, which the browser must expose to Assistive Technology (AT):

• Implicit aria-controls: The browser maps commandfor="ID" to the aria-controls relationship.
• Contextual labeling: If the target container has an accessible name (e.g., aria-label="Document Preview"), the browser should propagate this to the button’s announcement. For example, a page-inline-end command would be announced as "Next page, Document Preview, button."
• Announcement Priority:
  • If a button has a custom aria-label, the browser should use that label as the primary identifier.
  • If no custom label exists, the browser generates a name combining the command action and the target container's name (e.g., "Next page, Document Preview, button").

State management and styling

One of the primary benefits of this declarative approach is automatic state synchronization.

• Boundary detection: The browser should automatically manage the aria-disabled state. When a scroller cannot be moved further in the associated direction, the corresponding button is marked aria-disabled="true".
• Focus preservation: The use of aria-disabled is required over the HTML disabled attribute to ensure the button remains in the Tab order. If the button were strictly disabled via the HTML attribute, a keyboard user would lose their focus point upon reaching the end of the scrollable region, causing the focus to reset to the top of the document.
• Styling via attribute selectors: Authors can style these states using attribute selectors (e.g., button[aria-disabled="true"]) to provide visual parity with the :disabled pseudo-class while maintaining accessibility.

Internationalization & writing modes

Logical commands (page-inline-start, page-block-end, etc.) ensure that scrolling directions automatically adapt to the document's writing mode. In a Right-to-Left (RTL) context, page-inline-end will correctly scroll to the left, ensuring that "Next" remains semantically and functionally accurate without requiring manual direction logic from the author.

Handling multi-axis scrolling

In complex interfaces where a single container supports both horizontal and vertical scrolling, the AT announcement must distinguish between axes to prevent user confusion. When multiple scroll commands target the same commandfor ID, the browser should include the axis in the announcement.A page-inline-end button would be announced as "Next page, horizontal, [Container Name], button."A page-block-end button would be announced as "Next page, vertical, [Container Name], button."

[css-meeting-bot]

The ARIA Working Group just discussed check mappings and a11y of HTMLButtonElement's declarative scroll commands.

The full IRC log of that discussion

<Zakim> agendum 7 -- -> check mappings and a11y of HTMLButtonElement's declarative scroll commands https://github.com//issues/600 -- taken up [from agendabot]
<Adam_Page> jamesn: is anyone familiar with this?
<sakhapov> sakhapov
<Adam_Page> sakhapov: please open the explainer
<Adam_Page> ... in the Example Usage section
<Adam_Page> ... there is an HTML button
<Adam_Page> ... we want to introduce new commands
<Adam_Page> ... that would allow scrolling
<Adam_Page> ... e.g., `page-inline-start`, `page-inline-end`
<Adam_Page> ... the a11y part is how to declare it to the user
<Adam_Page> ... browsers should mount it to `aria-controls`
<Adam_Page> ... if the scroller has an `aria-label`, we take that name to announce what the button does
<Adam_Page> ... e.g., “Next page, document preview, button”
<Adam_Page> ... this is the first part of the proposal
<scott> q+
<jamesn> q+
<Adam_Page> ... second part is button has state management
<Adam_Page> ... it becomes disabled when the scrolling position is at the corresponding end
<jamesn> Ack scott
<Adam_Page> scott: I read through this earlier today
<Adam_Page> ... and understand where this is coming from
<Adam_Page> ... having consulted on the CSS carousel proposal
<Adam_Page> ... the thing that struck me here was the explicit use of `aria-label`
<Adam_Page> ... and appending it to the button accname
<Adam_Page> ... for this use case, does it actually make sense to include them in the accessible name of the previous and next buttons
<Adam_Page> ... but I do agree it makes sense to announce when the new content has been revealed
<Adam_Page> ... so I see the intent
<Adam_Page> ... but a little unsure of it at this time
<Adam_Page> ... with the aria-controls mapping, if we could get that to be useful, then maybe it could apply here
<Adam_Page> ... that’s my initial feedback
<Adam_Page> ... focusing heavily on `aria-label`, but there are other ways to name a button
<jamesn> Act jamesn
<Adam_Page> sakhapov: how would the user know what the scroller does?
<Adam_Page> scott: no one looking at the page would know what it is either
<Adam_Page> jamesn: the aria-label in this proposal refers to the scrolling group, not one of the grouped items
<Adam_Page> sakhapov: correct, it’s the name of the scrolling group
<Adam_Page> ... it’s not possible to put the scrolling buttons inside the scrolling region
<Adam_Page> jamesn: this needs clarifying in the explainer
<jamesn> Ack jamesn
<Adam_Page> jamesn: what happens when the button is pressed?
<Adam_Page> ... what announcement will AT users get at that time?
<Adam_Page> ... we need some sort of announcement, and how would the author specify something custom if they didn’t want the default behavior?
<jamesn> Q?
<jamesn> Agenda?
<Adam_Page> sakhapov: makes sense
<Adam_Page> jcraig: I echo some of jamesn’s concerns
<Adam_Page> ... should be up to the web author what gets announced
<Adam_Page> ... as one example, on the Mac side a button would confirm “pressed”, which would sometimes trample the thing that comes later
<Adam_Page> ... so we changed to an earcon
<Adam_Page> ... just want to make sure that we’re overspecifying in a way that the downstream AT can present to the user based on what the user wants
<Adam_Page> spectranaut_: do we need more discussion on this?
<Adam_Page> jamesn: I think we need explainer clarifications first, then more discussion
<jamesn> Zakim, end meeting

[davidsgrogan]

@danielsakhapov updated the explainer to address questions from last time this was discussed.

[css-meeting-bot]

The ARIA Working Group just discussed check mappings and a11y of HTMLButtonElement's declarative scroll commands.

The full IRC log of that discussion

<Zakim> agendum 5 -- -> check mappings and a11y of HTMLButtonElement's declarative scroll commands https://github.com//issues/600 -- taken up [from agendabot]
<pkra> spectranaut_: we briefly discussed this a few meetings ago.
<pkra> ... we ended with questions.
<pkra> ... in particular, what's announced when these buttons are clicked.
<pkra> ... how is scrolling announced.
<pkra> ... there's been an update.
<pkra> daniil: to recap, we want to add scroll events for html buttons.
<pkra> ... the question is how the changes in the scroller are announced.
<jcraig> Explainer update here: https://github.com/danielsakhapov/declarative-scroll-commands-for-html-explainer/blob/master/README.md
<pkra> ... first proposal is that it shouldn't be connected to the buttons at all but separate.
<pkra> ... proposal: snap change event. Contains snap target.
<pkra> ... could be used as some way to understand which element is in view.
<jcraig> Deep link to scrollsnapchange: https://github.com/danielsakhapov/declarative-scroll-commands-for-html-explainer/blob/master/README.md#currently-possible-solution-scrollsnapchange
<pkra> ... problem: it only works with snappable containers, with limited implementations.
<pkra> ... 2nd proposal: declarative live regions.
<pkra> ... live region would have idref to scroller.
<jcraig> deep link to Daniil's new aria-live-source proposal https://github.com/danielsakhapov/declarative-scroll-commands-for-html-explainer/blob/master/README.md#proposed-extension-declarative-live-regions-aria-live-source
<pkra> ... the bowser could detect which element is in view, we can extract which element is active, take its label and without changing the DOM the browser sends the even to the OS that something has changed, e.g., with label.
<pkra> ... this would allow us to avoid requiring changes to AT
<pkra> ... problem is that you cannot really change much.
<pkra> ... but it's simple to subscribe.
<pkra> ... if this lacks flexibility, then a new event might be an option. Firing on any kind of scroller. Browser gives you the elements in view. You can then format it as you want and update the aria-live content.
<spectranaut_> agenda?
<jcraig> q+ to ask why the aria-live wouldn't already work?
<spectranaut_> q?
<scott> q+
<spectranaut_> q+ matt
<pkra> jcraig: thanks for the explainer updates.
<pkra> ... regarding aria-live-source. What's currently possible with aria-live, in particular atomic, and the events you described, I think you can already do this.
<pkra> ... if it requires JS, then it should work already.
<pkra> daniil: the goal is to have no JS needed. The idea is that aria-live is subscribed to the scroller. Then the aria-live is populated automatically by the label of the element in view.
<pkra> jcraig: do you update the label?
<pkra> daniil: no, the label comes from the element in view.
<pkra> jcraig: thanks for clarifying.
<spectranaut_> ack jcraig
<Zakim> jcraig, you wanted to ask why the aria-live wouldn't already work?
<spectranaut_> ack scott
<pkra> scott: option 2 seems a bit more elegant, especially with aria-notify.
<pkra> ... for option 1, the markup seems a bit confusing to me.
<pkra> ... I can imagine aria-live-source acting a bit like labelledby. It's different in that you're not putting anything into it.
<pkra> ... of course we want the accname for whatever is shown.
<pkra> ... that could be done by role=status or alert right now if labelledby would point to the ID which changes
<pkra> ... not saying that's how it worked. just conceptually similar.
<pkra> ... I wonder why wouldn't we just use aria-notify since that's sort-of the future of aria-live / live regions.
<pkra> ... and since we don't want to add new features that aren't testable.
<pkra> ... anyway, I'm more in favor of option 2.
<spectranaut_> ack scott
<jcraig> q+
<pkra> matt: on option 2. you said you have flexibility here.
<pkra> ... is option 2 also not requiring JS to get this kind of flexibility?
<pkra> ... or is it the AT that's more flexible in presenting or filtering.
<pkra> daniil: I mean just the author.
<pkra> ... in the first option with aria-live-source, it's the browser that sources things.
<pkra> ... in option 2, it's the author.
<pkra> matt: so option 2 needs JS to format?
<pkra> jcraig: yes.
<pkra> matt: ok, then it doesn't achieve the objectives of option 1 but gives the flexibility.
<spectranaut_> After the third bullet in this section is the 2nd example https://github.com/danielsakhapov/declarative-scroll-commands-for-html-explainer/blob/master/README.md#extra-thoughtspossible-extensions
<spectranaut_> q?
<spectranaut_> ack masonf
<spectranaut_> ack matt
<spectranaut_> ack jcraig
<pkra> jcraig: if it's really as simple as "DOM announcement of an aria-label", could it not be done from the scroll snap change?
<pkra> ... or is there a downside?
<pkra> matt: how would AT handle that?
<pkra> ... announcement with properties like aria-notify to enable AT to properly filter or control presentation?
<pkra> jcraig: maybe not even aria-notify. Just on scroll snapped event, we could say that the expected behavior is triggering a live region event with the computed label.
<pkra> ... it's then separate from really both live and notify.
<spectranaut_> q+
<pkra> ... it just gets routed to the platforms. maybe using live-like treatment under the hood.
<pkra> daniil: I thought it should be opt-in.
<pkra> jcraig: does it need to be opt in? Can we think of reasons it's too chatty or users don't want it?
<pkra> matt: feels like at least authors should opt in.
<pkra> ... when they do want a specific behavior.
<pkra> ... often what's snapped into view is a container that contains a lot of stuff, may not be named meaningfully.
<pkra> ... e.g. subset of a collection
<pkra> ... like a few thumbnails at once
<pkra> ... might need author control.
<pkra> jcraig: if they label the items, they could have granular control.
<pkra> ... there might be times where it's chatty but users would be able to cancel e.g. speech updates.
<pkra> ... but you're sitting on a button that you're activating.
<pkra> ... and by default you get an update.
<scott> q+
<pkra> matt: right. I think there might be a situation where authors want more control than the name of a container.
<pkra> ... generating containers and naming them might be a bigger ask.
<pkra> spectranaut_: recap, jcraig is suggesting making option 1 but as a default.
<pkra> jcraig: for option 2, you could use prevent default .
<spectranaut_> ack scott
<spectranaut_> ack spectranaut_
<jcraig> q+
<pkra> scott: I'm more in favor of jcraig's revision of option 1. Not asking authors to create an aria-live element somewhere.
<pkra> ... from a quick test, if I understand the feature correctly, then putting aria-labelledby on a visually hidden status element, pointing to it, hiding/showing that. It's announcing the correct thing. So it seems we could already do option 1 easily.
<spectranaut_> ack jcraig
<pkra> jcraig: just to clarify. this will obviously depend on how my suggestion is written up.
<Matt_King> q+
<pkra> ... I think the request to make this opt-out could be possible.
<pkra> ... and yes, notifications are not testable. But this seems more like a new behavior not a new feature as such.
<spectranaut_> ack Matt_King
<pkra> matt: I like this direction, in particular if there is an opt-out.
<pkra> ... and if the events help identify the source.
<pkra> ... e.g. when we talk to AT vendors, they tend to need a way to identify where the events come from.
<pkra> spectranaut_: any other questions right now?
<pkra> daniil: having this on by default seems risky. This proposal is independent of the buttons themselves. If we're discussing this, we should be able to apply this to any scroller.
<pkra> ... or should it depend on the button specifically?
<pkra> jcraig: you're saying the announcement would happen in many other scenarios?
<scott> q+
<pkra> daniil: yes. And also not just on snappable. These buttons can be used outside snapping. E.g. scroll to TOS.
<pkra> jcraig: I think it should not apply to any scroller. Snapping has a more specific intent.
<pkra> daniil: but then scroll-snap-end event is sufficient?
<Matt_King> q+
<pkra> jcraig: then the question might be if authors can prevent the announcement.
<pkra> daniil: it just gives you the even, it doesn't update anything, just gives you the information
<pkra> jcraig: I have to spend more time on the opt-out considerations.
<pkra> ... I might be misunderstanding this.
<pkra> daniil: how would you envision the opt-out?
<pkra> jcraig: usually when you change focus, things get trampled over.
<spectranaut_> ack scott
<spectranaut_> zakim, close queue
<Zakim> ok, spectranaut_, the speaker queue is closed
<pkra> scott: clarifying question: this may be unwanted, e.g., when multiple items are in the available viewport. Say in a TOC. If you scroll, the other elements might not be out of view. Figuring out which accname to announce.
<pkra> ... in the carousel example, it's often assumed that if you only show a particular panel at a time, the off-screen content should be hidden.
<pkra> ... but from other work on carousel, that content is not necessarily hidden, so it might still contribute.
<pkra> ... I still feel like aria-notify is still the better path to follow.
<jcraig> I'm coming back around to option 2
<pkra> matt: re "all scrollers". It matter a lot what's triggering a scroller. In the case of the button, it's useful because it's outside the controller.
<jcraig> the new js event
<pkra> ... if the focus is inside, but say a keyboard event scrolls a feed you're inside, then announcements would be very confusing.
<pkra> ... it matters a lot.
<pkra> jcraig: thanks. I'm coming around back to your point of view.
<spectranaut_> agenda?
<pkra> daniil: thanks. if scott could add a comment. And perhaps we could split out the buttons.
<pkra> zakim, close this item
<Zakim> I see a speaker queue remaining and respectfully decline to close this agendum, pkra
<pkra> zakim, next item
<Zakim> I see a speaker queue remaining and respectfully decline to close this agendum, pkra
<pkra> q?
<pkra> ack Matt_King
<pkra> zakim, next item