Reader Interface Page Structure A11y improvement

[StephDriver]

closes #4232
closes #3937
closes #3914
closes #3915
closes #4212
addresses some of #4482

[StephDriver]

Task List

Landmarks

• remove 'space images' landmark
• update existing landmarks to consistent syntax, in line with W3C guidelines
• add navigation landmark to OLH
• tidy up section regions
• markup Table of Contents as a landmark
• tidy article landmarks
• markup other side content as Aside (not possible within template structure - so mark up as section region with appropriate headings)

Headings

• identify all headings
• ensure no template has multiple H1 (check logic of templates where multiples exist so that no more than one is rendered)
• skip deprecated templates
• work through all identified headings, until all have been reviewed and updated as required.
• add logic for templates where a clash of required heading level was found from different includes

Other

• make use HR tags consistent

NOTE
reworking the visual display or template hierarchy of pages is out of scope for this issue, so there are places where compromises have to be made so a11y improves, but the ideal solution is not implemented. For example, ideally a region would be defined around the whole area related to that content, but this is not always possible within the template structure, so some regions are defined around the start of that area instead - i.e. the landmark would take a user to where that area begins, but does not fully surround all the content.

[StephDriver]

Accessible Structure Syntax

(this documentation to be added to A11y dev docs)

Landmarks

Following the W3C guidance on landmark regions, our landmarks will primarily use HTML sectioning, only including roles and / or aria labels where the HTML alone is not sufficient.

📋 Note: the structure of our current theme templates is such page content is all inside main such that other top-level landmarks cannot be added within the page contents. This gives us a very flat structure (see basic structure below) with all other landmarks inside the main. This compromise will be addressed in our next theme design.

Page Structure

Basic

All individual page content is within the main landmark. The header, nav and footer are standardised with variations for Journal, Repository and Press.

header
nav
main
footer

Pages with side content and on-page navigation (e.g. articles)

📋 Note: Ideally, the side content (downloads, metadata etc) would be a complementary landmark and the table of contents would be a <nav>. But this only works at top level where such landmarks are siblings to the main, not child content. Rather than wait for our next theme design, we are improving accessibility by including sections with aria markup.

header
nav
main
    article
    section aria-label="article information"
    section aria-labelledby="id_of_table_of_contents_heading"
footer

Pages with filters and/or search results

header
nav
main
    section aria-label="results"
    section aria-labelledby="search-title"
    section aria-labelledby="filter-title"
footer

Pages with a several different blocks of 'slot in' content, e.g. journal home page

Consider each block as to whether that would benefit from being a region, for example:

header
nav
main
    section aria-labelledby="about-title"
    section aria-labelledby="latest-news-title"
    section aria-labelledby="current-volume-title"
    etcetera ...
footer

Landmark Syntax

Classes, IDs and etc may be included within these tags, only the landmark related syntax is shown.

Where possible use aria-labelledby="id_of_heading_of_section", as this means that the screenreader text will stay consistent with any changes to onscreen text. aria-label only to be used for landmarks where aria-labelledby is not suitable e.g. when there is no heading. In such cases, first consider whether there should be a heading, and if so include one.

Landmarks should be used sparingly.

Header

<header> ... </header>

Nav

<nav> ... </nav>

Article

Currently we use this for article content on the articles page only.

📋 In future we should consider using article landmarks for other content, e.g. news items.

<article> ... </article>

Aside

📋 Currently we are not using Aside as a landmark, because this only works at top level, and our template structure places the whole template inside main, meaning any content inside a template is within the main landmark.

Section

Landmarks should be used sparingly, and most sections are not landmarks. Including an aria-label / labelledby defines this as a landmark. Where a section is expected to form a distinct part of a multisection page, a landmark should be considered, where it covers content that would be considered 'main' it should not be distinguised from the main landmark. For example, use a landmark section for areas of the homepage (news, current issue etc), but do not use it for the 404 message on a page-not-found as this is the main content of that page.

<section aria-labelledby="id_of_heading_of_this_section"> ... </section>

Footer

<footer> ... </footer>

Headings

General

All pages should start with an H1.

<h1> Heading that sets context for whole page </h1>

📋 Note: on some pages, this interrupts the visual flow - and the context of the page is clear from other visual cues, e.g. the contact us page. Redesigning the page layout to incorporate a top level heading is beyond scope, so in these cases, provide the H1 for screen readers only.

<h1 class="sr-only"> invisible heading text to provide alternative to visual context of whole page </h1>

Where a heading is inside logic, and is either the H1, or is likely to have subheadings, there should be an 'else' to provide a fallback heading.

Modals

Modals start with an <h2>. This differentiates them from pages which start with an <h1>, and keeps them within the context of that <h1>.

Homepage

index.html begins with an <h1 class="sr-only > identifying this as the home page. It is arguable that it is visually clear it is the home page, and introducing a visible "home page" heading would be a significant change of visual design.

Each homepage-element should be in a section and have an <h2> which provides the aria-labelledby for the section to make it a landmark. Any subheadings are then <h3> and below.

Article Page

📋 This is a compromise that balances improved accessibility against fundamental changes to the layout and display.

