Consider providing a way for authors to customize the announcement of state

[scottaohara]

During the open ui call today, we were talking about switches and how it can be awkward to need to figure out the label for a switch that makes sense for the 'on' or 'off' states - when really what someone wants to do is communicate that something is in the "dark mode" or "light mode" state.

tldr; it made me wonder if there is any appetite for a aria-roledescription attribute, but specifically to revise the way a state is communicated.

believe me, i feel yucky for asking about this. but i also can't deny the fact that I've also wanted this as well.

[spectranaut]

Discussed briefly during new issue triage: https://www.w3.org/2023/12/07-aria-minutes.html#t01

[giacomo-petri]

How about incorporating a feature akin to the aria-valuetext attribute available in the progressbar role?

If supported by both browsers and assistive technologies, this enhancement could expose the element as a switch button but, instead of announcing the standard "on/off" state, the technology can communicate the designated aria-valuetext value.

By doing so, we can maintain consistency between the role announced by screen readers and the operability for sighted keyboard-only users (using the enter/space bar).

It is crucial for authors to take responsibility for updating the aria-valuetext value to accurately reflect the state of the switch button.

So, if dealing with a conventional on/off switch button, using aria-checked is the appropriate solution. However, if the switch represents something other than a standard on/off state, such as "dark mode/light mode" or "centimeters/inches," it might be more fitting to utilize aria-valuetext.

[scottaohara]

good comparison @giacomo-petri

so it's not even just aria-roledescription that shows there is precedent for this with roles, but aria-valuetext is similarly allowing for a rewriting of a specific state for a specific role.

[spectranaut]

Notes from today's discussion in the ARIA working group: https://www.w3.org/2024/01/11-aria-minutes#t09

[MarioBatusic]

I like your idea Giacomo. First of all it is much better than using aria-roledescription. Through the latter the AT-user does not know which key shortcuts are valid for the "new" widget role.ddition to aria-valuetext? And if so, do we have to here "on"/"off" in addition to the value of aria-valuetext?
Question: What with aria-checked on switch role? Do we have to use it in

[giacomo-petri]

@MarioBatusic,

as per specifications, the aria-checked attribute is mandatory. In the context highlighted by Scott, the attribute is consistently checked, given that the switch button doesn't toggle a function on and off but rather allows selection between two options, akin to a radio button.

However, the "switch" role lacks a direct counterpart in native HTML. Consequently, one might contemplate that in specific scenarios involving switch buttons, the aria-checked attribute may not be obligatory. Yet, I am not inclined towards this option due to the potential for confusion.

In my perspective, the aria-checked value should invariably be set to "true" in such scenarios, with emphasis on the author responsibility to set an appropriate aria-valuetext attribute value (and to update it when appropriate).

I want to underscore my endorsement of the significance of addressing the situation brought to attention by Scott.

While the current on/off state of switch buttons serves a purpose, developers could achieve a comparable outcome using a checkbox (where "on/off" equates to "checked/unchecked"). Although the presentation may differ slightly across technologies, the functionality/output and keyboard operability remain consistent.

This distinction is crucial for switch buttons that encompass two distinct values rather than a binary on/off state. Presently, there is no efficient way to create a switch button with two custom values, aside from resorting to radio buttons. However, this introduces a disparity between the displayed information and its behaviour, particularly concerning keyboard operability. Unlike switch buttons operated with the spacebar, a set of radio buttons can be navigated using arrow keys.

[giacomo-petri]

After some thoughts, do we really need the switch role at all?

Imagine, for a moment, that an element designated with the switch role not only responds to the spacebar but also accommodates input from the arrow keys.

In such a scenario:

• Treating a "standard" on/off switch button as a checkbox allows users familiar with checkbox semantics to operate it with the spacebar. Simultaneously, users attuned to the visual aspect of the element can employ both the spacebar and arrow keys. The potential inconsistency of checkboxes operated with arrows is unlikely to pose challenges to operability, since visually the element is presented as a switch button.
• Similarly, a customized switch button (e.g., cm/inches) could be semantically treated as a radio button. Users familiar with radio semantics could operate it with the arrow keys, while those relying on the visual experience might use the spacebar. Again, any inconsistency with the spacebar operability compared to default radios is unlikely to significantly impact the user experience.

Effectively handling switch buttons in alignment with their visual representation appears to be a matter of adhering to potential "new" best practice.

But at this point, again assuming that a switch button can function seamlessly with both the spacebar and arrow keys, it prompts the question: when is the essential use of a switch button truly warranted? This consideration becomes even more pertinent, given that there is no HTML element specifically corresponding to this role.

[giacomo-petri]

Disregard the previous feedback as it is inaccurate. Screen reader users may inadvertently interact with the "already selected" radio button, leading to an unintended activation of the "unselected" option.

[giacomo-petri]

While working on an initial draft to implement the discussed idea, I noticed that the aria-valuetext attribute, as it currently stands, is overly tailored for range widgets.

Thus, there are two potential paths forward:

1. Introduce a new aria attribute specific for the switch role.
2. Enhance the flexibility of the existing aria-valuetext attribute.

While the first option appears simpler initially (from a writing specs point of view), I believe it may not be sustainable in the long term.
Consequently, I began outlining a proposal for the second scenario. However, I realized that by making the aria-valuetext attribute more flexible, it could also accommodate scenarios such as aria-colindextext and aria-rowindextext, making these attributes redundant and overly specific.

