Clarification on 4.1.2: setting states, properties and values programmatically

[babielmam]

For all user interface components (including but not limited to: form elements, links and components generated by scripts), the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies.

I would like to have some clarification on the highlighted part of 4.1.2 Name, Role, Value.

When we speak of user interface components, we usually also include widgets that serve a distinct function. For example tabs are used as a way to switch between contents. They are thus seen as a single user interface component. Other examples include collapsible elements, complex custom-made select's with autocomplete, etc.

In these examples the state of the user interface component can be set by the user. For example they can select a tab from all the tabs and the content switches to the selected item. In a collapsible element they can click the title and the initially collapsed content is shown.

Let's imagine, that these changes are then reflected in the HTML attributes of the element such as aria-expanded, aria-selected, etc.

Does this fulfill the highlighted part of the SC? The attributes can of course be altered directly without user input by just changing the HTML attributes.

Or does the SC rather ask, that the programmatically set states, properties and values be correctly reflected in the user interface component? This may put a large part of the web at risk of failing this SC, because it essentially asks for a two-way binding between HTML attributes and actual function of the UI component. In most cases, I would guess, the attributes like aria-expanded are rather a reflection of the output triggered through user input, but not a way to manipulate the component.

I see, there may be simple components, like collapsible elements, where you can style them with CSS in a way, that when there is [aria-expanded="true"], the content is shown. On the other hand, there are complex components, that involve a lot of JS workload with a lot of DOM manipulating, where setting the appropriate ARIA property at the end is just one of many steps.

[yatil]

Or does the SC rather ask, that the programmatically set states, properties and values be correctly reflected in the user interface component?

It does not. (You might run into other failures of SCs when the states/properties/values do not reflect the current state.)

[babielmam]

Thanks, @yatil!

What is the benefit of having that requirement in the SC, then? I mean, when using HTML, you basically can set states/properties/values programmatically anytime, even if they are not set by the author at all. I don't see any benefit for users, unless the programmatic changes are also reflected in the UI component itself. Am I wrong here?

Also, what other SCs may fail? I only remember SCs where something is required to be programmatically determined.

[JAWS-test]

In my opinion, the first sentence of 4.1.2 is worded incorrectly because it should say:

name, role, states, properties, and values can be programmatically determined;

instead of:

name and role can be programmatically determined

Restricting states, values etc. to those that can be changed by the user and only outputting them by AT when they are changed is wrong, because (for exmaple) a form field with disabled attribute cannot be changed, but the value and state disabled must still be programmatically determined

[babielmam]

In my opinion, the first sentence of 4.1.2 is worded incorrectly because it should say:

name, role, states, properties, and values can be programmatically determined;

I agree to that.

Restricting states, values etc. to those that can be changed by the user and only outputting them by AT when they are changed is wrong

I suspect there is a misunderstanding of SC's second sentence here, but I'm not sure if it's on your side or mine. I understand it to mean that there must be a way for AT to be able to adjust states, properties and values programmatically. The exception is that this should only be possible for states, properties and values that can also be changed manually by the user by other means. I explain this exception by the fact that, on the one hand, you don't want users of AT to be disadvantaged, but on the other hand you don't want the SC to demand additional functions. In my opinion, it makes sense to limit this to states, properties and values, as the role and name of a component are normally unchangeable.

In my view, however, this second sentence only makes sense, as described above, if the programmatic changes made by AT are also reflected in the UI component. Otherwise, what is the benefit to the user if the values in the accessibility tree say something different from the actual state of the component?

I could imagine that this second sentence of the SC would be helpful for AT that not only simulates user input to interact with the page, but also intervenes in the code of the page. But I don't know if there is such an AT and if that would be a good idea.

[GreggVan]

I think this got messed up somewhere in translations

what it should say is that

name, role, states, properties, and values can be programmatically determined; AND that they can be programmatically set when it is possible for users of the standard interface to set them.

so there is no restriction on the programmatic READ but the programmatic WRITE is limited to things that all other users can do from the standard interface.

best

[JAWS-test]

@GreggVan What do you mean by translations? I read the original: https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html

For all user interface components (including but not limited to: form elements, links and components generated by scripts), the name and role can be programmatically determined

only role and name

states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies.

now also states, properties and values - but limited to changes.

It is clear that only "states, properties, and value" should be changeable with AT, which are changeable for all. But "states, properties, and value" is clearly missing in the first part, because they must be perceptible with AT even without a change

[yatil]

I think this feels like hair splitting. Name and role are mentioned separately because they don’t change. States (etc.) are not included because UI elements do not always have determinable states. Think of a link as a simple example. That’s why the they are not in the first sentence.

states, properties, and values that can be set by the user can be programmatically set;

