ARIA document role: several incorrect information pieces

MDN URL

https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/document_role

What specific section or headline is this issue about?

Description, ARIA properties, keyboard interactions, best practices

What information was incorrect, unhelpful, or incomplete?

The article needs some corrections/clarifications.

1. The example shows <dialog>...<document tabindex=0>...</document></dialog> while stating that a dialog is a "composite widget". Role=dialog is a window role, not an application or composite widget.

This is an incorrect implementation and misinforms authors about dialogs: AT virtual document/"browse" mode is NOT disabled within a dialog, so this ability doesn't need to be "restored", and focus should NOT be managed within a dialog itself; only composite widgets if nested inside the dialog.

2. "Aria-expanded" is not permitted on role=document. In fact, it should never be applied to content itself, but on the widget that controls that content.

3. Tabindex is not an ARIA role, state, or property. Not sure if this is standard across other MDN documents, but noting the distinction would help authors.

4. The article would benefit from clarifying that including an element in natural tab order via tabindex=0 is just one technique to ensure users can reach it, and may not be appropriate in all cases. Authors should be advised of potential focus order issues when using tabindex=0 inside a composite widget with managed focus. E.g., how users will know to press Tab when the rest of the area uses arrow keys, how to navigate back into the widget when surrounding elements have a roving tabindex, etc.

5. The article states:

In contrast to the article role, the document role does not have any relation to other elements with a document role, it merely has a relationship to the containing composite widget. An article can have associated articles.

At minimum, this paragraph needs clarification.

Saying that a document-role element "can't" have a relationship with other document-role elements may lead authors to create content that fails info & relationships. If this section is kept, authors would benefit from examples of how to appropriately conform to WCAG when the documents' content is related.

It should also be clarified that articles can't be directly programmatically associated with each other. Authors would benefit from understanding that when it says "An article can have associated articles", that association would have to be intentionally conveyed by the context, e.g. a shared parent heading, list items with a list, a landmark, etc.

What did you expect to see?

Information that conforms with ARIA specifications, accurate explanations of expected AT behavior with specified roles, warnings when techniques implemented in the wrong context may cause WCAG failures, and best practice advice that is clearly explained and widely-agreed upon by the accessibility community, preferably sourced from recognized expert opinions or user research.

Do you have any supporting links, references, or citations?

1. https://w3c.github.io/aria/#window_roles
2. https://w3c.github.io/aria/#attrs_widgets

Do you have anything more you want to share?

No response

MDN metadata

• Folder: en-us/web/accessibility/aria/roles/document_role
• MDN URL: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/document_role
• GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/accessibility/aria/roles/document_role/index.md
• Last commit: https://github.com/mdn/content/commit/019ca5c9ce641bfa02825e1ba0444f35dfb646cc
• Document last modified: 2024-04-17T05:19:10.000Z