Aria-practices: Review modal dialog design pattern

[mcking65]

Drafting of the
modal dialog pattern
for issue #42 is complete, and it is ready for review.

Reviews requested as of March 16, 2017

• [x] Review by @annabbott
• [x] Review by @a11ydoer
• [x] Review by @jnurthen
• [x] Review by @MichielBijl

[mcking65]

@stevefaulkner, the issue you raised in #237 is now addressed in the current draft of the
modal dialog design pattern.

[annabbott]

Looks good.

[jnurthen]

If the content is large enough that focusing the first interactive element could cause the beginning of content to scroll out of view, it is advisable to add tabindex=0 to a static element at the top of the dialog, such as the dialog title or first paragraph, and initially focus that element.

I would normally recommend tabindex=-1 in this case, not tabindex=0

[jnurthen]

If the dialog is asking the user to confirm a destructive action, it may be advisable to set focus on the least destructive action, especially if undoing the action is difficult or impossible. The Alert Dialog Pattern is often employed in such circumstances.

I don't like the term destructive action as I see this applying in more cases than this (such as buying something from a store). How about:

"If the dialog is the final step in a process which is not easily reversible such as deleting data or completing a financial transaction, it is advisable to set focus on the least destructive action such as cancel. The Alert Dialog Pattern is often employed in such circumstances."

[jnurthen]

We should have aria-modal="true" on the modal dialog

[mcking65]

Based on other feedback I have received outside github, in commit b805355 I added the following to the states and properties section of the design pattern:

Optionally, if content outside a dialog is completely inert and visually obscured to an extent that is intentionally unreadable, each element containing a portion of the inert layer has aria-hidden set to true. In this circumstance, the dialog container element cannot be a descendant of an element that has aria-hidden set to true. However, if content outside a modal dialog is visually discernable, aria-hidden is not present.

[ZoeBijl]

This is a weird sentence:

If a dialog is limited to interactions that either provide additional information or continue processing, it might set focus to the element deemed to be most frequently desired, such as a OK or Continue button.

it might set focus to the element sounds like the dialog is a mythical beast we barely tamed; what else might it do? :O

I think it’s better to use something like focus should be set to the most frequently used element, such as an OK or Continue button.

Small change: a OK should be an OK no?

---

When a dialog closes, focus typically returns to the element that had focus before the dialog was invoked. This is often the control that opened the dialog. In circumstances where that element no longer exists, focus is set on an element that supports a logical work flow.

Why is it typically returns and not simply “returns”?

[jnurthen]

@jnurthen to redraft

Optionally, if content outside a dialog is completely inert and visually obscured to an extent that is intentionally unreadable, each element containing a portion of the inert layer has aria-hidden set to true. In this circumstance, the dialog container element cannot be a descendant of an element that has aria-hidden set to true. However, if content outside a modal dialog is visually discernable, aria-hidden is not present.

to note that with aria-modal this isn't really necessary now.

[jnurthen]

238 is related

[jnurthen]

Add text to clarify that the interface can only be controlled by elements that are descendents of the dialog

[mcking65]

Commit 2c2f6bc includes what I hope is the last significant set of revisions needed to close this issue. A description of the changes follows.

@jnurthen, @MichielBijl, @annabbott, @a11ydoer, @shirsha, please give the
modal dialog pattern
one more read through and comment as to whether you think we are ready to close this review.

Summary of changes in commit 2c2f6bc

In the introduction, to improve clarity, replaced:

The window under a modal dialog is typically inert; users cannot interact with content outside the dialog window.
If the background window is not inert, then interaction with elements in the background window cause the modal window to close.

With:

Windows under a modal dialog are inert. That is, users cannot interact with content outside an active dialog window.
Inert content outside an active dialog is typically visually obscured or dimmed so it is difficult to discern, and in some implementations, attempts to interact with the inert content cause the dialog to close.

To address feedback from @MichielBijl about the following note in the keyboard subsection, replaced:

