fix(a11y): add skip-to-operations link, banner and main landmarks#10849
Open
bmatar wants to merge 1 commit intoswagger-api:masterfrom
Open
fix(a11y): add skip-to-operations link, banner and main landmarks#10849bmatar wants to merge 1 commit intoswagger-api:masterfrom
bmatar wants to merge 1 commit intoswagger-api:masterfrom
Conversation
Adds three structural a11y improvements:
1. <main id="operations"> wraps the operations + webhooks + models
region in BaseLayout. Provides a primary landmark for SR navigation
in every swagger-ui consumer (standalone or custom layout).
tabIndex="-1" + outline:none keeps it focusable programmatically
without adding a tab stop.
2. <header role="banner"> wraps the Topbar in StandaloneLayout. SR
users can jump to it via banner navigation.
3. Skip-to-operations link in StandaloneLayout — visually hidden
until focused, then appears top-left as a high-contrast button.
The click handler scopes the target lookup via closest('.swagger-ui')
so the link works correctly when multiple swagger-ui instances are
mounted on one page.
Manually verified with NVDA + Chrome on Windows 11.
Refs swagger-api#7350. WCAG 2.4.1 (Bypass Blocks), 1.3.1 (Info and Relationships).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds three structural a11y improvements:
<main id="operations">wraps the operations + webhooks + models region in BaseLayout. Provides a primary landmark for Screen Reader (SR) navigation in every swagger-ui consumer (standalone or custom layout).tabIndex="-1"+outline:nonekeeps it focusable programmatically (so the skip link can move focus to it) without adding a tab stop.<header role="banner">wraps the Topbar in StandaloneLayout. SR users can jump to it via banner navigation.Skip-to-operations link in StandaloneLayout — visually hidden until focused, then appears top-left as a high-contrast button. The click handler scopes the target lookup via
closest('.swagger-ui')so the link works correctly when multiple swagger-ui instances are mounted on one page.Motivation and Context
The default layout currently has no
<main>landmark. Standalone has no banner and no bypass mechanism. Keyboard and SR users must Tab through the topbar's logo, filter input, and dark-mode toggle on every navigation before reaching the operations list — and have no landmark structure to navigate via SR shortcut keys.Refs #7350 (umbrella accessibility issue). WCAG 2.4.1 (Bypass Blocks), 1.3.1 (Info and Relationships).
Detected by Tactual.
How Has This Been Tested?
npm run test:unit— all suites passnpm run build— cleanDOM probe (master vs this branch):
Keyboard flow on the local build:
.swagger-ui__skip-link(visible top-left)<main id="operations">Manually verified with NVDA + Chrome on Windows 11:
<main>; NVDA announces the main landmark and then the first operation heading/linkScreenshots
The skip link is visually hidden until focused. After pressing Tab once on page load:
No other visual change.
Checklist
My PR contains...
src/is unmodified: changes to documentation, CI, metadata, etc.)package.json)My changes...
Documentation
Automated tests