--- name: aria-live-announcements description: "Audits and fixes how dynamic changes reach screen readers: toasts, form errors, saved and loading messages, search result counts, cart updates (WCAG 4.1.3). Finds live regions rendered conditionally in React, Vue or Angular, regions hidden with display:none, assertive overuse, too many regions and script-injected alerts, then watches a real page for regions inserted late. Covers role=status, role=alert, aria-live and ariaNotify. Use for 'screen reader does not announce' bugs. Do NOT use for focus management, accessible names, dialogs or screen reader testing." license: CC-BY-4.0 metadata: author: Afeez Adebayo author_url: https://afeezadebayo.com author_linkedin: https://www.linkedin.com/in/afeez-adebayo/ author_x: https://x.com/za_icon source: https://afeezadebayo.com/skills-md/frontend-development/accessibility/aria-live-announcements/ category: frontend-development subcategory: accessibility version: "1.0.0" created: "2026-10-30" updated: "2026-10-30" --- # ARIA Live Announcements: Make Status Messages Reach Screen Readers An agent works on announcements in this order: list every message the interface shows without a page load, decide which ones need announcing, run a static checker over the source, run a browser probe that clicks through the triggers and reports what happened to the live regions, fix the structure first (a region that exists, stays in the accessibility tree and only changes its text), then the urgency, then repeats, and re-run both tools. The checker reads markup and component syntax. The probe shows the DOM behaviour. Neither can hear a screen reader. Patterns and code are in `references/patterns.md`. Technique ids and support notes are in `references/appendix.md`. ## When to use this skill, and when not to Use it when a screen reader user is not told about a saved, failed, loading, added or filtered result, when a toast is silent, or when a validator or audit flags status messages (SC 4.1.3). | Request | Use instead | |---|---| | Moving focus to an error summary or a new heading | `keyboard-focus.md` | | Names, roles and `aria-hidden` on controls | `aria-names-roles.md` | | Native `` and popover markup | `dialog-and-popover.md` | | Field labels, error text wording, validation timing | `html-forms.md` | | Real speech output, timing and verbosity | Out of scope. Needs a person with the screen reader | ## Guardrails 1. **Propose, then change.** Report and plan first. Edit only after the user approves a batch, on a branch under version control. Never push, merge or deploy. 2. **Pages you own only.** `live_probe.js` opens a page and clicks the selectors you give it. Run it only on pages the user owns, never on a page where a click can pay, send, delete or publish. Use a test environment or static copy with test data. Never ask for cookies, tokens or passwords. 3. **Data handled.** `live_check.py` reads the files you pass. `live_probe.js` prints element descriptions (tag, id, role) and counts, never page text. Messages can contain names, order numbers or health or payment details: do not paste message text, screenshots or form values into prompts or reports. 4. **Nothing is invented.** Every rule carries a source and a date. Version-dependent behaviour carries **verify before relying on this**. 5. **Not a conformance statement.** A clean run means the structure is sound. Whether a message is spoken, and when, depends on the screen reader and browser pairing. It is not a WCAG conformance claim and not legal advice. A conformance claim needs a person who has heard the page with a screen reader. 6. **Refuses to:** make a region assertive because a message matters to the team, announce every keystroke, put a live attribute on `main`, `form` or a long list, hide a region with `display: none`, or report a fix as verified without the probe. ## Inputs the agent must have before starting Ask for every missing item. Do not assume. | Input | Ask exactly | |---|---| | Messages | "List every message that appears without a page load: saved, error, added to cart, results count, loading, session timeout, toasts." | | Source | "Give me the component or template files that render them." | | Framework | "Which framework renders them: React, Vue, Angular, Svelte or plain HTML?" | | Page | "Which page may I click through? Give a local file or a test URL you own, and a click selector for each trigger that is safe to press." | | Screen readers | "Which screen reader and browser pairings must work? A person with the device has to confirm." | | Tooling | "Is Node with Playwright installed? If not, may I install it in a temporary folder?" | | Approval | "May I edit on a branch in batches and show each diff first?" | ## Workflow ### Step 1: Classify each message W3C Understanding SC 4.1.3 (AA): a status message is a content change that is not a change of context and that reports success or results, a waiting state, progress or an error. | Message | Needs a live region? | |---|---| | "Saved", "Added to cart", "18 results returned", "Loading" | Yes: status message | | Validation error that stays on the page and focus does not move | Yes | | Error summary that receives focus | No. A change of focus is a change of context, so it is not a status message | | Content revealed by a menu, accordion, tab or tree | No. That is SC 4.1.2 (`aria-names-roles.md`) | | The results list itself | No. Announce the count, not the list | ### Step 2: Run the static checker ``` python3 scripts/live_check.py src/Cart.jsx page.html | head -40 ``` Read only its output. Do not read the script. The first line has the counts and the number of live regions found. `--strict` exits 1 on warnings. | Code | Level | Meaning | Fix | |---|---|---|---| | `live-conditional` | error | Region rendered behind `&&`, a ternary, `v-if`, `*ngIf` or `@if`: it arrives with its text | Step 4 | | `live-hidden` | error | Region hidden with `hidden`, `display:none`, `aria-hidden` or `v-show` | Step 4 | | `live-injected` | warn | Region created by script with its text in one step | Step 4 | | `live-conflict` | warn | `role=alert` with `aria-live=polite`, or `role=status` with `aria-live=assertive` | Step 5 | | `live-container` | warn | Live attribute on `main`, `form`, `nav`, `table`, `section`, `article`, `ul`, `ol` or `aside` | Step 4 | | `live-region-count` | warn | More than two regions in a file | Step 4 | | `live-assertive-many` | warn | More than one assertive or alert region | Step 5 | | `toast-no-role` | warn | Element named toast, snackbar, notification or similar with no live role | Step 4 | | `live-redundant`, `live-weak-role`, `live-relevant`, `notify-used` | info | Repeated defaults, weakly supported roles or attributes, `ariaNotify` present | Steps 5 and 6 | | `notify-no-fallback` | warn | `ariaNotify()` with no live region anywhere | Step 6 | The checker reads text, not a DOM, and splits tags on `>`. Brace expressions that contain `>` can hide a tag. It cannot see a region built by a library. Treat a `live-conditional` hit that sits in a string or comment as a false positive after reading the line. ### Step 3: Probe the page ``` node scripts/live_probe.js page.html '#save' '#remove' '#pay' ``` It watches the DOM, clicks each selector in order, waits 700 ms after each, and prints one line: `regions-at-load=N changed=N late-inserted=N hidden-changed=N`, then one line per problem. Needs Node and Playwright (`require('playwright')` must resolve). Chromium only. | Output | Meaning | Action | |---|---|---| | `late-inserted` | A region was added to the DOM already holding text | Step 4 | | `hidden-changed` | Text changed inside a region that was hidden | Step 4 | | `changed=0` after a click that should announce | The click changed no live region | The message goes elsewhere. Find the render path | | `regions-at-load=0` | No region exists before the first action | Step 4 | ### Step 4: Fix the structure Sources: htmhell (2023), dev.to (framework article), MDN, all fetched 30 October 2026. | Rule | Fix | |---|---| | The region must exist in the DOM, empty, before the text changes | Put the empty element in the markup at load. Change its text, or add a child to it | | Never toggle the region itself | React, Vue and Angular fixes: `references/patterns.md`, section 3 | | Never hide the region | `display: none` and `visibility: hidden` remove it from the accessibility tree. Use the clipped `.visually-hidden` class (`references/patterns.md`, section 1) | | Do not reveal a hidden region and change its text in the same moment | Keep it visible or clipped permanently | | Keep regions small | A live attribute on a container re-reads every change inside it. Use a dedicated element | | Use at most two regions | One polite, one assertive, reused through one helper (`references/patterns.md`, section 2) | | Toast without a role | Give a non-urgent toast `role="status"`. A toast must not be the only channel for critical information (ibelick) | ### Step 5: Choose the urgency | Message | Use | Why | |---|---|---| | Saved, added, results count, progress, filter applied | `role="status"` (polite) | Spoken at the next graceful moment (MDN) | | Error the user must act on now, session about to expire | `role="alert"` (assertive) | Highest priority, may clear the speech queue (MDN) | | Anything routine | Never assertive | An assertive update can cause a simultaneous polite one to be dropped (htmhell) | | Time-limited content | Assertive, and a way to extend or turn it off | MDN, WCAG timing | | Updates that change faster than a person can listen (scores, tickers, per-keystroke results) | `off`, or announce a summary after the user pauses | MDN, htmhell | Do not add `aria-live` to `role="status"` or `role="alert"`: the role already implies `polite` or `assertive`, plus `aria-atomic="true"` (htmhell). Prefer `status` and `alert` over `log`, `timer` and `marquee`, which have weaker support (htmhell). `aria-busy`, `aria-relevant` and `aria-atomic` vary by pairing: verify before relying on them. ### Step 6: Repeats, timing and ariaNotify | Case | Fix | |---|---| | The same message must be announced twice | Clear the text, wait, then set it again. Start at 150 ms and confirm with the target screen reader: mgifford uses 50 ms, the dev.to article suggests 150 to 500 ms. **Verify before relying on this** | | A screen-reader-only notice stays in the DOM | Remove it about 500 ms after it appears, to avoid stale re-announcements (htmhell) | | Several updates in one burst | Combine them into one message. `ariaNotify()` usually speaks only the latest call (MDN) | | Browsers that support it | `document.ariaNotify(message, { priority })`, `normal` or `high`, with the live-region helper as the fallback in an `else` branch. MDN labels it Baseline 2026, newly available. **Verify before relying on this** | ### Step 7: Verify and report 1. Re-run `live_check.py`. Errors must be 0. Each warning is fixed or listed with a reason. 2. Re-run `live_probe.js` with the same selectors. `late-inserted` and `hidden-changed` must be 0 and `changed` must equal the number of triggers that announce. 3. List each message with its role and urgency. Do not paste the message text. 4. State what is untested: speech output on every pairing, verbosity, interrupted speech, voice control. 5. Ask a person to try each message with the target screen readers: JAWS with Chrome, NVDA with Firefox, Narrator with Edge, VoiceOver with Safari (htmhell). 6. Use the report template. Do not echo unchanged code back. ## Worked example An invented page of 10 lines (`demo-live.html`): a Save button that writes text into `#ok` (`role="status"`, empty at load), a Remove button that writes into `#hid` (`role="status"`, `display:none`), and a Pay button that sets `innerHTML` to a new `

Payment failed

`. ``` $ python3 scripts/live_check.py demo-live.html 1 errors, 2 warnings, 0 info, 3 live regions demo-live.html:5 error live-hidden
is hidden or toggled with display:none ... demo-live.html:1 warn live-region-count 3 live regions in this file ... demo-live.html:10 warn live-injected

is created by script together with its text ... $ node scripts/live_probe.js demo-live.html '#save' '#remove' '#pay' regions-at-load=2 changed=1 late-inserted=1 hidden-changed=1 late-inserted p[role=alert] region added to the DOM already holding text: often not announced hidden-changed div#hid[role=status] text changed while the region was hidden: not announced ``` (Messages shortened here.) Only the Save message follows the rules in step 4. The other two fall under the cases that step lists as unreliable, which is an inference from the sources and not a speech test. The probe finds what the checker cannot: the injected alert sits inside a script string, and the checker sees it only because the line contains `innerHTML`. One batch: the hidden region goes, "Item removed" is written into `#ok`, the injected alert becomes an empty `