swagger-api / swagger-api/swagger-ui

Correct accessibility issues with headings

Open
#10,703 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

backlog cat: a11y
Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

  • skipping h2 - h1 is used for the title and then h3 for operations and schemas. h2 is used only for webhooks in OpenAPI 3.1 (rendered on the same level as tags sections starting with h3) and for nested callbacks in OpenAPI 2.0/3.0 (rendered nested in operations which start with h3). The main sections should be unified to start with the same heading.

  • nesting h2 inside of section starting with h3 and h4 - callbacks are nested within operations and start with h2, breaking the order of headings (h1h3h4h2)

    Image
  • Parameters and Callbacks heading - these headings are used as buttons but have no indication that the user can switch between the Parameters and Callbacks sections or which one is chosen. It is also not possible to focus them when using tab navigation

  • tag heading - the heading is used as a button and can expand/collapse the section without any indication that it does so. We should indicate that it can be interacted with, what it does and what the current state (expanded/collapsed) is.

  • unify styling of headings - styling of headings should be the same for different components, in this case it’s h4 that is different for: cURL, request URL, server response, responses, schemas

This task covers issues originally reported in:

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Locate the rendering for headings in operations, schemas, callbacks, tags, Parameters and Callbacks, and the related component styling. Check the heading hierarchy, keyboard focus, control labels, and expanded or collapsed state against the listed accessibility concerns. Done means the affected sections use a consistent hierarchy and styling, and interactive headings expose their purpose, focusability, and current state.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
accessibility, frontend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.