a11y(4.1.3): Toaster role="log" → per-toast role="status"/"alert" for correct AT announcement semantics by rosanusi · Pull Request #3560 · temporalio/ui

rosanusi · 2026-06-12T15:45:03Z

Summary

Fixes WCAG 2.2 SC 4.1.3 (Status Messages) for the toast notification surface by introducing a small, placeable live-region primitive and decoupling the screen-reader announcement from the visual toast.

The earlier approach in this PR put role="status"/role="alert" + aria-atomic on each per-toast <div>. That inverts the one rule a live region must obey: the region has to exist in the DOM, empty, before its content is inserted. A node that is simultaneously the region and its content (inserted in a single DOM mutation) does not reliably announce — and the polite case (status: success/info/warning/primary, the majority of toasts) is exactly the unreliable one. So the original change likely regressed the SC it set out to fix. This rework replaces it.

Approach

A persistent sr-only live region, fed by the toaster store — one announcement per toast, independent of the animated visual node:

File	Change
`src/lib/stores/announcer.ts` (new)	`createAnnouncer()` — a buffer of `{ id, message, politeness }`. `announce()` appends a uniquely-keyed node (append, not clear-and-reset); each is removed after `max(toast duration, 7s)`. `clear()` empties the buffer and cancels pending timers.
`src/lib/holocene/live-region.svelte` (new)	Two always-rendered sr-only regions — `aria-live="polite"` and `aria-live="assertive"`, both `aria-relevant="additions"`; messages routed by politeness, keyed by `id`. Optional `data-testid` applied to both regions (`-polite`/`-assertive`).
`src/lib/stores/toaster.ts`	`push()` calls `announce(message, variant === 'error' ? 'assertive' : 'polite', duration)`; exposes `announcements`; `clear()` also clears the announcer.
`src/lib/holocene/toaster.svelte`	Mounts `<LiveRegion>` (optional self-subscribing `announcements` prop, defaults to the singleton store); container keeps no `role`.
`src/lib/holocene/toast.svelte`	Reverted to purely visual — per-toast `role`/`aria-atomic` removed.

Why this shape