This means, add your states (etc.) too! To allow communication of the state as the user sets it to AT. It’s not limited to changes, it’s limited to items that can be changed. If the user has no way to change a state, they arguably have less of a need to be informed about the state.

and notification of changes to these items is available to user agents, including assistive technologies.

The semicolon after ”programmatically set” mages this a separate clause.

Back to the initial question: Most SCs have no bi-directionality. 1.3.1 Info and Relationships asks that visual information is programmatically available, however not all programmatically available information needs to be visually apparent. The same goes here. The SC is only concerned about the underlying code. If you have a checkbox that is checked and its state is properly set, the SC is passed. You will run into failures of other SC (for example, Consistent Identification or Info and Relationships), but for this SC, its only important that the state is communicated programmatically.

[JAWS-test]

@yatil SC 4.1.2, as worded, does not require states, properties, and values to be transmitted programmatically unless they have changed. I do not consider this to be splitting hairs, but rather an very incorrect statement. I would only consider this to be unproblematic if missing transmission of states, properties, and values is evaluated in SC 1.3.1 - because this is usually visually transmitted information. A read-only field, which often does not differ visually from an operable field, could then not be evaluated if the read-only status is not transmitted programmatically. I dare to doubt that the majority of WCAG testers will assess the lack of transmission of states, properties, and values in SC 1.3.1. Most of them will evaluate it at SC 4.1.2 because they haven't actually read the SC, as I have myself. And the distinction between an initial state or value and a changed state or value is not made by WCAG itself, see https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA5

[yatil]

SC 4.1.2, as worded, does not require states, properties, and values to be transmitted programmatically unless they have changed.

As shown above, this is nowhere found in the SC. There is no passive language in there. All clauses are separated by semicolons, making them individual requirements.

Here’s a rewrite/reformat with bullet points that makes it clear:

For all user interface components (including but not limited to: form elements, links and components generated by scripts):

• the name and role can be programmatically determined;
• states, properties, and values that can be set by the user can be programmatically set; and
• notification of changes to these items is available to user agents, including assistive technologies.

There is nothing that says, “states, properties, and values that can be set by the user can be programmatically set after they have changed”. The SC says, “if it's something that the user can change, set it programmatically”.

[yatil]

And the distinction between an initial state or value and a changed state or value is not made by WCAG itself, see https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA5

Can you elaborate? Here the aria-pressed is set initially, not on change, and aria-valuenow is also set initially, not only when a change happens, which agrees with me. (Also techniques are famously non-normative.)

The readonly example cannot be changed by the user, so it does not need to be communicated, for example if the readonly field is styled like it looks like regular text, that would be completely permissible. If it looks like a textfield that can only be read, it’s a 1.3.1 failure.

[JAWS-test]

@yatil

There is nothing that says, “states, properties, and values that can be set by the user can be programmatically set after they have changed”. The SC says, “if it's something that the user can change, set it programmatically”.

I didn't say that. I said that the SC does not require states, properties and values to be programmatically perceptible. I'm not interested in the change aspect. That is correctly formulated in the SC.

[yatil]

Then we seem in agreement‽ I'm very confused. Because it clearly says that states need to be set, if the user can change it.

[yatil]

And if they are set, they are perceptible, too. 🤷‍♂️

[GreggVan]

I think the key here (as pointed out above) is to remember that

• it starts out with "that can be set by the user".
• That means the typical user can perceive it (or else the typical user could not set it)
• That means it is already presented on the page -- and all of the other provisions will already have made sure that it is programatically determined (or determinable).

Now - if it turns out that the typical user can set something but not perceive the new setting (for example there is some open-loop system where you can set the vote counter up -- but no user can see what the vote counter reads) then the person with a disability should also not be able to "perceive" the new setting - or they would (for example) have access to voting count they should not. (and if they compared values of people voting before and after someone votes they would know how that person voted).

The bottom line is that accessibility means equal access -- not more access.

• so if everyone else can set something - then people with disabilities should be able to set it (this provision)
• if everyone else can see the status of something - then people with disabilities should be able to see the status (covered by the other SC that ensure that everything presented to "everyone else" is also perceivable by people with disabilities)
• and if NOT viewable by others - then it should not be viewable by people with disabilities. (this does not include alternate content that is provided specifically to people with disabilities as part of accessibility - that of course is presented to those who need it -- but not necessarily to everyone)

Does that help?

[JAWS-test]

@yatil

Then we seem in agreement‽

I don't think so. Imagine a div element that represents a checkbox. According to 4.1.2, the role and name must be transmitted, i.e. the div needs a role=checkbox for the role and an aria-label for the name. However, the wording does not require aria-checked, although the checkbox always has a status and it would be important to transmit this.

[JAWS-test]

@GreggVan

if everyone else can see the status of something - then people with disabilities should be able to see the status (covered by the other SC that ensure that everything presented to "everyone else" is also perceivable by people with disabilities)

Do you mean SC 1.3.1? I mentioned this above and at the same time doubted that this was intended by WCAG.

ARIA5 belongs to 4.1.2 and not to 1.3.1 and says:

Check that the required states and properties for the role are present.

[yatil]

@JAWS-test So we are in agreement! As the checked status can be set by the user, it has to be set to the UI element.

[JAWS-test]

@yatil

@JAWS-test So we are in agreement! As the checked status can be set by the user, it has to be set to the UI element.

No.

the name and role can be programmatically determined;

not applicable, as only name and role are mentioned here

states, properties, and values that can be set by the user can be programmatically set

does not apply, as this is only about the operability of the checkbox with AT and not about the perceptibility of the state

and notification of changes to these items is available to user agents, including assistive technologies.

does not apply, because here it is only about the perceptibility of a state change, but not about the initial state of the checkbox before the change and also not about the state after the change (i.e. here it would be sufficient to indicate the state change via live region, but it is not necessary that the checkbox has an aria-checked before and after operation).

[yatil]

states, properties, and values that can be set by the user can be programmatically set

does not apply, as this is only about the operability of the checkbox with AT and not about the perceptibility of the state

How do you set a state in an imperceptible way? If aria-checked is set, it's perceivable, also this is not in the perceivable principle but in robust. I think you're intentionally try to read into this something that is not in there, which… you do you.

[JAWS-test]

@yatil

states, properties, and values that can be set by the user can be programmatically set

The sub-sentence says nothing about perceptibility, only that something can be set programmatically. The checkbox, which is built from a div, therefore does not require aria-checked, because the state is a visual representation (checkmark in the square or not). And this sub-sentence says nothing other than that I can also change this visual representation programmatically. I can simply solve this using the correct JavaScript event handlers. There are also elements that are not operable at all and have a state, such as a deactivated checkbox.

[yatil]

The checkbox, which is built from a div, therefore does not require aria-checked, because the state is a visual representation (checkmark in the square or not). And this sub-sentence says nothing other than that I can also change this visual representation programmatically.

How is it programmatically set if you do not set it programmatically? Programmatically set is a defined phrase that says:

set by software using methods that are supported by user agents, including assistive technologies

How can you read that as setting the visual information only is sufficient? I really want to understand where the disconnect is here, so we can make sure to fix it.

[babielmam]

I appreciate the discussion, but I assume it would help, if you raise a separate issue for that discussion, as I don't see a connection to my initial question anymore.

Coming back to my question, it has been answered. But my follow up question was somewhat left unanswered: https://github.com/w3c/wcag/issues/3962#issuecomment-2227750573

What is the benefit of having that requirement in the SC, then? I mean, when using HTML, you basically can set states/properties/values programmatically anytime, even if they are not set by the author at all. I don't see any benefit for users, unless the programmatic changes are also reflected in the UI component itself. Am I wrong here?

Also, what other SCs may fail? I only remember SCs where something is required to be programmatically determined.

[JAWS-test]

@babielmam You are right, only your question should be answered here. Unfortunately, I don't really understand your question. Do you mean the following:

• a checkbox has the visual state checked or not checked (represented by a square with a checkmark or an empty square)
• a checkbox has the programmatic state checked or not checked by aria-checked=true/false
• a checkbox has the system state checked or not checked, which means that the status is sent to the server correctly when the form is submitted

Now the part of 4.1.2 can mean the following:

• programmatically I can change the visual state
• programmatically I can change the programmatic state
• programmatically I can change the system state
• programmatically I can change all 3 states (*)
• programmatically I can change a combination of 2 of the states
• if I change a status not programmatically, but e.g. with the mouse, then all the other two also change (*)
• if the web application changes one status, the other two also change (*)

I have marked with an asterisk the options that I assume should apply and be covered by SC 4.1.2, even if SC 4.1.2 does not formulate this so precisely. As you have seen from the discussion between yatil and myself, it is actually completely unclear what SC 4.1.2 means

[babielmam]

Ok, let's stick to your example with the checkboxes: Assuming, we have a custom checkbox. It has a visual state (checkmark made with CSS) and a programmatic state (aria-checked). It also has a "system" state as you name it, but that is not really relevant here.

SC 4.1.2 gives following criteria.

1. name and role can be programmatically determined
2. states, properties, and values that can be set by the user can be programmatically set
3. notification of changes to these items is available to user agents, including assistive technologies

Assuming we work correctly, number 1 and 3 is met successfully.

