Background

In legacy Vector the TOC was located after the page title as part of the page content. This location was ideal for a few reasons, the TOC should be located inside the main element as it contains content specific to the page, and the TOC should follow the h1 for easy access for navigating the rest of the page. Legacy Vector's TOC is even frequently used as an example in accessibility guidance (i.e. inclusive components)

Due to the design of the TOC in modern Vector and limitations with Vector's layout CSS, the TOC was moved before the main element. The new DOM location means that keyboard/screenreader users who arrive at the page title (i.e. using the skip link, the main landmark, or h1) will skip over the TOC. It also resulted in other tradeoffs, like the replacement of the "Contents" h2 with a p element and the removal of h3s from the main menu to preserve the heading order (as mentioned in T311294). From a technical perspective, these semantic issues could mean Vector is more prone to other issues in the future, as there isn't a sensible source order to fallback on.

However, with the introduction of CSS grid to Vector, it should be possible to restore the original source ordering, and move the entire sidebar (including the TOC and main menu) after the page title (after article tools would probably make most sense). This would improve the UX of screenreader/keyboard users to be on par with legacy Vector and help future proof Vector from similar issues in the future.

Note

A downside to this is that there will be more elements between the h1 and the rest of the article content. My perspective is that this is to a certain extent unavoidable considering modern Vector's design, which moves several menus to be visually below the h1. It's a bit of a tradeoff between a good source order and some expected verbosity, and this will probably be addressed by T312818. Perhaps we could research how much of an issue this poses for users in the future

AC

• No visual changes
• TOC and main menu are located in the DOM after article tools. New tab order should reflect this.
• TOC "Contents" title should be a h2 element