aria-describedby, verbose vs. concise and arbitrary 'state' information

[brennanyoung]

There is a semantic aspect of aria-describedby which I think may get lost with the current spec copy, or perhaps I misunderstand something. Here are a couple of rather common use cases by way of illustration:

• A notifications button on a social media site which includes an additional 'badge' displaying the number of unread posts.
• A shopping cart on an e-commerce site which includes an additional 'badge' displaying the number of items in the cart.
• A process queue of items in a dashboard whose completion state is indicated with a small icon: Pending, processing, done.

These cases seem semantically identical.

I assume that the most correct way to associate the item count 'badge' or the process state icon with the element is to point to the id of the badge/icon with aria-describedby - is that right?

If so, I am concerned that the spec for aria-describedby states

The aria-labelledby attribute is similar to the aria-describedby in that both reference other elements to calculate a text alternative, but a label should be concise, where a description is intended to provide more verbose information.

(Emphasis mine). What bothers me here is that the item count in both the cases mentioned above is just a single value, and is certainly concise, rather than verbose. Strictly speaking, it's state, pure and simple. The current wording might lead authors to look beyond these attributes for expressing state values, or to 'hack' the accessible name to include this additional (and semantically distinct) text.

I strongly believe that concatenating an accessible name with semantically distinct strings that express state is an anti-pattern which indicates that a role or relationship may be missing. Similarly, it's preferred to rely on aria-pressed to express the state of a toggle button, rather than manipulating the accessible name.

I suppose that what is intended by the words "concise" and "verbose" is that aria-describedby calls for 'flat' strings (i.e. without further semantic variation).

The point appears to be to distinguish this attribute from aria-details which can point to rich text ("verbose"). Yet aria-details is not mentioned as a possible alternative in the spec for aria-describedby, in the useful way that certain other parts of the spec guide authors to make the other appropriate choices where there may be similarities in the semantics.

The distinction is made in the ARIA annotations spec. I approve of this clarity, and hope the distinction will be included in the 1.3 spec for aria-describedby.

So there are two problems here, one is to guide readers of the ARIA spec to make the correct choice between aria-labelledby, aria-describedby and aria-details based not on the razor of verbose/concise but on whether the indicated element is

• The accessible name of the element (aria-labelledby)
• A flat string describing the element (aria-describedby)
• A rich text structure describing the element (aria-details)

... and secondly, to make it fully legitimate that concise 'state' annotations (such as the item counts or process state in the examples above) are valid use cases for aria-describedby - and I don't think that APG examples will be quite enough to make this unambiguous.

Or maybe I've got this all wrong, and someone could clear up my doubt about this. Is aria-describedby the wrong thing for arbitrary 'state' information associated with an element? Do we need something else?

[stes-acc]

It depends.

aria-describedby and aria-description are also for describing custom states (for instance a "read" state of a message in a feed).

Never use aria-label or aria-labelledby for that since a label is NOT a state.
2nd reason is that AT typically speaks descriptions like properties AFTER labels and object values and you would destroy that pretending states as labels since they then come BEFORE all else in speech order which is wrong.

If ARIA spec is not clear here it should be enhanced.

BTW, for a number in a shopping basket icon button with badge this is not so clear.

You can code this with

aria-label="Shopping basket" aria-description="Contains 2 Items"

with yields speech output as

"Shopping basket button contains 2 items"

The info may be better read in a continous way as label which makes sense in this case. Here I can imagine an

aria-label="Shopping basket with 2 items"

and speech output

"Shopping basket with 2 items button"

as more natural textual representation of the content.

[brennanyoung]

Thank you! That's how I understood it too.

Yes, I think the spec should be clearer on this point, and state should be explicitly contraindicated under the spec for aria-label and aria-labelledby, and explicitly mentioned as intended use cases under aria-describedby and aria-description.

The words "verbose" and "concise" are therefore misleading, since the kind of UI state we are talking about is typically very concise indeed.

[JAWS-test]

I think the badge can be part of the Accessible Name or the Accessible Description, depending on the context.

For example, if an icon for unread messages is only displayed when there are such messages, then it would make sense to use the icon with the number as part of the Accessible Name ("3 unread messages").

If the icon for the messages is always displayed and the badge only when there are new messages, then the following would make sense:

• Accessible Name: "Messages"
• Accessible Description: "3 unread messages" or "New: 3". Just passing the number may also be ok, but not always if there are e.g. different badges (showing e.g. new and unread messages separately)

I agree with you, though, that a description doesn't always have to be verbose. It can be shorter than the label, e.g. even if it contains operating and input instructions.

More important would be the distinction:

• Accessible Name: mandatory, uniquely identifies the element. It should be concise.
• Accessible description: not mandatory, additional information that is not necessary for understanding and operation (e.g., because the screen reader user can deactivate the output of the description). It can be verbose, but should be as concise as possible

[stes-acc]

I strongly disagree to the general statement that accessible descriptions should NOT contain additional information necessary for understanding and operation.

A lot of custom properties out in the world ARE important for operation and is is not a good approach to put these in Label "just because people cannot switch that off".

[brennanyoung]

Accessible description could be either, where aria-describedby might be more 'essential' to operation or understanding than aria-details. Is that fair?

