Accordion buttons have incomplete accessible names (WCAG Level A failure)

[maggiewachs]

Q&A (please complete the following information)

• OS: all
• Browser: all
• Version: all
• Method of installation: n/a
• Swagger-UI version: v5.9.1 (latest)

Summary / TL;DR:

• The accordion buttons that contain summary text in Swagger UI are named in a way that fails accessibility standards defined in WCAG SC 2.5.3: Label in Name (Level A)
• This error is present in every default installation of Swagger UI: https://github.com/swagger-api/swagger-ui/blob/master/src/core/components/operation-summary.jsx#L71
• For the websites I work on, that means thousands of accessibility violations across hundreds of our dataset pages
• Removing the aria-label (editing a single line in the source) would spare us having to do a hacky workaround to eliminate the accessible name mismatch, and would benefit all users of Swagger UI, especially those who rely on assistive tech (voice control, screen readers, etc)

Describe the bug you're encountering

The Swagger UI accordion button's accessible name (aria-label) does not include all of the text displayed on the button and therefore does not conform to accessibility standards defined in WCAG (SC 2.5.3: Label in Name (Level A)). See also:

• Understanding SC 2.5.3: Label in Name (Level A)
• axe-core rule: Elements must have their visible text as part of their accessible name

In the current button markup, the aria-label value is missing the summary description (e.g., "Add a new pet to the store"). Examples from the Pet store demo:

This markup fails SC 2.5.3:

<button aria-label="post /pet" aria-expanded="false" class="opblock-summary-control">
  <span class="opblock-summary-method">POST</span>
  <span class="opblock-summary-path" data-path="/pet">
    <a class="nostyle" href="#/pet/addPet"><span>/pet</span></a>
  </span>
  <div class="opblock-summary-description">Add a new pet to the store</div>
</button>

For comparison, this markup would pass SC 2.5.3 (aria-label removed):

<button aria-expanded="false" class="opblock-summary-control">
  <span class="opblock-summary-method">POST</span>
  <span class="opblock-summary-path" data-path="/pet">
    <a class="nostyle" href="#/pet/addPet"><span>/pet</span></a>
  </span>
  <div class="opblock-summary-description">Add a new pet to the store</div>
</button>

To reproduce...

Some automated testing tools like Wave and axe DevTools do not flag this issue, however Accessibility Insights and Siteimprove do, as does manual testing with a screen reader. Accessibility Insights flags the "label-content-name-mismatch" issue under "Needs review" for a person to verify the content mismatch.

Steps to reproduce:

1. Open the pet store demo (or other default installation of Swagger UI) in a browser with the Accessibility Insights extension installed
2. Open Accessibility Insights, and choose the FastPass option
3. When the results window appears, choose "(3) Needs review" from the left nav, and expand to show all instances of the "label-content-name-mismatch" issue.

Expected behavior

There should be no label-content-name-mismatch occurrences displayed in Accessibility Insights, however there are 20 in the pet store demo.

Additional context or thoughts

Note that this issue applies only to the buttons that contain an aria-label and visible text. The arrow buttons for toggling accordions should retain their aria-label attributes because they do not have visible text.

Suggested fix: The simplest way to correct this mismatch is to remove the aria-label from the accordion's summary button because it's entirely redundant. Without the aria-label, assistive tech will use the visible text to compute the accordion button's accessible name:

[mgifford]

If the semantics can be achieved through HTML, we shouldn't be using ARIA. Redundant semantics doesn't benefit users.

[konstantintieber]

@mgifford so you are saying that rather than including the endpoint description in the existing aria-label attribute on that button (link from the issue description), the proper and more sustainable way to improve accessibility would be to remove the aria-label attribute altogether? Since all the text we include in the button is already contained within its children?

Thanks for your input :)

[maggiewachs]

@mgifford so you are saying that rather than including the endpoint description in the existing aria-label attribute on that button (link from the issue description), the proper and more sustainable way to improve accessibility would be to remove the aria-label attribute altogether? Since all the text we include in the button is already contained within its children?

@konstantintieber Yes! That's the simplest and most effective fix.

[char0n]

Hi @maggiewachs,

Thanks for explaining the whole context and reasoning.

[char0n]

Closed by #9361