Header
Nav
Main
1 Article title
    2 Abstract
    2 Keywords
    2... all other front matter headings.
    
    Article
    2 Article top level headings
        3 Article subheadings etc.

    Article Information Region
    2 Share
    2 Download
    2 ... all other information headings

    Table of Contents Region (using labelledby to table of contents heading)
    2 Table of Contents

Footer

Nested Templates

There are a handful of templates on each theme which are nested within other templates at differing levels, such that the headings within these templates need to be at differing levels too. This is achieved by passing a 'level' variable in the include.

Example Logic

  {% include "elements/journal/issue_top.html" with level="shallow" %}

{% if level == "deep" %}
    <h4>{{ article.title|safe }}</h4>
{% elif level == "shallow" %}
    <h3>{{ article.title|safe }}</h3>
{% else %}
    <h2>{{ article.title|safe }}</h2>
{% endif %}

Clean

• default - [page] h1 -> article listing h2
• shallow - issue.html -> issue top h1 -> issue block h2 -> article listing h3
• deep - homepage h1 -> homepage_elements/issue_block -> issue top h2-> issue block h3-> article listing h4

Material

• default - [page] h1 -> article listing h2
• deep - [page] h1 and h2-> article listing h3
• default - homepage -> issue top h2 -> issue block h3 -> article listing h4
• issuepage - issue.html -> issue top h1 -> issue block h2 -> article listing h3
• default - issues.html h1 -> issue_list h2
• deep - issues.html h1 -> issue_list_by_decade h2 -> issue_list h3

OLH

• default - [page] h1 -> article listing h2
• shallow - [page] h1 and h2-> article listing h3
• default - homepage -> issue top h2 -> issue block h3 -> article listing h4
• issuepage - issue.html -> issue top h1 -> issue block h2 -> article listing h3
• default - issues.html h1 -> issue_list h2
• deep - issues.html h1 -> issue_list_by_decade h2 -> issue_list h3

Note: I initially passed in the numerical value - but as this needed to be passed on to lower templates, this would have required incrementing, or would have meant that sometimes receiving a level=3 meant start with an h3, and others start with h4 which would be confusing to maintain. So instead I have used words to name the path and can then be the same through that whole path. The default does not require any level to be defined, and serves all other cases.

HR - Dividing lines

see <hr>: The Thematic Break on MDN

The <hr > element represents a thematic break between paragraph-level elements: for example, a change of scene in a story, or a shift of topic within a section.

All of our current Front of House <hr /> elements are decorative, and are marked up as <hr aria-hidden="true" />.

Where an <hr /> is semantic, it may be included with aria markup to provide context.

📋 Note: in future designs, we will consider including decorative lines within the css styles rather than in the html.

[StephDriver]

Material Table of Contents

The table of contents for material (article.html and page.html) was fading in and out when you reached it. But as display: none also hides that content from assistive technology, this meant that the landmark was sometimes there, sometimes not - which is unhelpful. Following discussion with @mauromsl, I have changed this to a sticky table of contents which otherwise appears underneath any other side content. There is visually very little difference except it is no longer animated.

[StephDriver]

News Bylines

Previously, news bylines were mostly <h6> but these are bylines not headings. In this update, each theme now uses <p class="byline"> and the byline class for each theme includes css to make it visually identical to previous.

News Tags

Where a heading only contains dynamic content such that it could be empty, I have included logic so that the heading does not show when empty - this particularly relates to tags for news items - where not all themes removed the Tags heading when no tags existed.

[StephDriver]

Notes - Templates to check are still in use / find

• material journal/new_search.html
• material preprints/article.html
• material journal/articles.html
• material elements/accounts/user_form.html
• OLH elements/edit_author.html
• OLH elements/submit/author.html
• OLH elements/submit/file.html
• OLH elements/submit/preprint_file.html

[StephDriver]

plan after discussion with @ajrbyers

This work touches most of the Front of House templates, which are going to have further work on them during the 1.9. It will also need careful consideration of how changes to headings could impact custom styling etc.

This PR is for 1.9 not 1.8. It underpins much of the work in 1.9, and so should be merged before that work begins, but not until after 1.8 is cut.

[joemull]

This represents a huge amount of work--thank you for going through with such attention to detail and systematizing the changes we need to make. Also, the document you wrote explaining the changes was very good, and I hope we can re-use much of that in public developer documentation around heading structure.

[StephDriver]

On investigation, this is going to take a bit longer. When I updated the landmarks, some changed (e.g. aside to section) but the OLH css uses the aside as a selector to identify elements, and so these will no longer work.

So the problems @ajrbyers has identified, are symptomatic of wider problems, which could particularly affect anyone with custom styling.

I need to give this further thought.

[StephDriver]

CSS changes (for migration)

#content aside h3 -> #content .side-info h2
#content aside  -> content .side-info 

[ajrbyers]

OLH

The sidebar H2s are still really large, there is no padding at the top so it feels off as its not in line with the Abstract header.

Conversely the issue archive header now sits too far down the page

Clean and Material seem fine on quick inspection.

[ajrbyers]

Huge work here. Well done. I've added a couple of comments. Can you please take a quick look then we can MERGE.

[StephDriver]

While fixing this I've made the OLH side bar more consistent too

[ajrbyers]