Background
Currently we don't have an available ARIA live region for dynamic content changes. This is important because screen readers scan the page at load time and register all live regions then. If there is a dynamic update that isn't within a live region, screen readers will not pick up on aria-live. If we create an aria live region within the html when a page is loaded we can then append information to it that we want screen readers to read. This is important for Reading List bc we want assistive technology users to know that they have successfully added articles to their reading list
User story
As a person who relies on assistive technology like screen readers to use the web, I want to be made aware of dynamic changes to content so that I am not confused or unsure of the current state of the application. As a Reading List users, I want to be notified that I have successfully added an article to my reading list so that I don't have to navigate to my reading list and check for the article there.
Former art
T55483: Add aria-live to mw.notification messages
Open questions
- ✅ Evaluate polite vs assertive as value for the live region for notifications
- 2025-09-24 @Volker_E: With some research and accessibility group feedback, polite seems like a solid choice
- Evaluate accompanying aria-atomic attribute and value
- 2025-10-29 @LMora-WMF With some research decided to leave aria-atomic to it's default setting of false
- Which region(s) on the page should be live regions?
- 2025-10-29 @LMora-WMF Keeping this scoped to notifications to not over engineer
- From patch: Would it be possible to add the aria-live markup to the mw-notification-area element, instead of copying the text to another element?
- 2025-10-29 @LMora-WMF using a live region separate from mw-notification-area follows best practices and separation of concerns. See comment below
Technical notes
- display: none is an issue for live regions https://tetralogical.com/blog/2024/05/01/why-are-my-live-regions-not-working/
Requirements / Acceptance Criteria
- Within core, there is an ARIA live region that exists on initial page load.
- ARIA live region has role="region" and aria-live="polite"
Requirement
Scope: MediaWiki core (desktop + mobile, all skins).
- Introduce an ARIA live region that is available immediately upon initial page load.
- The live region must be available to screen readers at all times and not hidden via display: none.
- The live region must have the following attributes:
- role="region"
- aria-live="polite"
- The live region should be separate from the mw-notification-area element to maintain clear separation of concerns.
- The region will serve as the destination for dynamic notification messages (e.g., Reading List confirmation).
- The live region must load with every page, even before any dynamic notifications occur.
- aria-atomic should remain at its default (false).
BDD
Feature: Create an ARIA live region for dynamic notifications
Scenario: Page loads with ARIA live region
Given I load any page on the wiki
When I inspect the page’s DOM structure
Then an element exists with `role="region"` and `aria-live="polite"`
And it is visible to assistive technology (not `display: none`)
Scenario: Screen reader detects live region
Given the ARIA live region exists on page load
When a dynamic notification is triggered (e.g., a Reading List save message)
Then the notification text is added to the live region
And the message is read aloud by the screen readerTest Steps
Test Case 1: Verify live region exists on page load
- Load any wiki page and open Chrome DevTools → Elements tab.
- Search for an element with role="region" and aria-live="polite".
- AC1: The live region is present in the DOM on initial page load.
- AC2: The live region is not hidden with display: none or visibility: hidden.
Test Case 2: Verify screen reader reads messages from live region
- Trigger a dynamic notification (e.g., save a page to Reading List).
- Inspect the live region content again in DevTools.
- AC3: The notification text appears inside the live region element.
- AC4: Using macOS VoiceOver, confirm that the text is read aloud automatically.
