Writing Accessible Dialog Descriptions
Writing Accessible Dialog Descriptions records a distinct W3C-supported interface-content task while keeping implementation mechanics outside the writing guidance.
Use a short dialog description only when a brief block of text can clearly explain the dialog’s primary purpose or message; do not force complex multi-paragraph content into one description.
Key details
Important caveats
Scope Boundary
This page covers the wording chosen as a dialog description; deciding whether to apply aria-describedby and managing focus remain implementation concerns.
Further guidance
Content
Write a compact description that adds the dialog’s primary purpose, result, or message beyond the title when that information can be understood as a short linear announcement.
Practical Application
Write a short dialog description only when a compact block of text can explain the dialog’s main purpose, result, or message beyond its title.
Purpose
A concise description can add useful context after the dialog title without making users navigate the entire dialog before understanding its purpose.
Reader Check
Can the extra context be understood as a short linear announcement? If the dialog contains complex multi-paragraph content, do not compress it into one overloaded description.
Worked Example
Example: Title the dialog “Delete report” and add the concise description “This action cannot be undone” when that warning is the key extra context.
Sources and evidence
Sources are shown with the role they play in this guide. Historical or style-sensitive claims are kept within the evidence boundary described above.
- Dialog (Modal) Pattern — WAI-ARIA Authoring Practices Guide (opens in a new tab)World Wide Web Consortium (W3C) · W3C APG guidance for accessible dialog names, typically from a visible dialog title.