Skip to content

General: Elements without a robust accessible name or role #153

Closed

Description

@TetraLogicalHelpdesk

WCAG Level

Level A

Priority

High

Pages/screens/components affected

Description

Without an accessible name, interactive controls will simply be announced as generic "link", "button", "edit" or similar by assistive technologies. Without a role the control will be announced only as text (if an accessible name is provided), or "Clickable" without any further information if the control is interactive but lacks an accessible name or role, or "Blank" if no information at all is provided in the accessibility API.

While the majority of controls have accessible names, the way they have been implemented with web components in some cases leads to an unusual situation. Although the accessible names of controls is consistently announced when using a screen reader's browse mode controls (use of arrow keys to navigate forward and backwards through the document, pressing the b key to navigate through button elements, etc.) when using the Tab key in some cases nothing is announced.

Similarly, the role of controls is inconsistently announced.

Beyond not announcing the name/role of the control, in some situations (for instance, using Chrome/NVDA, of iOS/Safari/VoiceOver) this can lead to the actual control not being operable - as browsers/assistive technologies don't perceive the currently focused component as being interactive, and hence don't activate it when users try to interact with it.

For example, the button component and other components that use it, such as the "Log in" and "Forgot password" buttons in the Login component, when focused using the Tab key in Google Chrome with NVDA announce only "Blank". Neither the role or the accessible name of the controls is announced. Using screen reader navigation keys, NVDA announces "Button Log in".

<vaadin-button part="vaadin-login-submit" theme="primary contained" tabindex="0" role="button">
  # shadow-root
  <div class="vaadin-button-container">
    <div part="prefix">
      <slot name="prefix"></slot>
    </div>
    <div part="label">
      <slot></slot>
    </div>
    <div part="suffix">
      <slot name="suffix"></slot>
    </div>
  </div>
  <button id="button" type="button" tabindex="0" role="presentation"></button>
  # end shadow-root

  Log in
</vaadin-button>

This is because although the outer element has tabindex="0" and is therefore focusable, and role="button" so it would be announced as a button, the focus management of the component moves focus from the <vaadin-button> element to the <button> element. This element has a role of presentation, so it is set to appear in the accessibility tree as a semantically neutral element. This is also why although there are two elements that are keyboard focusable, <vaadin-button tabindex="0"> and <button>, only one is focussed.

To demonstrate this, I added an obvious :focus style to the <button>:

button#button:focus {
  border: 8px solid red !important;
}

and disabled the styles to hide it off screen. The following image shows the unfocused element as a grey rectangle overlapping the right hand edge of the visible component.

The unfocused "Log in" button in the Details component, with visible button element

Pressing the Tab from the "Password" field sets focus not to the <vaadin-button tabindex="0"> element but to the <button> element as shown in the following image:

The focused "Log in" button in the Details component, with focus style of a thick red border on the button element

See a video recording of this focus behaviour.

While managing focus in this way means that that there is only a single tab stop for keyboard users, it means that for screen reader users, who will likely be using the Tab for navigation as is usual when interacting with forms (see Understanding screen reader interaction modes by Léonie Watson for an explanation of forms/focus mode), will not hear either a role or name for the component.

Although accessible names are being provided, which in most circumstances would be sufficient to pass WCAG 2.1 Success Criterion 4.1.2 Name, Role, Value (Level A), WCAG 2.1 requires that techniques used must be accessibility supported in order to qualify for conformance. This means, in this case, that any method of providing an accessible name must be implemented in such a way that user agents including assistive technologies can understand and use.

Note that the JAWS screen reader handles this differently. JAWS makes more use of heuristics based on the information in the accessibility tree that it is aware of. When encountering a focusable element with no role or accessible name it may look at adjacent or ancestor nodes to determine the information it is lacking. This is the case here, but the consequence is that the information is duplicated, once for the <button> element and once for the <vaadin-button role="button"> element, resulting in "Log in button, Log in button" and "Forgot password button, Forgot password button.

In this case it is unclear why the <button> element is necessary other than, perhaps, to use the default click and keyboard handling that the native element provides.

There are two possible solutions. The first is to remove the <button> element and rely entirely on the <vaadin-button> element. It has the correct role, is keyboard focusable due to the tabindex="0" attribute, and has an accessible name due to the child element text node which is inserted into the <slot> within <div id="label"></div>.

The result would be:

<vaadin-button part="vaadin-login-submit" theme="primary contained" tabindex="0" role="button">
  # shadow-root
  <div class="vaadin-button-container">
    <div part="prefix">
      <slot name="prefix"></slot>
    </div>
    <div part="label">
      <slot></slot>
    </div>
    <div part="suffix">
      <slot name="suffix"></slot>
    </div>
  </div>
  # end shadow-root

  Log in
