Reading order does not match visual order

[karlgroves]

Reading order does not match visual order

• Severity: Low
• Affected Populations:
  • Low-Vision
  • Cognitively Impaired
• Platform(s):
  • All / Universal
• Components affected:
  • Tools and Options

Issue description

When assistive technology users are reading through the "Keyboard
Shortcuts" list, the items in the list are announced differently than
their visual order: each shortcut keystroke is announced before its
description, even though the description comes first visually.

Users who need an alternative presentation of content benefit from a
logical reading order. Users who have a cognitive disability and have
difficulty reading may also be confused by an unexpected or illogical
reading order when using text-to-speech programs.

Issue Code

    <dl class="edit-post-keyboard-shortcut-help__shortcut-list">


        <div class="...">


            <dt class="edit-post-keyboard-shortcut-help__shortcut-term">


                <kbd class="...">...</kbd>


            </dt>


            <dd class="edit-post-keyboard-shortcut-help__shortcut-description">


                Display this help.


            </dd>


        </div>


        ...


    </dl>





    ...





    .edit-post-keyboard-shortcut-help__shortcut-term {


        order: 1;


        ...


    }


    .edit-post-keyboard-shortcut-help__shortcut-description {


        flex: 1;


        order: 0;


        ...


    }

Remediation Guidance

Avoid the use of flexbox order properties to change the order of
elements, because this change is not reflected in the DOM reading
order.

It appears as though this has been done so that the description can be
the <dd> and the keystroke can be the <dt>, however this is
not necessary. The description can be considered the term, since it's
the primary frame of reference for a user (i.e. a user wouldn't
encounter a keystroke and wonder what function it controls, they would
encounter a function and wonder what keystroke can be used for it).

Therefore, the order property can be removed, and the markup
inverted to use <dt> for the description and <dd> for the
keystroke.

Recommended Code

    <dl class="edit-post-keyboard-shortcut-help__shortcut-list">


        <div class="...">


            <dt class="edit-post-keyboard-shortcut-help__shortcut-term">


                Display this help.


            </dt>


            <dd class="edit-post-keyboard-shortcut-help__shortcut-description">


                <kbd class="...">...</kbd>


            </dd>


        </div>


        ...


    </dl>

Relevant standards

• 1.3.2 Meaningful Sequence
  (Level A)

Note: This issue may be a duplicate with other existing accessibility-related bugs in this project. This issue comes from the Gutenberg accessibility audit, performed by Tenon and funded by WP Campus. This issue is GUT-71 in Tenon's report

[melchoyce]

Screenshot from the full report:

[afercia]

On the related W3C recommendation there's an entire section dedicated to the flexbox order property and accessibility: https://www.w3.org/TR/css-flexbox-1/#order-accessibility

It's well known that order shouldn't be used this way.

I'd like to add that the use of a <dl> is questionable to start with, as assistive technologies support is inconsistent at best and misleading most of the times. Some testing from @aardrian https://codepen.io/aardrian/full/NzGaKP

Suggest: use a normal unordered list.

[afercia]

For reference and future implementations: here's a practical example of <dl> elements announced incorrectly by screen readers. More testing data on the codepen linked above.

Safari and VoiceOver initially announce the first <dl> as "description list" with 12 items:

But then, when navigating through the items, their count is based on a total of 24. Items are announced as "1 of 24", "2 of 24", etc. Highly confusing for users:

Additionally, <dt> and <dd> elements are not announced as "term" and "description", making the usage of <dl> elements a bit pointless in the first place.