Region pre-exists empty → reliable announcement (MDN Live Regions; WCAG ARIA22).
aria-live on the wrapper (not role) avoids iOS-VoiceOver double-speak; aria-relevant="additions" keeps the timed removals silent.
Unique-keyed append → identical consecutive messages re-announce (fixes the stale-announcement gap).
A placeable component (not a body-level singleton) is deliberate: a body-level region is inerted by aria-modal under VoiceOver+Safari (W3C ARIA Update drawer types and x color props #1854). Modal-scoped messages (future, e.g. a11y(2.2.1): ui-main — warn the user before session expiry and offer an extend affordance #3531) must mount their own <LiveRegion> inside the dialog; DOM-resident status (e.g. a11y(4.1.3): Add live-region wrappers for workflow status, event count, filter counts, and Banner #3561) announces in place. This PR scopes to toasts only.

Test plan

Screen-reader smoke test (VoiceOver + NVDA) — success/info/warning/primary toast announces politely (no interrupt); error toast announces assertively (interrupts). (Note: under a rapid burst, screen readers coalesce same-region polite updates to latest-wins; this matches react-aria/Radix and is expected.)
DOM: two .sr-only[aria-live="polite"] / [aria-live="assertive"] regions exist before any toast fires; the visible container <div> and each toast <div> carry no role.
Workflow client-action confirmations (Terminate / Cancel / Reset / Signal) fire a toast that renders and announces.
axe-core: no new violations on a page with a live toast.

Automated: unit tests for createAnnouncer (politeness mapping, lifetime/timeout, distinct ids, clear) and toaster store wiring; an integration assertion that the live regions pre-exist and a toast message routes to the polite region.

Downstream (cloud-ui)

announcements is an optional prop defaulting to the singleton, so cloud-ui's two <Toaster> mounts compile and work unchanged after the @temporalio/ui pack bump — no cloud-ui edits required.

A11y-Audit-Ref: 4.1.3-toaster-role-status-alert

🤖 Generated with Claude Code

…ert" - Remove role="log" from the Toaster container; live-region semantics move entirely to individual Toast instances - Add getRole() to Toast: error variant → role="alert" (assertive); all others → role="status" (polite) - Add aria-atomic="true" so the full toast content re-announces on each insertion, even when consecutive toasts share similar markup Screen readers can now distinguish urgency between error and informational toasts (WCAG 2.2 SC 4.1.3 Status Messages). A11y-Audit-Ref: 4.1.3-toaster-role-status-alert Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel · 2026-06-12T15:45:09Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
holocene	Ready	Preview, Comment	Jun 24, 2026 4:21pm

temporal-cicd · 2026-06-12T15:46:19Z

	Warnings
⚠️	📊 Strict Mode: 3 errors in 2 files (0.3% of 892 total) src/lib/stores/toaster.ts (1) L38:8: Argument of type 'string \| undefined' is not assignable to parameter of type 'string'. src/lib/holocene/toaster.svelte (2) L50:40: Type 'ToastVariant \| undefined' is not assignable to type 'ToastVariant'. L50:50: Type 'string \| undefined' is not assignable to type 'string'.

Generated by 🚫 dangerJS against f3bf7da

Implement framework-agnostic Svelte store factory that manages announcement messages with auto-removal timeout, supporting polite and assertive politeness levels for WCAG 4.1.3 live-region announcements. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…on contract Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

temporal-cicd · 2026-06-20T00:41:41Z

+    toastWithDefaults.variant === 'error' ? 'assertive' : 'polite',
+    toastWithDefaults.duration,
+  );
  const timeoutId = setTimeout(() => {


⚠️ Argument of type 'string | undefined' is not assignable to parameter of type 'string'.

…n directly

temporal-cicd · 2026-06-22T13:08:11Z

-<div class={toast({ position: $position })} role="log">
+<div class={toast({ position: $position })}>
+  <LiveRegion messages={$announcements} data-testid="toast-live-region" />
  {#each $toasts as { message, variant, id, link } (id)}


⚠️ Type 'ToastVariant | undefined' is not assignable to type 'ToastVariant'.

⚠️ Type 'string | undefined' is not assignable to type 'string'.

Add an optional `politeness` prop ('polite' | 'assertive' | 'both', default 'both') so consumers that only ever emit one politeness level (e.g. status chips, filter counts, the session-warning countdown) don't render an unused live region. Zone selection must be declared at instantiation because a live region must pre-exist empty before content is inserted — it cannot be derived from current message content. Toaster keeps the default 'both' (success=polite, error=assertive), so its behavior and the existing integration contract are unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…render" This reverts commit 9d60456.

ardiewen · 2026-06-24T13:47:32Z

Update — reworked onto a shared LiveRegion/announcer primitive

What changed since the original PR

The original approach (per-toast role="status"/"alert" set on mount) regressed SC 4.1.3 — a polite role announced on insertion is unreliable. Reworked to the always-rendered-live-region pattern.

Before	After
Role applied per-toast at mount	Toast is purely visual (no ARIA)
Region created with its content	Persistent empty `aria-live` regions pre-exist; toasts announced as dynamic content
Toaster-only	Reusable `createAnnouncer()` store + placeable `LiveRegion` component

Final architecture

stores/announcer.ts — createAnnouncer(): announce(message, politeness?, duration?) + clear(); persists each message max(duration, 7000ms) then removes.
holocene/live-region.svelte — two persistent sr-only regions (polite + assertive), keyed nodes.
stores/toaster.ts — holds a private announcer; push() routes error → assertive, else polite.
holocene/toaster.svelte — mounts LiveRegion; container/toast carry no role.

Decisions

✅ Announcer kept private to the toaster — it's a standalone module, so layering is already clean and a future shared announcer forecloses nothing here.
↩️ A politeness zone-selection prop was added then reverted — speculative; no current consumer needs it.

Out of scope (follow-up: "ambient SR announcements")

Audited ui + cloud-ui for the same transient-no-visible-host gap. Not part of this PR:

Class	Surfaces	Fix
Copy-to-clipboard (silent icon swap)	`ui` ×4, `cloud-ui` ×3 — all via shared `copyToClipboard()`	Announce inside the shared util → covers both repos
Inline action confirms ("Success!"/"Saved")	`cloud-ui` ×3 (sink-verify ×2, internal-roles)	Per-surface `announce()`

Banners/modals/status-chips/counts excluded (persistent or in-place → element-level live regions).

Remaining gate

Manual NVDA + VoiceOver verification (polite no-interrupt, error interrupts, both regions pre-exist) before leaving draft. Note: VoiceOver coalesces rapid polite updates (latest-wins) — expected SR behavior, not a regression.

tegan-temporal · 2026-06-24T15:29:56Z

+  clear: () => void;
+}
+
+const DEFAULT_TIMEOUT = 7000;


Am I understanding correctly that we are defaulting to a 7 second delay before starting the announcement? Is that normal? IMO it feels like a long time, if something is 'polite' does it need a manual delay at all?

It's not a delay on the announcement itself, but rather how long the announcement text stays in the DOM. This gives the screen reader a chance to actually pick up the announcement, while also ensuring it gets automatically cleared out of the dom after a certain amount of time.

The default of 7000ms is just directly ripped from other popular implementations, e.g. react-aria

tegan-temporal · 2026-06-24T15:47:41Z

+  const polite = $derived(
+    messages.filter((message) => message.politeness === 'polite'),
+  );
+  const assertive = $derived(
+    messages.filter((message) => message.politeness === 'assertive'),
+  );


Feel free to ignore this suggestion, but it seems like a good use case for the newish Object.groupBy.

Suggested change

const polite = $derived(

messages.filter((message) => message.politeness === 'polite'),

);

const assertive = $derived(

messages.filter((message) => message.politeness === 'assertive'),

);

const { polite, assertive } = $derived(

Object.groupBy(messages, (message) => message.politeness)

);

pnpm check fails when we try to implement this:

1782322397445 ERROR "src/lib/holocene/live-region.svelte" 19:12 "Property 'groupBy' does not exist on type 'ObjectConstructor'. Do you need to change your target library? Try changing the 'lib' compiler option to 'es2024' or later."

Looks like it's an ES2024 and beyond feature 😞

tegan-temporal

couple comments, no blockers

Addresses review feedback — replaces the hand-rolled { subscribe } wrapper with svelte/store's readonly() helper. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Auto-generated version bump from 2.51.1 to 2.52.0 Bump type: minor Changes included: - [`9c6fcd54`](9c6fcd5) Add direct SSO redirect and backend logout (#3590) - [`feab0d90`](feab0d9) a11y(4.1.3): Toaster role="log" → per-toast role="status"/"alert" for correct AT announcement semantics (#3560) - [`d7bbfb01`](d7bbfb0) a11y(2.5.8): toast — replace bare close button with IconButton (36×36 px) (#3553) - [`4efd6ab6`](4efd6ab) a11y(3.3.1): Holocene input primitives — add aria-invalid, aria-describedby, and uniform live-region error announcement (#3554) - [`0600b700`](0600b70) Use green only (#3599) - [`94107549`](9410754) Clarify activity pause timeout behavior (#3600) - [`9f88d5a8`](9f88d5a) Bump node version to 22.23.1 or newer to fix issue from previous security release (#3604) - [`ca4104ae`](ca4104a) Update reason copy and inputs (#3588) - [`51db73fa`](51db73f) Update batch operation reason input hint (#3605) - [`836d7c55`](836d7c5) a11y(2.4.3): route navigation — move focus to the main landmark on afterNavigate, not just scroll (#3538) - [`4ee95696`](4ee9569) Improve re-renders for large encoded event histories (#3592) - [`fa5e7aa1`](fa5e7aa) feature/schedules (#3603) - [`0d9467fd`](0d9467f) Default includeHeartbeatDetails and includeLastFailure to true for getActivityExecution and pollActivityExecution (#3521) - [`e5bc514e`](e5bc514) fix schedules: duplicate key (#3612) - [`f1eb489f`](f1eb489) Remove preview badge (#3581) - [`1e5173b4`](1e5173b) Add existing versions to worker create deployment version form (#3601) - [`a8552bae`](a8552ba) fix schedules -e.trim not a function (#3613) - [`0442f847`](0442f84) Fix width of ComputeBadge in VersionTableRow (#3615) - [`ddbeb54f`](ddbeb54) fix(cloud-nav): animate and stabilize side-nav collapse (#3606) - [`3cfc684b`](3cfc684) fix - schedules recent/upcoming runs - sort issue (#3616) - [`92b8875b`](92b8875) Move timestamp out of translate (#3617) - [`901258af`](901258a) Fix SAA and WF consistency (#3614) - [`99593d97`](99593d9) DT-4001 - standalone nexus operations (#3496) - [`f10d1bf1`](f10d1bf) Clamp codeblock to container width (#3621) - [`0a9d93ce`](0a9d93c) Remove unnecessary bottom-0 (#3623) - [`9dabb522`](9dabb52) chore(deps-dev): bump vite from 6.4.2 to 6.4.3 (#3610) - [`5c1854d3`](5c1854d) News Feed (#3596)

github-actions Bot added a11y Accessibility audit PR a11y:bucket-3 Bucket 3: engineer required a11y:sc-4.1.3 labels Jun 12, 2026

vercel Bot deployed to Preview June 12, 2026 15:45 View deployment

rosanusi marked this pull request as ready for review June 12, 2026 16:30

rosanusi requested a review from a team as a code owner June 12, 2026 16:30

ardiewen and others added 5 commits June 19, 2026 16:18

feat(a11y): add placeable LiveRegion component

06619d3

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat(a11y): announce toasts via createAnnouncer in toaster store

687a03c

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat(a11y): announce toasts via LiveRegion; drop per-toast roles

b0031a8

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

refactor(a11y): consolidate duplicate toaster store import

93df55b

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview June 19, 2026 20:47 View deployment

This comment was marked as outdated.

Sign in to view

ardiewen and others added 2 commits June 19, 2026 20:35

fix(a11y): coordinate announcer lifetime, tidy clear(), test LiveRegi…

1add131

…on contract Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

test(a11y): assert default 7s announcer floor for longer durations

4276cb5

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel Bot deployed to Preview June 20, 2026 00:41 View deployment

temporal-cicd Bot reviewed Jun 20, 2026

View reviewed changes

refactor(a11y): drop unused Toaster announcements prop, read singleto…

1d4b358

…n directly

vercel Bot deployed to Preview June 22, 2026 13:07 View deployment

temporal-cicd Bot reviewed Jun 22, 2026

View reviewed changes

vercel Bot deployed to Preview June 23, 2026 20:13 View deployment

Revert "feat(a11y): let LiveRegion declare which politeness zones to …

6127abd

…render" This reverts commit 9d60456.

vercel Bot deployed to Preview June 23, 2026 20:48 View deployment

tegan-temporal reviewed Jun 24, 2026

View reviewed changes

Comment thread src/lib/stores/announcer.ts Outdated

tegan-temporal reviewed Jun 24, 2026

View reviewed changes

tegan-temporal approved these changes Jun 24, 2026

View reviewed changes

refactor(a11y): use svelte readonly() for announcer messages store

f3bf7da

Addresses review feedback — replaces the hand-rolled { subscribe } wrapper with svelte/store's readonly() helper. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel Bot deployed to Preview June 24, 2026 16:21 View deployment

ardiewen merged commit feab0d9 into main Jun 24, 2026
19 checks passed

ardiewen deleted the wcag/4.1.3-toaster-role-status-alert branch June 24, 2026 17:37

temporal-cicd Bot mentioned this pull request Jul 2, 2026

chore: bump version to 2.52.0 #3626

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

a11y(4.1.3): Toaster role="log" → per-toast role="status"/"alert" for correct AT announcement semantics#3560

a11y(4.1.3): Toaster role="log" → per-toast role="status"/"alert" for correct AT announcement semantics#3560
ardiewen merged 12 commits into
mainfrom
wcag/4.1.3-toaster-role-status-alert

rosanusi commented Jun 12, 2026 •

edited by ardiewen

Loading

Uh oh!

vercel Bot commented Jun 12, 2026 •

edited

Loading

Uh oh!

temporal-cicd Bot commented Jun 12, 2026 •

edited

Loading

Uh oh!

This comment was marked as outdated.

temporal-cicd Bot Jun 20, 2026

Uh oh!

temporal-cicd Bot Jun 22, 2026

Uh oh!

ardiewen commented Jun 24, 2026

Uh oh!

tegan-temporal Jun 24, 2026

Uh oh!

ardiewen Jun 24, 2026

Uh oh!

Uh oh!

tegan-temporal Jun 24, 2026 •

edited

Loading

Uh oh!

ardiewen Jun 24, 2026

Uh oh!

tegan-temporal left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

rosanusi commented Jun 12, 2026 • edited by ardiewen Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Approach

Why this shape

Test plan

Downstream (cloud-ui)

Uh oh!

vercel Bot commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

temporal-cicd Bot commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

temporal-cicd Bot Jun 20, 2026

Choose a reason for hiding this comment

Uh oh!

temporal-cicd Bot Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

ardiewen commented Jun 24, 2026

Update — reworked onto a shared LiveRegion/announcer primitive

What changed since the original PR

Final architecture

Decisions

Out of scope (follow-up: "ambient SR announcements")

Remaining gate

Uh oh!

tegan-temporal Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

ardiewen Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tegan-temporal Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ardiewen Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

tegan-temporal left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rosanusi commented Jun 12, 2026 •

edited by ardiewen

Loading

vercel Bot commented Jun 12, 2026 •

edited

Loading

temporal-cicd Bot commented Jun 12, 2026 •

edited

Loading

tegan-temporal Jun 24, 2026 •

edited

Loading