If a dialog is limited to interactions that either provide additional information or continue processing, it might set focus to the element deemed to be most frequently desired, such as a “OK” or “Continue” button.

With:

If a dialog is limited to interactions that either provide additional information or continue processing, it may be advisable to set focus to the element that is likely to be most frequently used, such as an “OK” or “Continue” button.

To address feedback from @MichielBijl about the following note in the keyboard subsection, replaced:

When a dialog closes, focus typically returns to the element that had focus before the dialog was invoked.
This is often the control that opened the dialog.
In circumstances where that element no longer exists, focus is set on an element that supports a logical work flow."

With:

When a dialog closes, focus is set on an element that supports a logical work flow.
If the element that had focus before the dialog was invoked still exists, that element is usually the most appropriate choice.

Added a third note to the list of notes in the keyboard section:

It is strongly recommended that the tab sequence of all dialogs include a visible element with role button that closes the dialog, such as a close icon or cancel button.

In the states and properties subsection, to improve clarity, replaced:

All controls required to operate the dialog are child nodes of the element which has role set to dialog.

With:

All elements required to operate the dialog are descendants of the element that has role dialog.

In the states and properties subsection, to improve editorial consistency, replaced:

The aria-describedby property can be set on the element with the dialog role to indicate which element or elements in the dialog contain content that describes the primary purpose or message of the dialog.

With:

Optionally, the aria-describedby property is set on the element with the dialog role to indicate which element or elements in the dialog contain content that describes the primary purpose or message of the dialog.

In the states and properties subsection, to improve clarity and strengthen messaging, replaced:

If the dialog has aria-modal set to true and content outside the dialog is completely inert and visually obscured to an extent that is intentionally unreadable, it is no longer necessary to set aria-hidden to true on each element containing a portion of the inert layer.
However, if you do still use aria-hidden set to true, the dialog container element cannot be a descendant of any element that has aria-hidden set to true and the content outside the modal dialog must not be visually discernable.

with two notes:

• Because marking a dialog modal by setting aria-modal to true can prevent users of some assistive technologies from perceiving content outside the dialog, users of those technologies will experience severe negative ramifications if a dialog is marked modal but is not modal for other users. So, mark a dialog modal only when:
  
  
  
  1. Application code prevents all users from interacting in any way with content outside of it.
  
  
  2. Visual styling obscures the content outside of it.
  
  
• The aria-modal property introduced by ARIA 1.1 replaces aria-hidden for informing assistive technologies that content outside a dialog is inert. However, in legacy dialog implementations where aria-hidden is used to make content outside a dialog inert for assistive technology users, it is important that:
  
  
  
  1. aria-hidden is set to true on each element containing a portion of the inert layer.
  
  
  2. The dialog element is not a descendant of any element that has aria-hidden set to true.
  
  

[a11ydoer]

Thanks for all the edits you made @mcking65

Here is my subjective comments for keyboard subsection edit change.
I prefer original edit rather than revised one because

• original edit gives more contextual information about focus management (ie. "return" vs "set")
• "the most appropriate choice" is very vague concept in revised edit. In original edit, it clarifies that the most appropriate choice is "an element that supports a logical work flow"

I copied both edits for comparison.

Original
When a dialog closes, focus typically returns to the element that had focus before the dialog was invoked. This is often the control that opened the dialog. In circumstances where that element no longer exists, focus is set on an element that supports a logical work flow.

Revised edit:

When a dialog closes, focus is set on an element that supports a logical work flow.
If the element that had focus before the dialog was invoked still exists, that element is usually the most appropriate choice.

[a11ydoer]

@mcking65 @jnurthen
In "two notes" sections, the last edit, I found the second note are very helpful information. Thanks for adding that. In the first note, you meant "setting aria-modal to true" as "marking a dialog modal". What do you mean by "but is not modal for other users."?

[mcking65]

@a11ydoer commented:

In the first note, you meant "setting aria-modal to true" as "marking a dialog modal". What do you mean by "but is not modal for other users."?

I meant "does not behave as a modal for other users." I modified the sentence in commit cd6d9d5.