Does the group feel that this proposal is in line with our objectives? If so, I will proceed with it; otherwise, I will revert to the first option.

[spectranaut]

Discussed at length in today's meeting: https://www.w3.org/2024/02/29-aria-minutes.html#t06

There is still some interested in using aria-valuetext, and a suggestion for aria-statetext. Perhaps one next step would be proposing the actual html mark up that needs this features, so we can discuss that specific case. In the notes above there is a link to: https://webkit.org/blog/15054/an-html-switch-control/

[scottaohara]

the webkit blog post has examples of where this would be useful (you do need safari tech preview to properly experience/see those demos) - and also demonstrate some issues with not considering how to treat the visible 'state' content that people try to add to custom switches now, via CSS content.

So per the demos with the visible "on/off" text, when the current webkit implementation of <input type=checkbox switch> is not named, the CSS pseudo content becomes the accessible name. You then get "on off" as the name. And then either singularly "on" or "off" announced again as the state. If you label these demos though, the CSS content is ignored because the label/aria-label(ledby) has higher priority in the accname algorithm. So then this pesudo content is entirely ignored.

But then there's also the day/night switch demo (daylight switch) - this example doesn't use CSS pseudo content (and like the rest of the demos in the webkit post, lacks a label), only using the visual graphics of "day time" or "night time" to represent state, so it's exposed as an unnamed switch with an on/off state.

The issue here becomes which is which? is "on" daytime? nighttime? People that create these designs want the single-element behavior of a checkbox/toggle button, but they want to convey the choices that a 2-item radio group would have been "more suitable" to expose. One needs to actually understand these nuances, so to "do this right" with these default on/off states, the content author/designer would have to know how to write a good label so one can infer what on/off mean. E.g., "enable dark mode" - where "on" can be inferred as it being enabled, and "off" can be inferred as being the opposite (so light/daytime).

But commonly, that isn't what ends up happening. You instead get a label for the switch like "Choose theme" or "Mode'. Something that requires one can see that the state of the switch is conveying ( to Jame Nurthen's point ) the human understandable value of what they've chosen. "on" and "off" don't do that.

To be honest, the only ways I can think of to "solve" this issue with HTML alone, specifically under this context of repurposing the existing checkbox input, is to either:

1. create specific rules about how to implement/use existing css psuedo content to convey the custom state you want (e.g., only have one pseudo element exposed to the a11y tree at a time. or UAs need to figure out a way to know what state the switch is in and somehow match that up with the pseudo content that matches the state...somehow... with magic and heart ache)
2. create new specific pseudo elements specifically for the text replacements for the on/off states (and UAs to ignore the rest of the pseudo content / inform developers that they should not rely on the other pseudo content to convey their state/be exposed at all to AT). like input[switch]:on { content: 'night' } input[switch]:off { content 'dark' }
3. ignore all pseudo content and instead create attributes where developers can add their own text alternative strings for the 'on' and 'off' states - which the pseudo content could then leverage to visually populate that text (though the pseudo content would still be ignored itself)
   so something like

<label for=s>name</label>
<input type=checkbox switch onstate=night offstate=day>

input[switch]:checked::before {
  content: attr(onstate);
}

per the above, anyone can put whatever they want into the CSS pseudo content, even pulling the text they want directly from the attributes i made up. but the CSS content would be explicitly ignored, and the attribute values themselves would be what was passed to the a11y API.

but, giant shrug... i'm sure someone could punch holes in that for why it won't work. and that's fine if they can come up with something better. So, by all means. I'd be really happy if others could give this thought and devise an elegant solution.

edit: made a webkit bug so that they can be aware of this/the current issue with the implementation as well - https://bugs.webkit.org/show_bug.cgi?id=270377

[aardrian]

I had not seen the Safari demo prior to the call. The dark/light is, IMO, a pretty sound use case for how this will be used (never mind that dark/light should be a tri-state that lets the user pull from their own prefs).

I feel very strongly that CSS generated content / pseudo-content is the wrong path here. Of the three options @scottaohara suggested (I lack creativity to come up with more right now), the third seems best since it puts the content into the control itself.

To carry this to a bit of an extreme, if we need to map those values to something within ARIA (is this a thing we do here?) then perhaps aria-valuemin and aria-valuemax for the two possible states. Then aria-valuenow can echo the selection. Essentially treat the switch as a range and loosen aria-valuemin and aria-valuemax in the switch context to allow non-numeric values.

Localization will be a concern regardless.

[MarioBatusic]

By all these possible solutions we have to avoid introducing different text content for "on" and "off" values visually (CSS) and in the accessibility tree (possibly new HTML attributes of te input element with type "checkbox" switch. The reason is that not only screen reader users but also speech input users commands rely on the names in the accessibility tree and these should not differ from the visual contents (CSS). So we need a better HTML solution that supports accessibility itself. But unfortunately I don't know the solution.

[annevk]

I've retracted the light/dark demo: WebKit/WebKit@58cbb3a.

It does not illustrate a switch, but rather a toggle or cycle button. https://developer.apple.com/design/human-interface-guidelines/toggles goes into this as well to some extent. I think we should consider an HTML control for toggle/cycle button as a separate feature: whatwg/html#10206. As you all highlight a toggle/cycle button's API and semantics are quite different from a switch.

[spectranaut]

Discussed briefly in yesterdays meeting: https://www.w3.org/2024/04/04-aria-minutes#t08