</vaadin-button>

i.e. the same output but without the <button>. With this approach you will need to handle all events, including ensuring that the control can be activated with both Enter and Space key presses and that page scrolling is disabled when the Space key is pressed.

The second approach is to use a <button> element as a container rather than using a <div> element, as follows:

<vaadin-button part="vaadin-login-submit" theme="primary contained">
  # shadow-root
  <button class="vaadin-button-container">
    <span part="prefix">
      <slot name="prefix"></slot>
    </span>
    <span part="label">
      <slot></slot>
    </span>
    <span part="suffix">
      <slot name="suffix"></slot>
    </span>
  </button>
  # end shadow-root

  Log in
</vaadin-button>

In this version, the role and tabindex attributes are removed from the <vaadin-button> element and <div class="vaadin-button-container"> replaced with <button class="vaadin-button-container">. Note also that the inner <div> elements have been changed to <span> elements, as block-level elements such as <div> are not valid children of <button> elements. You may need to adjust the styling to accommodate this, but applying display: block; to the <span> elements will give you a block level element equivalent to a <div>.

For more complicated components, such as Radio buttons, there is the same problem:

<vaadin-radio-button value="economy" tabindex="0" aria-checked="true" role="radio" checked="">
  <label>
    <span part="radio">
      <input type="radio" role="presentation" tabindex="0">
    </span>

    <span part="label">
      <slot></slot>
    </span>
  </label>

  Economy
</vaadin-radio-button>

Using the same style technique, the following image shows focus on the <input> element.

The unfocused "Log in" button in the Details component, with visible button element

While the outer element, with role="radio" is focusable and has an accessible name and role, it is the <input type="radio" role="presentation">" that focus is set to. While the "Economy" text is inserted into the <slot> as you would expect, and it's part of the <label> element so would, under normal circumstances be picked up as an accessible name due to the implicit relationship the <label> and <input type="radio"> elements have, because the <input> element has role="presentation" this is not the case. NVDA announces nothing when navigated to the control using the Tab key.

The same solutions would apply here and to other similar cases, however we recommend the second approach with native <input type="radio"> elements here. Where as a button is relatively simple to implement, custom elements in general can be prone to problems such as this and are, in general, a less robust approach.

Currently the radio buttons operated independently and are not announced as a group (see also Radio Button issue regarding group labels). The expected behaviour when interacting with radio buttons is for the screen reader to enter forms/focus mode (indicated by a sound that varies depending on the screen reader), for the group name to be announced when first entering the group, and for the number of items in the group as well as the current radio button's place in that group to be announced: "Travel class grouping, First class, radio button, checked, three of three". Currently, none of that happens, but by removing role="presentation" from the <input type="radio"> elements and the role="radio" and tabindex="0" (as well as any other now unnecessary attributes such as aria-checked) the expected behaviour is exposed.

<vaadin-radio-button value="economy">
  <label>
    <span part="radio">
      <input type="radio">
    </span>

    <span part="label">
      <slot></slot>
    </span>
  </label>

  Economy
</vaadin-radio-button>

It would be usual for each radio button to have a name attribute, unique to the group of radio buttons. This is how the grouping of radio buttons is exposed using entirely native controls, and handles both the requirement that only one radio button in a group is checked and the keyboard navigation with up and down keys (i.e. pressing down focuses and selects the next radio button and pressing down when the last radio button in th group is focused checks and sets focus to the first radio button in the group – behaviour that is missing in the current implementation, even though it is technically accessible).

You have keyboard behaviour that is handling this when a screen reader is running, but because the current implementation is not triggering forms/focus mode automatically the behaviour of screen readers is to treat each radio button as a separate element. Changing the implementation so that the <input type="radio"> has a role of radio natively fixes this problem. When first focused, either with the Tab key or using the screen reader's focus controls, the screen reader will enter forms/focus mode by default and provide the expected experience automatically.

The select component has issues with accessible name calculation that is specific to NVDA. Investigation in to this has proved inconclusive as to the cause, but it is likely to be a similar issue whereby the actual focusable element is not the expected element with role="button" and aria-haspopup="listbox", but another element within the component. The result is that while JAWS correctly announces the visible label, the role, and the currently selected option, NVDA announces only the currently selected element and the accessible name of the role="button" element which is "toggle".

The select component with current selected option of "Most recent first"

