Receive Immediate Screen Reader Announcements for Dynamic Content Changes

The Semantic Label Service is responsible for triggering live region announcements whenever dynamic UI state changes occur. This includes: inline form validation errors appearing after field blur, submission success or failure toasts, loading spinner state changes (start/complete), list refresh completions, and notification badge count updates. The service must use Flutter's SemanticsService.announce() or equivalent live region marking to push announcements to the screen reader without shifting visual focus. Announcement text must be concise, action-oriented, and localized. The service must also resolve organization-specific dynamic labels (from the Labels Config system) into screen-reader-appropriate text before announcing.

HIGH story-screen-reader-support-peer-mentor-004 8 pts

Story Points

High

Priority

Screen Reader Support

Feature

User Story

As a user

I want my screen reader to automatically announce dynamic content changes — such as form validation errors, loading completion states, success or failure confirmations, and updated list content — without requiring me to manually navigate to discover them

So that So that I can complete tasks efficiently without losing my place in the interface when the app responds to my actions, and so that error states do not go unnoticed causing silent failures

Acceptance Criteria

Given a user submits an activity registration form with a missing required field, when the validation error appears inline, then VoiceOver announces the specific error message within 500ms without focus shifting away from the current field
Given a user triggers a Bufdir report generation, when the loading spinner appears and then completes, then VoiceOver announces 'Report generation started' and subsequently 'Report ready for preview' without requiring navigation
Given the contact list refreshes after a pull-to-refresh gesture, when new items are loaded, then TalkBack announces the updated item count
Given a duplicate activity warning dialog appears, when it opens, then VoiceOver immediately announces the dialog title and primary action without the user needing to swipe to it
Given an organization uses a custom label for 'Peer Mentor' (e.g., 'Likeperson'), when the screen reader encounters that label in any announcement, then the organization's custom term is used rather than the default
Given a push notification arrives while the user is in the app, when the notification banner appears, then an announcement is made that does not interrupt an ongoing form entry interaction mid-word

Business Value

Screen reader users are entirely dependent on audio feedback to understand state changes in the UI. Without live region announcements, errors are silent, confirmations are invisible, and the user must manually explore the entire screen after every action to determine what changed. This creates an unacceptable burden for visually impaired peer mentors completing time-sensitive registrations in the field. Proper dynamic announcements are a core WCAG 2.2 AA requirement (Success Criteria 4.1.3) and are essential for the app to be genuinely usable rather than merely technically accessible.

Components

Semantic Label Service service
Accessible Widget Library ui

Screen Reader Support

Related Feature

Peer Mentor (Likeperson)

User Role