Skip to content

fix(theme): improve accessibility of api explorer controls#1325

Open
emroussel wants to merge 1 commit intoPaloAltoNetworks:mainfrom
emroussel:fix/explorer-a11y
Open

fix(theme): improve accessibility of api explorer controls#1325
emroussel wants to merge 1 commit intoPaloAltoNetworks:mainfrom
emroussel:fix/explorer-a11y

Conversation

@emroussel
Copy link

Description

Fix a couple of accessibility violations in the openapi explorer:

  • Associate form controls like inputs and selects to their label: I created a new <FormLabel> component to do this since I couldn't find a good way to make this work with the existing <FormItem> component. Some spots didn't render a visual label so I just set an aria-label or aria-labelledby as to not introduce any UI changes.
  • Use buttons instead of spans for the buttons next to the title in the request and response sections: Previously these "collapse/expand all" and "clear" interactive elements were impossible to focus/trigger using a keyboard.
  • Implement the disclosure pattern on the "show/hide optional params" button: Looks like all other disclosures use <details>/<summary> so the ideal fix here would probably be to do the same, but I wanted to keep markup changes to a minimum so I added the required aria attributes to make it accessible to screen readers instead.
  • Remove outline: none from the delete and add item buttons in array param form items: Removing the outline makes it so that users who navigate the site using a keyboard cannot know what is currently being focused.

Motivation and Context

Closes #1265

How Has This Been Tested?

Tested the openapi explorer section of the pet store demo running locally with keyboard navigation, screen reader, and mouse. Compared markup and styles with previous version (without my changes) to make it looks the same and that markup is not changed significantly.

Screenshots (if appropriate)

N/A

Types of changes

  • Bug fix (non-breaking change which fixes an issue)

Note: some of these fixes change the markup/styles slightly, for example I updated a clickable <span> to use a <button> instead since that's better semantics, but it could also be kept as a span with attributes like role="button" and tabindex="0" instead if you would rather keep markup changes to an absolute minimum. Some changes are probably inevitable though.

Checklist

  • I have updated the documentation accordingly.
  • I have read the CONTRIBUTING document.
  • I have added tests to cover my changes if appropriate.
  • All new and existing tests passed.

<button
className="openapi-explorer__delete-btn"
onClick={handleDeleteItem(item)}
aria-label="Delete"
Copy link
Author

@emroussel emroussel Mar 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The <title>Delete</title> below wasn't read by screen readers because the parent <svg> has aria-hidden="true". aria-label on the <button> is a more reliable way to set this label for screen readers.

background-color: transparent;
text-transform: inherit;
font-weight: inherit;
font-size: inherit;
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This overwrites default button browser styles so that these buttons look the same as before my changes in the demo. Worth noting that it could conflict with style overwrites depending on people are loading/applying them, in which case this element could stay as a span instead of a button like I mentioned in the "types of changes" in the PR description.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Accessibility issues in explorer

1 participant