Skip to content

Docs: clarify toast accessibility guidance#42276

Open
monsonego wants to merge 1 commit intotwbs:mainfrom
monsonego:docs/toast-accessibility-warning
Open

Docs: clarify toast accessibility guidance#42276
monsonego wants to merge 1 commit intotwbs:mainfrom
monsonego:docs/toast-accessibility-warning

Conversation

@monsonego
Copy link
Copy Markdown

@monsonego monsonego commented Apr 5, 2026

Description

  • add a warning callout to the toast accessibility section
  • clarify that toasts are best for optional, non-critical updates
  • recommend alerts for messages that require immediate attention or user action

Motivation & Context

Issue #41873 asks for clearer guidance about the usability and accessibility tradeoffs of toast notifications. The page already explains the ARIA setup for toasts, but it does not explicitly warn readers when a toast is the wrong pattern to use.

This change adds that guidance directly in the existing accessibility section and points readers to alerts when a message should be more persistent.

Type of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Refactoring (non-breaking change)
  • Breaking change (fix or feature that would change existing functionality)

Checklist

  • I have read the contributing guidelines
  • My code follows the code style of the project (using npm run lint)
  • My change introduces changes to the documentation
  • I have updated the documentation accordingly
  • I have added tests to cover my changes
  • All new and existing tests passed

Live previews

Validation

  • ran npm run docs-prettier-check
  • reviewed the MDX diff to confirm the guidance is placed in the Accessibility section and uses the existing docs callout pattern
  • confirmed the Netlify deploy preview was created successfully
  • not run the full docs build locally in this environment

Related issues

Closes #41873

@monsonego monsonego changed the title Docs: add toast accessibility warning Docs: clarify toast accessibility guidance Apr 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: warn about usability / accessibility issues of Toasts

2 participants