Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update dialog definition #2054

Merged
merged 3 commits into from
Dec 11, 2024
Merged

Update dialog definition #2054

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cdba2eb
Update dialog defnition
scottaohara Oct 2, 2023
9f945a7
address feedback
scottaohara Dec 14, 2023
c66033a
Update index.html
scottaohara Dec 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 17 additions & 3 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3055,10 +3055,24 @@ <h2>Definition of Roles</h2>
<div class="role" id="dialog">
<rdef>dialog</rdef>
<div class="role-description">
<p>A dialog is a descendant window of the primary window of a web application. For HTML pages, the primary application window is the entire web document, i.e., the <code>body</code> element.</p>
<p>Dialogs are most often used to prompt the user to enter or respond to information. A dialog that is designed to interrupt workflow is usually modal. See related <rref>alertdialog</rref>.</p>
<p>A dialog is a descendant window of the primary window of a web application. For HTML pages, the primary application window is the entire web document, i.e., the content the user interacts with, within the <code>body</code> element.</p>
scottaohara marked this conversation as resolved.
Show resolved Hide resolved
scottaohara marked this conversation as resolved.
Show resolved Hide resolved
<p>Dialogs are often used to prompt the user to enter or respond to information, or can represent content related to understanding or modifying the content of the primary application window. A dialog that is designed to interrupt workflow and prevent users from interacting with the primary web application is usually modal. See related <rref>alertdialog</rref>. A dialog that allows for the user to switch between interacting with the content of the primary web application and the content the dialog is usually modeless (i.e., non-modal). In lieu of using robust host language features for marking content of the primary web application as <code>inert</code>, authors SHOULD use the <pref>aria-modal</pref> attribute, and constrain focus to dialogs. See the <a href="https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/">WAI-ARIA Authoring Practices: Dialog (modal) pattern</a> for additional details on implementing modal dialog design patterns.</p>
<p>Authors MUST provide an accessible name for a dialog, which can be done with the <pref>aria-label</pref> or <pref>aria-labelledby</pref> attribute.</p>
<p>Authors SHOULD ensure that all dialogs (both modal and non-modal) have at least one focusable descendant element. Authors SHOULD focus an element in the modal dialog when it is displayed, and authors SHOULD manage focus of modal dialogs.</p>
<p>Authors SHOULD ensure that all dialogs (both modal and non-modal) have at least one focusable descendant element. Authors SHOULD focus an element in the modal dialog when it is displayed, and authors SHOULD constrain keyboard focus to focusable elemenets within a modal dialog, until dismissed.</p>
scottaohara marked this conversation as resolved.
Show resolved Hide resolved
<p>Authors SHOULD provide a dialog an accessible description, with the <pref>aria-describedby</pref> attribute, for instances where authors have set initial keyboard focus on an element that follows content that outlines the purpose of the dialog. Assistive technology SHOULD give precedence to exposing author defined dialog accessible descriptions when a dialog is invoked and user focus is moved to a descendant of the dialog element.</p>
<div class="note">
<p>Authors are strongly encouraged to use <pref>aria-describedby</pref>, rather than <pref>aria-description</pref>, to provide descriptions to dialogs. While <code>aria-description</code> could be used to provide an accessible description for a dialog, it will provide a better and more consistent user experience to reference visible content that can also be independently read by all users. Doing so will help ensure important descriptive information is less likely to be missed.</p>
</div>
<aside class="example">
<p>In the following example, the first text field will receive initial focus when the dialog is rendered. As this means focus will be set "after" the preceding content that provides instructions for the form fields, an <code>aria-describedby</code> attribute is used to expose this content as a description for the <code>dialog</code>.
<pre>&lt;div role="dialog" aria-labelledby="h" aria-describedby="d" aria-modal="true" ...>
&lt;h2 id="h">Add Shipping Address&lt;/h2>
&lt;p id="d">By placing an order on this website, you acknowledge we will be sending you tons of junk mail for you to immediately recycle. Thanks!&lt;/p>
&lt;label>
Street: &lt;input autofocus ...>
&lt;/label>
...
&lt/div></pre></aside>
<p class="note">In the description of this role, the term "web application" does not refer to the <rref>application</rref> role, which specifies specific assistive technology behaviors.</p>
</div>
<table class="role-features">
Expand Down
Loading