Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Accessibility improvements #7224

Merged
merged 28 commits into from
May 12, 2021
Merged

Accessibility improvements #7224

merged 28 commits into from
May 12, 2021

Conversation

gileswells
Copy link
Contributor

Description

This PR includes a few improvements to the accessibility of Swagger UI and will allow users with assistive devices to more easily navigate and consume the information that is being presented.

  1. Add aria-control for ContentType & Responses region
  2. Add aria-expanded support to collapsable regions
  3. Update the heading level on the Operation Tag to be an h3

Motivation and Context

  1. This adds better support for screen readers on the modified elements so they can more easily navigate and consume the information.
  2. This adds more contextual clues for collapsable sections of content.
    1. The arrow icons currently used here differ from UX guidance from few industry experts. When using icons to show there is an interaction to trigger the icon should show what is expected. If expanding an accordion downward you could use a + or in this case a downward arrow. When collapsing back up either a - or an upward arrow would be appropriate because that shows the action to come.
    2. This also adds arrows to the endpoints themselves to assist in visual representation that they expand downwards.
    3. (IBM) https://www.carbondesignsystem.com/components/accordion/usage/#states
    4. (Nielson) https://www.nngroup.com/articles/accordion-icons/
  3. This change provides for better hierarchy because, using (petstore)[https://petstore.swagger.io/] as an example, the pet endpoint group (tag) is currently an h4 but is at a higher position in the document's hierarchy and should be more prominent than the Parameters or Responses headings which also are h4's.
    1. (future consideration not in this PR) Ideally I believe the endpoint url itself would probably take up a tag as an h4 and then the h4's below that should move to h5 tags.

How Has This Been Tested?

We've tested using VoiceOver on Safari and Chrome on Mac and by running and as needed updating the unit tests that exist within this repo.
It's our understanding that these changes did not have any changes outside those mentioned above.

Screenshots (if appropriate):

Previously (showing an expansion to the right and a further expansion downward):
image

PR (shows the expansion will happen downward and the collapse will happen upwards)
image

Checklist

My PR contains...

  • No code changes (src/ is unmodified: changes to documentation, CI, metadata, etc.)
  • Dependency changes (any modification to dependencies in package.json)
  • Bug fixes (non-breaking change which fixes an issue)
  • Improvements (misc. changes to existing features)
  • Features (non-breaking change which adds functionality)

My changes...

  • are breaking changes to a public API (config options, System API, major UI change, etc).
  • are breaking changes to a private API (Redux, component props, utility functions, etc.).
  • are breaking changes to a developer API (npm script behavior changes, new dev system dependencies, etc).
  • are not breaking changes.

Documentation

  • My changes do not require a change to the project documentation.
  • My changes require a change to the project documentation.
  • If yes to above: I have updated the documentation accordingly.

Automated tests

  • My changes can not or do not need to be tested.
  • My changes can and should be tested by unit and/or integration tests.
  • If yes to above: I have added tests to cover my changes.
  • If yes to above: I have taken care to cover edge cases in my tests.
  • All new and existing tests passed.

ediiotero and others added 28 commits March 11, 2021 13:39
…airs/swagger-ui into bug/add-aria-label-to-select
…a-label-to-select

fix: add aria label to select element for content types
…ft/a11y-curlform-submit-button

feat: adds a11y for ContentType & Responses region
…ft/a11y-updates-for-expand-collapse

feat: a11y updates for expand/collapse elements
…fix-optag-heading-heirarchy

Fix optag heading heirarchy
@tim-lai tim-lai merged commit 72811bd into swagger-api:master May 12, 2021
@tim-lai
Copy link
Contributor

tim-lai commented May 12, 2021

@gileswells PR merged! Appreciate the work on improving accessibility!

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.

None yet

3 participants