<vaadin-select-text-field tabindex="0" has-label="" has-value="">
  # shadow-root
  <div class="vaadin-text-field-container">
    <label part="label" id="vaadin-select-text-field-label-8">Sort by</label>

    <div part="input-field" tabindex="0" aria-labelledby="vaadin-select-text-field-label-8 vaadin-select-text-field-input-8" id="vaadin-select-text-field-input-8" aria-expanded="false">
      <slot name="prefix"></slot>

      <slot name="input">
        <input part="value" aria-hidden="true" tabindex="-1" style="pointer-events: none;">
      </slot>

      <div part="clear-button" id="clearButton" role="button" aria-label="Clear"></div>
      <slot name="suffix"></slot>
    </div>

    <div part="helper-text" id="vaadin-select-text-field-helper-8">
      <slot name="helper"></slot>
    </div>

    <div part="error-message" aria-live="assertive" aria-hidden="true" id="vaadin-select-text-field-error-8"></div>
  </div>
  # end shadow-root
  
  <slot name="prefix" slot="prefix"></slot>
  <slot name="helper" slot="helper"></slot>
  <div part="value" slot="input"><vaadin-item value="recent" aria-selected="true" selected="" active="">Most recent first</vaadin-item></div>
  <div part="toggle-button" slot="suffix" role="button" aria-haspopup="listbox" aria-label="Toggle" aria-expanded="false"></div>
</vaadin-select-text-field>

Our best advice for this component is to simplify the structure, avoiding the multiple nested elements with tabindex="0" as these are potentially focusable and only make the custom focus management within the component more complicated. Follow the W3C Authoring Practices Guide Listbox pattern, specifically the Collapsible Dropdown Listbox Example as closely as possible as this provides the correct experience with both JAWS and NVDA.

The menu bar component has similar issues. While the appropriate roles and accessible names are exposed in JAWS, and the component is keyboard accessible with JAWS or without a screen reader running, in NVDA no content is exposed and it is entirely non-functional.

The select component with current selected option of "Most recent first"

<vaadin-menu-bar open-on-hover="" role="menubar" style="pointer-events: auto;">
  # shadow-root
  <div part="container">
    <vaadin-menu-bar-button tabindex="0" aria-haspopup="true" aria-expanded="false" part="menu-bar-button" role="menuitem" expanded="">
      # shadow-root
      <div class="vaadin-button-container">
        <div part="prefix">
          <slot name="prefix"></slot>
        </div>
        <div part="label">
          <slot></slot>
        </div>
        <div part="suffix">
          <slot name="suffix"></slot>
        </div>
      </div>
      # end shadow-root

      Project
    </vaadin-menu-bar-button>
    
    <vaadin-menu-bar-button tabindex="-1" aria-haspopup="true" aria-expanded="false" part="menu-bar-button" role="menuitem">Account</vaadin-menu-bar-button>
    
    <vaadin-menu-bar-button tabindex="-1" part="menu-bar-button" role="menuitem">Sign Out</vaadin-menu-bar-button>
  </div>
  # end shadow-root
</vaadin-menu-bar>

The container has the expected role="menubar" and the individual items have role="menuitem" with appropriate aria-haspopup and aria-expanded attributes; structurally there is nothing wrong with this. However, as with other components the focus management that takes place within the component may be causing issues with NVDA.

User impact

When an assistive technology user reaches a control without an accessible name or role, they will not be able to ascertain what the control's purpose is. Depending on the browser/assistive technology combination they are using, and how they navigated to the control (using browse mode or forms mode) they may also not be able to activate the controls altogether.

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. Turn on your screen reader
  2. Navigate through all controls (using Tab/Shift+Tab to move to all focusable elements, as well as using reading keys such as cursor up/down)
  3. Make sure that controls are announced with an actual name and role (e.g. "Primary author, edit") rather than just as generic nameless controls (e.g. "edit", "link", "button", "checkbox, unchecked")

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

Activity

  1. web-padawan commented on Mar 31, 2021

    @web-padawan
    Member
  2. rolfsmeds commented on Apr 8, 2021

    @rolfsmeds
    Contributor

    Realted issue for vaadin-button: https://github.com/vaadin/vaadin-button/issues/96

  3. rolfsmeds commented on Apr 8, 2021

    @rolfsmeds
    Contributor

    Related issue for vaadin-checkbox: https://github.com/vaadin/vaadin-checkbox/issues/181

  4. rolfsmeds commented on Apr 8, 2021

    @rolfsmeds
    Contributor

    Related issue for vaadin-radio-button: https://github.com/vaadin/vaadin-radio-button/issues/139

  5. web-padawan commented on Aug 29, 2022

    @web-padawan
    Member

    Closing as linked issues for individual components have been fixed.

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

    a11yAccessibility issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions