custom-field: Errors are not identified or described in text

[TetraLogicalHelpdesk]

WCAG Level

Level A

Priority

Medium

Pages/screens/components affected

• Custom Field

Description

When an input error is detected (either client-side, or server-side), a clear error indication must be given to users. The error message/indication must clearly signal to the user that an error was detected, and - if necessary - what they need to do to resolve the error.

Per the definition in WCAG, an "input error" is information provided by the user that is not accepted. This includes:

• information that is required by the web page but omitted by the user, or
• information that is provided by the user but that falls outside the required data format or allowed values.

For example:

• the user fails to enter the proper abbreviation in a state, province, region, etc. field;
• the user enters a state abbreviation that is not a valid state;
• the user enters a non-existent zip or postal code;
• the user enters a birth date 2 years in the future;
• the user enters alphabetic characters or parentheses into their phone number field that only accepts numbers;
• the user enters a bid that is below the previous bid or the minimum bid increment.

In the custom field validation example, if a user enters a price amount, but not a currency, the text-based error message only refers to the "amount". This may not necessarily be issues of the component itself, but just of the documentation/example provided.

User impact

Without an explicit error indication, users may be unable to understand why a particular action, such as a form submission, failed. They may abandon the form altogether, thinking that the page simply is not functional. They may realise that there is an error, but not be able to work out specifically where the error occurred, or how to correct it, leading to a frustrating experience.

Required solution

Make sure that whenever an error is detected (either client-side, or server-side), the error is described to the user, generally, with a text-based error message, though in simple cases an icon/graphic may also be sufficient - for instance, to highlight required fields which have been left empty. Do not rely solely on cues like color changes on form field borders to indicate errors, as these don't provide sufficient context/information to users.

Note: beyond text, there are programmatic ways in which errors can be identified and described. User agents in general, and assistive technologies in particular, can use these programmatic ways to provide error information to the user. One example would be the use of aria-invalid="true" on an erroneous/invalid form field. However, WCAG 2.1 Success Criterion 3.3.1 Error Identification (Level A) is not concerned with the presence or absence of these - any issues relating to programmatic identification or errors fall under success criterion WCAG 2.1 Success Criterion 4.1.2 Name, Role, Value (Level A).

Error messages should be programmatically associated with their related form field/control, in order to satisfy WCAG 2.1 Success Criterion 1.3.1 Info and Relationships (Level A).

This solution must be applied to all instances of the issue identified within the test sample, then applied to all other instances of the same issue identified throughout the rest of the components, their variants, and the documentation website.

Test procedure(s)

Use these steps to confirm that the solution has been correctly applied to issues identified within the test sample, and to test the rest of the components, their variants, and the documentation website for instances of the same issue:

1. For all components in the page that accept user input, enter deliberately wrong values. If the components are part of a form that needs to be submitted, submit the form.
2. Verify that errors are indicated to the user in text, or using explicit icons (in simple cases, where errors don't require further explanation).

Definition of done

Complete all of these tasks before closing this issue or indicating it is ready for retest:

• All issues identified within the test sample have been resolved.
• The rest of the components, their variants, and the documentation website have been tested for the same issue.
• All issues identified throughout the rest of the components/website have been resolved or filed as new issues.

Related standards

• WCAG 2.1 Success Criterion 3.3.1 Error Identification (Level A)

More information

• W3C - Understanding Success Criterion 3.3.1: Error Identification

Test data

Test date: March 2021 Website: vaadin.com/components, vaadin.com/docs-beta

[rolfsmeds]

While the problem described above is really just an issue in the example (as the error message is created by the developer and could take both sub-fields into account), there's a more difficult issue that is not mentioned:

The error-message element is not programmatically associated with the sub-fields (as opposed to regular input fields whose <input> elements are associated with the error-message element using aria-describedby). So the custom-field would need a mechanism for creating the aria-describedby association between each input field and the custom-field's common error-message element. (Documentation should also show how to render an error message that accounts for all sub-fields simultaneously.)