Accessibility: add sections to main content

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

• Close this issue

I’ve taken a screenshot of the regions on a merge request page, and some significant portions of a MR page aren't represented. Here's an overview:

I'll attach a full screenshot to this MR, showing how incredibly long the main section can get. From a screenreader perspective, this is tedious and frustrating.

The question: accessibility inside 'main'

How can we make it possible for a screenreader to jump around inside the main body of the merge request, so the user doesn't have to listen to the entirety of the MR description to get to the merge widget, comments, or the comment form?

Possible solutions

I want to be clear that I'm not an expert here, but I think something would be better than nothing.

One of the easiest answers would be a (linked) subheading that starts (each of) the MR widget, comment threads, and comments area. However, the only area that currently contains a headline of any kind is the H5 for Linked Issues. We'd have to change designs over to use subheadings. I'm not sure how much redesign / refactoring would be required.

Another possibility would be to add <section> wrappers around these chunks of content?

Another would be to add role= and aria-label to reasonably appropriate (and existing) divs.

Extra notes

@andr3 asked me to file this issue, noting:

section sounds great and if we can get rid of some divs on the way, we should! 😄 I’d probably suggest having a revision of the headings too, to improve the document outline. (HTML5 introduced a new way to reset the heading numbering on every sectioning element, but it’s not very reliable, IIRC).

Could you please open an issue for this if you haven’t already, @amy Qualls? I’d love to prioritise this soon. It’s fairly straight-forward if we have the “map” thought out in advance. (This has come up in the past when we were talking about improving the skip links: https://gitlab.slack.com/archives/CJEU9TW5D/p1616786422054000?thread_ts=1616760839.040300&cid=CJEU9TW5D )

Amy also notes: I really should finish setting up NVDA to test if the behavior is the same as in VoiceOver. @jeldergl posted instructions in https://gitlab.com/gitlab-org/gitlab-services/design.gitlab.com/-/blob/main/doc/nvda-setup.md over the last few days.

@andr3, @jeldergl, please add whatever labels are needed. I'm not 100% clear what we should have. Also, a CC to @NicoleSchwartz because she might have helpful suggestions here.