[mcking65]

@a11ydoer, @annabbott, @jnurthen, @MichielBijl, or others ...

Any preferences between either of the following, or suggestions for tweaks:

Option A:

When a dialog closes, if the element that invoked the dialog exists, focus typically returns to that element.
Otherwise, focus is set on an element that provides logical work flow.

Option B:

When a dialog closes, focus typically returns to the element that invoked the dialog.
If that element no longer exists, focus is set on another element that provides logical work flow.

I believe option A implies a greater level of latitude and option B is thus more restrictive.

Thinking more about giving clear and actionable guidance, neither is fabulous because we do not have a place in the guide that illustrates what we mean by a logical workflow. And, you can do things that are logical that would be rather lousy from an accessible experience perspective.

If anyone can concisely describe some additional circumstances where focus would not go to the invoking element, we may be able to make the guidance more useful.

[annabbott]

My preference is Option B with a tweak to each sentence:

When a dialog closes, return focus to the element that invoked the dialog.
If that element no longer exists, focus is set on an element that provides logical work flow.

Reasoning: maintaining the user's point of regard, if the element still exists, should be the main consideration when the dialog closes.

[annabbott]

I received email notification:
Modal Dialog Pattern: Modify Warning About Use of aria-modal
Per feedback from @annabbott on issue #325 in the May 1, 2017 task force meeting, changed:

So, mark a dialog modal only when:
To add the word both:
So, mark a dialog modal only when both:

However, I do not see that change in 2.9 Dialog (Modal) > WAI-ARIA Roles, States, and Properties > Note > first bullet.

[mcking65]

@annabbott commented:

My preference is Option B with a tweak to each sentence:

When a dialog closes, return focus to the element that invoked the dialog.
If that element no longer exists, focus is set on an element that provides logical work flow.

Ann, if we write it that way, we are saying that the only time focus does not go to the element that opened the dialog is when that element does not exist. I don't think we want to say that.

[mcking65]

@annabbott commented:

I received email notification:
Modal Dialog Pattern: Modify Warning About Use of aria-modal Per feedback from @annabbott on issue #325 in the May 1, 2017 task force meeting, changed:
So, mark a dialog modal only when:
To add the word both:
So, mark a dialog modal only when both:

However, I do not see that change in 2.9 Dialog (Modal) > WAI-ARIA Roles, States, and Properties > Note > first bullet.

It's there if you look now. I had to do a manual build to push the change; the automatic push to gh-pages isn't working.

[annabbott]

annabbott commented:

My preference is Option B with a tweak to each sentence:

When a dialog closes, return focus to the element that invoked the dialog.
If that element no longer exists, focus is set on an element that provides logical work flow.

Ann, if we write it that way, we are saying that the only time focus does not go to the element that opened the dialog is when that element does not exist. I don't think we want to say that.

@mcking65 : I don't know why we wouldn't want to say that. Design, Dev and Test have no understanding of maintaining the user's point of regard so I think we should say that.

[annabbott]

Confirmed that I do see that change in 2.9 Dialog (Modal) > WAI-ARIA Roles, States, and Properties > Note > first bullet.

[mcking65]

With commit 9ae09df, revised note 2 in the keyboard subsection of the design pattern to read as follows.

1. When a dialog closes, focus returns to the element that invoked the dialog unless either:
   
   
   
   • The invoking element no longer exists. Then, focus is set on another element that provides logical work flow.
   
   
   • The work flow design includes the following conditions that can occasionally make focusing a different element a more logical choice:
     
     A. It is very unlikely users need to immediately re-invoke the dialog.
     
     B. The task completed in the dialog is directly related to a subsequent step in the work flow.
     
     For example, a grid has an associated toolbar with a button for adding rows. the Add Rows button opens a dialog that prompts for the number of rows. After the dialog closes, focus is placed in the first cell of the first new row.
   
   

[mcking65]

Per discussion in today's task force conference call, task force review of this pattern is now complete. Thank you team!