document role needs fleshing out

[brennanyoung]

The document role has a very specific use case - it should only be used within an 'interactive' context, such as a role=application.

When assistive tech is in forms/focus mode (key events passed to the activeElement), there is occasionally a need to browse rich text (headings, paragraphs, lists etc.) - in other words, there is a need to return to browse mode. The document role is expressly intended for these cases.

More importantly, document role is the only non-interactive role which should be given a tabindex attribute. The structure might be something like

<h1>Foo</h1>
<p>Yadda yadda</p>
<div role=application>
    <!-- various focusable, interactive app things here -->
    <div role=document tabindex=0>
        <h2>Bar</h2>
        <p>Yabba dabba</p>
    </div>
    <!-- various other focusable, interactive app things here -->
</div>

So, your focus is inside role=application, and tabbing from UI control to UI control, and you tab to something with role=document. At this point, the assistive tech should switch back to browse mode, providing keyboard shortcuts for browsing.

The main caveat (AFAICT) is that you can't put any interactive content inside the nested document, because that will put the AT back into forms mode, and you wont be able to browse the rich text any more. (Tabbing out and back in again might work in some cases, however). Not sure if this constraint is intended (spec does not mention it), but that's how it works with (e.g.) NVDA.

Implicit in all of this, is that role=document is entirely irrelevant in a browse-mode context. This too is unmentioned in the spec.

Vague and scary warnings about the roles application and document are common in discussions about accessibility, but there's very little information about why they may be tricky, or how they should behave. This is the second resource I have found in two days which 'skimps' on detail in this area. They are under-documented, and far less well-established than certain other roles. No doubt the support from browser vendors and assistive tech is far from perfect, for the same reason.

But both roles exist for a good reason, and support will never improve unless we give them some proper attention: testing, clear documentation and real world use.