[stes-acc]

Accessible description could be either, where aria-describedby might be more 'essential' to operation or understanding than aria-details. Is that fair?

Makes some sense for me. Precedence rules for semantic importance are also within the APG realm, I think. They have a separate GitHub for that:

ARIA APG

[JAWS-test]

@stes-acc

custom states: Never use aria-label or aria-labelledby for that since a label is NOT a state.

I wouldn't say that: if I have a light bulb that allows me to turn on, turn off, and dim lights, then its label might be:

• Light on
• Light off
• Light dimmed

[stes-acc]

Interactively, this could be also the VALUE of a slider-like thing or a classy RadioButton Group selector with the actual value being set on user choice.

So your example is exposing a display-only version of that value. Of course, this output may be plain text which maps better to label-like things.

My examples are for interactive things. As said, it really depends on the use case.

[stes-acc]

jaws-test says:

@stes-acc
I strongly disagree to the general statement that accessible descriptions should NOT contain additional information necessary for understanding and operation

Power users can disable the description output in the settings because they already know how to operate elements or what values are expected for elements. Therefore I would say that all absolutely necessary information of the element should not be conveyed in the description (but by name, role, value and status) - and the description should contain secondary information.

@JAWS-test
It is all about custom states placement. Should be NOT in Label by default.
Apologies for comment deletion, was mistakingly done.

[brennanyoung]

Just want to connect to #711

[brennanyoung]

One conceptual problem I see with "hacking" state into the accessible name is that it takes us away from the principle that the name uniquely identifies the element. Is this not a problem?

[stes-acc]

It is, annother reason. In #711 it is also stated in the first comment:

"In my opinion, aria-labelledby should only be used for labels and never be used for the value. Label and value are different things."

So states do normally also represent values ( their own ones :-) ) and I see that in this sense.

[JAWS-test]

I think most of the time it's best to use the appropriate HTML elements/attributes or ARIA attributes for name, role, value, and description that will ensure that the information can be correctly submitted to the Accessibility API. However, if the issue is that I can't submit a custom status as a status because that status doesn't exist programmatically, then the status can be submitted in the name or description depending on the context (or even in the role via aria-roledescription if necessary). In some cases it may make more sense to use the name instead of the description, among other things because the description is not output when reading the content with the screen reader's virtual cursor.

[scottaohara]

I worry that this is veering into over-complicating things, particularly by thinking aria-valuetext might have a place here. Per the OP examples, a badge on a shopping cart link, or indicating you have X unread notifications isn't really a "state" or a "value". There is no "2 items in your cart" state for a link, nor does a button that invokes a panel containing a listing of notifications have a "value" equal to the number of notifications that are unread.

Again per the OP:

A notifications button on a social media site which includes an additional 'badge' displaying the number of unread posts.

why can't this just have an accessible name of "unread posts, X"? Visually i imagine this might be rendered as an icon with the number being the only visible text? Would consider this beneficial to include that text in the name then.

A shopping cart on an e-commerce site which includes an additional 'badge' displaying the number of items in the cart.

Similar to the above. accessible name "checkout cart, X items". Neither this nor the above's "badges" represent a value or state for the current control – they are referential to the state of other content.

A process queue of items in a dashboard whose completion state is indicated with a small icon: Pending, processing, done.

I actually don't have a clear understanding of what the UI would be for this, and can think of a variety of scenarios where different markup patterns (with or without aria) might be appropriate.

[JAWS-test]

It seems to me that we agree that the phrase.

where a description is intended to provide more verbose information.

is not quite correct, since a description need not to be verbose.

The question would be whether we can rephrase the sentence so that a description includes secondary information that may or may not be verbose

[brennanyoung]

X unread notifications isn't really a "state"

Oh! Could you explain why not? The spec for "state" says

A state is a dynamic property expressing characteristics of an object that may change in response to user action or automated processes. States do not affect the essential nature of the object, but represent data associated with the object or user interaction possibilities

(emphasis mine)

There is no "2 items in your cart" state for a link

Of course not, but the whole point of this thread is to discuss arbitrary (or custom) states which might be added to a standard element without affecting the essential nature (i.e. the role) of the object.

[stes-acc]

To be crystal clear, aria-valuetext has NO place here :) I don't know why this impression came up.

I also don't think we are overcomplicating things. We just need to have a clear advice which ARIA attribute is OK to put custom object properties in. Simple question.

If the answer to this is "none" this is not acceptable.

If the answer is "it depends", well then we need more use cases that makes the need for this more clear.

[brennanyoung]

The reason aria-valuetext came up is because the spec for the more appropriate alternatives leaves too much room for doubt.

[scottaohara]

For these use cases these aren't custom object properties. They're not descriptive of the buttons or links themselves, but rather what someone can expect to find in their associated content (e.g., disclosure widget panel, or on the page loaded after following the link).

Circling back to the OP. I've made a PR to adjust some of the wording to indicate that a description doesn't have to be verbose. I have not added anything to clarify how to communicate "state" here... I think these would be better topics for authoring guidance, and worry that adding in such nuance here goes beyond the scope of what the spec needs to clarify. We can, of course, discus that in one of the next WG calls when reviewing the issue/PR.