Regarding number 2: The state of the checkbox can be set by the user by clicking the checkbox. A visual indicator is added or removed by using a CSS class. The aria-checked-attribute is set as well, when the user clicks the checkbox.

In order to programmatically set the state, the aria-checked-attribute must be modified by the user agent or AT. Since this can easily be done, sentence 2 should be successful as well. It is clear from @yatil's first answer that it is not necessary for the programmatic change to be visually reflected in the checkbox. This means that after setting the state programmatically, the visual state (which works with CSS) is different from the programmatic state (which works with the attribute).

The questions I have are:

1. What is the benefit for the user having the possibility to programmatically set the state, but not seeing the change in state? Shouldn't the SC be more strict here?
2. What other SCs may fail, if you can set the state programmatically, but the change is not reflected visually?
3. Or does "programmatically set" rather mean, that e.g. any JavaScript snippet can be used to set the state? In that case it would be possible to also set the visual state programmatically, although it would be way more complex and there would be no one-solution-fits-all.

[JAWS-test]

It also has a "system" state as you name it, but that is not really relevant here.

This is very relevant because it is sent to the server when the form is sent. I know applications where I can use the mouse to set all 3 states I have mentioned, but with the keyboard or AT only aria-checked and possibly also the visual state, but not the one that is sent to the server. This is of course a big problem. This can happen because many frameworks use hidden HTML controls, but custom visual controls. When sending, the information from the HTML controls is sent to the server. An important task of the application is to pass on all information correctly to the hidden HTML control when the custom control is operated, regardless of whether it is operated with the mouse, keyboard or AT

[JAWS-test]

I assume that WCAG SC 4.1.2 "states, properties, and values that can be set by the user can be programmatically set" means that I can programmatically set all 3 states I mentioned, i.e. it should always be synchronous. But unfortunately the SC doesn't formulate this very precisely, which is why there was such a long discussion between @yatil and me.

Does that answer your question?

[JAWS-test]

By the way, the discussion area is better suited for such questions

[babielmam]

This is very relevant because it is sent to the server when the form is sent. [...]

Agreed, but if this fails, it is an implementation bug in my view. It primarily is not a concern for the accessibility of the UI component, as there can be other UI components where this SC applies and that don't send data to the server.

[...] means that I can programmatically set all 3 states I mentioned, i.e. it should always be synchronous [...]

This is in contrast to @yatil's first comment. Further, in the understanding document it is said, that "states" would be typically defined through other standards such as ARIA. As far as I know ARIA is not concerned about the visuals of a component. So this confirms @yatil's interpretation.

By the way, the discussion area is better suited for such questions

I thought that an issue would be more suitable, since the outcome may lead to a change in the understanding document.

[JAWS-test]

Agreed, but if this fails, it is an implementation bug in my view. It primarily is not a concern for the accessibility of the UI component

No, it is clearly an accessibility error and even a very serious one if, for example, I only set the state of the checkbox with the screen reader so that the checked state is activated visually and programmatically, but the checkbox is transmitted to the server as non-checked, whereas with mouse or keyboard operation the transmission to the server works correctly.

This is in contrast to @yatil's first comment.

I don't agree with him on that. I am convinced that the intention of SC 4.1.2 is that all 3 states are synchronous, are perceptible, can be changed programmatically and that the change is also perceptible.

yatil's comment sounds like the checkbox just needs to have aria-checked, but it doesn't matter if the value (true, false) matches the visually submitted state. If that were really the case, I could only check whether the visual state matches the programmatic state in SC 1.3.1, but I can't find anything like that in SC 1.3.1, so I assume that this always belongs to 4.1.2.

Further, in the understanding document it is said, that "states" would be typically defined through other standards such as ARIA.

In my opinion, the understanding assumes that a state is always transmitted visually (otherwise it is not a state). And if it is transmitted visually, then it must also be transmitted programmatically - so it must be synchronous. And I can then use ARIA for the programmatic transmission. See: https://www.w3.org/WAI/WCAG22/Techniques/aria/ARIA5

As far as I know ARIA is not concerned about the visuals of a component.

That is correct

I thought that an issue would be more suitable, since the outcome may lead to a change in the understanding document.

At the moment it's more of a discussion. If there is a result and a concrete update for the Understanding, it would be an issue

[JAWS-test]

Related: https://github.com/w3c/wcag/issues/686 and https://github.com/w3c/wcag/issues/2142

[yatil]

Like 1.3.1 Info and Relationships, 4.1.2 Name, Role, Value is not reversible.

[babielmam]

@yatil thank you for the clarification. In your initial answer you said, that one might run into issues with other SCs, if the programmatic change is not reflected visually. Which other SCs do you have in mind? I assume that it cannot be 1.3.1, because it is not reversible. But other SCs don't come to my mind, either.