time-picker: Errors are not identified or described in text

[TetraLogicalHelpdesk]

WCAG Level

Level A

Priority

Medium

Pages/screens/components affected

• Time Picker

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.

We found one instance of an invalid time picker field in the documentation page which does not show any descriptive error messages. This may not necessarily be an issue of the component itself, but just of the documentation/examples provided.

For the Minimum & Maximum Value example, manually entering a time outside of the allowed range only leads to a change in colour of the field. No text-based error message is presented to the user.

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 that the Custom Validation example on the same documentation page does provide an appropriate error message.

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

[web-padawan]

This appears to be a docs issue. A fix would be to specify errorMessage for all the components that use constraints validation in corresponding examples.

[web-padawan]

We found one instance of an invalid time picker field in the documentation page which does not show any descriptive error messages. This may not necessarily be an issue of the component itself, but just of the documentation/examples provided.

Duplicate of #109 which was fixed by https://github.com/vaadin/docs/pull/2179.