WCAG Level

Level A

Priority

Medium

Pages/screens/components affected

• Login

Description

When content is presented in a way that implies it has a particular structure, like headings that break up sections of content, but the same structure is not there in the HTML, it makes it difficult for anyone who cannot see the intended structure to navigate and understand it. Headings should have levels that represent their place within the hierarchy without skipping levels.

While the heading levels for some variations of the Login component are correct, for others they are either incorrect or lack the ability to be configured when placed into the context of a page.

User impact

Screen readers depend on HTML for information about the structure of content. Working in conjunction with the browser the screen reader takes information from the HTML and uses it to convey the structure/relationships to users. When HTML markup is used inappropriately, screen readers give users the wrong information about the content or the structure of the document.

Required solution

Ensure that headings are used in such a way as to represent the hierarchy of content within the document.

Implementation guidance

The Login form has several variations, but they all have the same basic heading structure.

• The title, when provided, is an <h1>
• The form heading ("Log in" by default), is an <h2>
• The error messages heading, that appears after the form heading, is an <h5>

This can be seen in the Validation example:

In most cases, the Login component is likely to be used on a page of its own or as a modal dialog. In these circumstances heading levels of 1 and 2 for the component title and the form heading respectively are appropriate. However, in any other circumstance, for example including the login form within a page's sidebar, these heading levels are unlikely to be appropriate. The example page is a case in point: each version of the Login component follows either the <h1> of the page or an <h2> for the sub-sections.

Additionally, the heading for the error messages, and <h5> following and <h2> by default, is always incorrect and should be an <h3> in that context.

Ideally it should be possible to configure the initial heading level from which other headings within the component are derived. The level of the form heading will vary depending on whether there is a separate title provided for the component.

Alternatively, the heading level for the error message should be corrected and the component recommended for use only when it is the main content of a page if the component has a title, or content that is one level below the page's main heading (to account for the form heading's <h2>) when the component does not have a title.

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 website for instances of the same issue:

1. Identify headings within the component
2. Make sure each heading has a heading role and a level that represents its place in the document hierarchy

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 1.3.1 Info and Relationships (Level A)

More information

• W3C WAI-ARIA Authoring Practices 1.1 Disclosure (Show/Hide)

Test data

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