details: heading level cannot be specified for elements with heading role

[TetraLogicalHelpdesk]

WCAG Level

Level A

Priority

Medium

Pages/screens/components affected

• Details

Description

A control's role conveys to assistive technologies the purpose - and expected interaction or effect - of the control. States and properties convey further information.

The heading role indicates that an element is considered a heading within the structure of the document, equivalent to a native HTML heading element (<h1>, <h2>, etc.) For elements with role="heading" the level is defined with a aria-level attribute, with a value of "1", "2", etc., through to "6" for the equivalent of an <h6>. Although the aria-level attribute is not required, when it is not present the default heading level is "2", equivalent to an <h2> element.

Just taking the content of the documentation page for details into account, the preceding heading for each example is an <h3> (<h3>Summary</h3>, <h3>Content</h3>, etc.). This means that the heading structure of the page, with a heading level 2 within a section with a heading level 3. The correct heading level in this specific cases is 4.

<div role="heading">
  <div role="button" part="summary" aria-expanded="true" tabindex="0">
    <span part="toggle"></span>
    <span part="summary-content"><slot name="summary"></slot></span>
  </div>
</div>

The API lacks a way of setting the heading level so it is not possible to ensure that the component's heading has an appropriate level for its place in the document. There are three possibilities for resolving this.

The first is to remove role="heading" from the component. While it is valid for a heading to be used in this way, it is more common in an Accordion pattern. Details patterns, such as the W3C WAI-ARIA Authoring Practices 1.1 Disclosure (Show/Hide), do not wrap the button control in a heading.

The second is to add to the component's API so that it is possible to add a heading level. The resulting markup would look like:

<div role="heading" aria-level="3">
  <div role="button" part="summary" aria-expanded="true" tabindex="0">
    <span part="toggle"></span>
    <span part="summary-content"><slot name="summary"></slot></span>
  </div>
</div>

where the value for aria-level is any integer value 1…6. If this is not required then the default heading level of "2" for role="heading" should be noted in the component's documentation.

The third approach, which would make reusing code with the similar Accordion component easier, would be to make the heading optional. This could be by not adding the role if no heading level is passed to the component's API or by adding a property that can be passed to the component.

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.

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