Consider discussing aria-describedby and aria-modal in dialog prose

[carmacleod]

Reading through the definition of dialog role, the prose feels "pretty skimpy". (Take a quick look at combobox for comparison.) Dialog is a complicated role, and authors often get it wrong. The spec could help by pointing out some things to take note of.

Stronger normative language for dialog label will be added when #1180 is merged. That's a great start, however I'd like to also add some words to draw attention to aria-describedby and aria-modal on dialog elements.

Description

Since aria-describedby (and the new aria-description) are global attributes, they hide in the list of inherited attributes unless they are called out in the prose. We could even consider some normative language around aria-describedby, such as perhaps:

If the dialog contains visible content that serves as a description, authors MAY (SHOULD?) use aria-describedby on the dialog element to point to that content, so that assistive technologies can read the content to the user when the dialog or an element in the dialog first gets focus.

Modal

Currently, the only thing the dialog spec says about the concept of "modal" is that:

A dialog that is designed to interrupt workflow is usually modal.

There's also a vague statement about:

authors SHOULD manage focus of modal dialogs.

...which may or may not mean trapping tabs and/or making content outside of the dialog inert, i.e. it's very unclear. I'm not even certain that "manage focus" is the correct phrase, because I think authors are unlikely to use the aria-activedescendant or roving tabindex strategies for managing focus that are described in the Managing Focus section of the spec.

Adding a sentence that links to the aria-modal definition will give authors a place to read more information about what it means to be "modal". It will also draw attention to aria-modal, which is also hidden in the list of inherited properties because dialog inherits it from window.

aria-modal is useful because it tells the user the dialog is modal, so they know they're in a place where reading and tabbing "should" be limited to content within the dialog. Of course, content outside of the dialog may or may not be removed from navigational shortcuts, but at least the user can decide whether to intentionally use those.

We could consider adding some normative language around aria-modal, while admitting that some authors prefer to use an inert polyfill:

If the dialog is modal, then authors SHOULD set the dialog's aria-modal to true, unless an alternate method is used to ensure that content outside of the dialog is hidden from assistive technologies.

ARIA Practices Guide

The APG does have a section on dialog, and some examples.
This is great, however I still think the spec needs to step up and make some assertions, because:

• the APG cannot make normative statements - only offer guidance
• the dialog role spec does not point directly to the dialog pattern guidance in the APG, so authors have to find the APG dialog guidance themselves (if they know to look)

[scottaohara]

Thanks for starting this @carmacleod

Definitely want to help out with this one :)

[LaurenceRLewis]

Just to mention @accdc Whatsock Roles Matrices has a description for dialog that seems to meet everything I have read in this discussion.

http://whatsock.com/training/matrices/#dialog-roles

[carmacleod]

Thanks, @LaurenceRLewis! There are some words in there that we can use.

[cmorten]

Extending the scope here slightly, I wonder if there is opportunity in #2054 to provide further clarity on the expectation of assistive technology for announcing a dialog’s accessible role and name in addition to the new clarification of announcing description?

@scottaohara has added:

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.

Could/should this be extended to include “accessible role, name, and descriptions”, or is role and name information nominally included in the definition of “descriptions”?

I have not tested extensively, but we appear to have precedent in at least NVDA and VoiceOver for MacOS for announcing this detail when an element contained within a dialog is brought to focus.

There is prior art for describing the expectation this way, see MDN:

When the dialog is correctly labeled and focus is moved to an element (often an interactive element, such as a button) inside the dialog, screen readers should announce the dialog's accessible role, name and optionally description, along with announcing the focused element.

REF: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role#possible_effects_on_user_agents_and_assistive_technology

At the moment it is not clear from the spec (I might be missing something) what the full intended purpose of providing an accessible name via aria-label or aria-labelledby on a role="dialog" is otherwise?

Beyond the standard use-case, presumably it is to address the nature of assistive technology announcing the dialog information upon focus of one of it’s child elements with a fallback of announcing the entire contents, but this is not stated explicitly.

There are hints that this is the generally understood behaviour in the community:

A dialog does not, and the screen reader should read up to the first focus (hopefully all ATs do this).
(In both cases, if aria-describedby/aria-description is set on them, then that should be read instead.)

REF: #1799 (comment)

Let me know if this is better placed on the PR or a new issue!