accessible-notifications

name

accessible-notifications

description

Guidance for accessible user notifications and feedback. AUTO-TRIGGER when implementing: toasts, snackbars, notifications, alerts, flash messages, status messages, success/error feedback, or any transient UI messages. Triggers include: "toast", "snackbar", "notification", "flash message", "notify user", "show success", "show error", "feedback message", "status update", "auto-dismiss", "popup message". Use this skill BEFORE implementing any toast-like patterns to ensure accessibility compliance.

Accessible Notifications

Critical: Toasts Are Not Recommended

Toasts pose significant accessibility concerns and should be avoided. Use the alternatives below instead.

Why Toasts Are Problematic

WCAG Violations

• 2.2.1 Timing Adjustable (A): Auto-dismiss prevents users from reading content
• 1.3.2 Meaningful Sequence (A): DOM placement disconnects toast from trigger
• 2.1.1 Keyboard (A): Focus management is complex and often broken
• 4.1.3 Status Messages (AA): Assistive technology announcements are disruptive

Usability Issues

• Large displays: Toasts appear outside user's field of view
• Screen magnification: Toast may be outside magnified area
• Multitasking: Auto-dismiss causes missed messages
• Blocking UI: Floats over important content like submit buttons

What to Use Instead

Successfully-Completed Simple Actions

Do nothing extra. Success should be self-evident.

<!-- User creates issue → Issue appears in list -->
<!-- No toast needed - the result IS the feedback -->

Successfully-Completed Complex Actions

Use persistent banners or progressive content display:

<Banner v-if="bulkResult" variant="success">
  Created {{ bulkResult.count }} issues successfully.
  <RouterLink :to="{ name: 'issues' }">View all</RouterLink>
</Banner>

Unsuccessful Actions (Errors)

Use inline validation or banners:

<!-- Inline validation for forms -->
<FormField :error="errors.email">
  <Input v-model="email" />
</FormField>

<!-- Banner for system errors -->
<Banner v-if="submitError" variant="destructive">
  {{ submitError.message }}
</Banner>

Form Submission Success

Use interstitial confirmation or redirect with banner:

<!-- Option 1: Confirmation page -->
<ConfirmationPage v-if="submitted">
  Your request has been submitted. Reference: #{{ referenceId }}
</ConfirmationPage>

<!-- Option 2: Redirect to result -->
// router.push({ name: 'item-detail', params: { id: newItem.id } })

Long-Running Tasks

Use persistent banners + other channels (email, push notifications):

<Banner v-if="taskComplete" variant="success">
  Export complete. <a :href="downloadUrl">Download file</a>
</Banner>

Assistive Technology Announcements

When to Announce

• Always: Location changes, navigation
• Always: Failed user actions (validation, errors)
• Sometimes: Essential streaming content (logs)
• Avoid: Non-essential updates (presence indicators, comments by others)

Implementation

Use aria-live regions for dynamic content that must be announced:

<div aria-live="polite" aria-atomic="true" class="sr-only">
  {{ statusMessage }}
</div>

Quick Decision Guide

Scenario	Solution
Simple action succeeded	No feedback needed
Complex action succeeded	Persistent banner
Action failed	Inline error or banner
Form submitted	Confirmation page or redirect
Long task complete	Banner + email/push
Need user attention	Dialog (interruptive)