Skip to content

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

Closed

Description

@TetraLogicalHelpdesk

WCAG Level

Level A

Priority

Medium

Pages/screens/components affected

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.

The expand / collapse control for the Details element with text of "Contact information"

<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

More information

Test data

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions