Receive Plain-Language Error Feedback on Login Failure
When authentication fails — whether due to wrong credentials, network issues, or a locked account — the peer mentor must receive immediate, understandable feedback. Error messages must be written in plain language (no technical jargon), must not expose security details (e.g. must not confirm whether the email exists), and must guide the user toward a resolution. Network errors must be distinguished from credential errors. The error must be accessible to screen readers via a live region announcement.
User Story
Audience Summaries
Clear, plain-language error feedback during login directly protects user retention among the most vulnerable segments of the peer mentor population — including users with cognitive disabilities, low digital literacy, and older adults. When authentication fails silently or with technical jargon, these users abandon the app entirely or escalate to coordinators for manual support, creating operational overhead and reducing data quality from missed registrations. By delivering immediate, actionable error messages that distinguish network problems from credential issues, the platform enables self-service resolution without coordinator intervention. This directly reduces support costs, sustains engagement rates, and fulfills the universal design commitments made to all three participating organisations.
For field-based workflows where coordinators are not available in real time, self-sufficient error recovery is not optional — it is a prerequisite for consistent reporting and program outcome measurement.
This high-priority story has a well-defined scope but requires careful coordination between UX writing, accessibility review, and QA. The five acceptance criteria cover distinct failure scenarios — credential mismatch, network timeout, screen reader announcement, stale error clearing, and server-side lockout messaging — each requiring its own test case and validation path. Accessibility testing must include assistive technology verification with at least one screen reader (VoiceOver, TalkBack), adding specialist QA time to the delivery estimate. A dependency on the core email/password login story (story-email-password-login-peer-mentor-001) must be completed before integration testing can begin.
UX copy for all error messages must be approved by an accessibility or plain-language reviewer before sign-off. Rollout risk is low if error states are implemented as a standalone presentational layer, but regression testing across all login failure paths is essential before release.
Implementation requires an ARIA live region (role='alert' or aria-live='assertive') injected into the login form DOM to enable automatic screen reader announcement on error render — this must not require user focus navigation to trigger. Error messages must be stored as constants mapped to failure types: credential failure maps to a generic 'Incorrect email or password' string (avoiding email enumeration), network timeout maps to a connectivity-specific message, and server-side lockout responses must be relayed in plain language without exposing raw API error codes. An onChange or onInput listener on both the email and password fields must clear the active error state to prevent stale feedback confusion. The network error vs credential error distinction requires inspecting the HTTP response status and catch block error type (e.g., fetch timeout vs 401/403).
All error rendering must be handled through the existing authentication state model with no new global state introduced. Unit tests should cover each failure type and the ARIA announcement behavior.
Acceptance Criteria
- Given incorrect credentials are submitted, When authentication fails, Then the message 'Incorrect email or password. Please try again.' is displayed prominently below the form
- Given a network timeout occurs during login, When the request fails, Then the message 'Unable to connect. Check your internet connection and try again.' is shown
- Given a screen reader is active and an error appears, When the error is rendered, Then the screen reader announces the error text automatically without requiring the user to navigate to it
- Given an error message is displayed, When the user begins editing the email or password field, Then the error message is cleared so the user is not confused by stale feedback
- Given three consecutive failed login attempts, When the fourth attempt is made, Then the UI does not lock the user out locally but communicates any server-side lockout message in plain language
Business Value
Clear error feedback is critical for peer mentors who include users with cognitive disabilities, low digital literacy, and older adults. Confusing or technical error messages lead to users abandoning the app or requiring coordinator support to log in. Plain-language errors reduce support burden, increase self-service resolution, and align with the universal design mandate shared by all participating organisations.
Components
- Login Screen ui
- Login Form ui
- Login Form BLoC service
- Credential Validator service
- Authentication Service service
- Supabase Auth Client infrastructure
- Plain Language Error Display ui
- Live Region Announcer ui
Dependencies
- Sign In with Email and Password critical