projectblacklight
Accessibility: Review existing heading issues and propose a plan for updating heading structure
Review the following tickets and propose a plan to update the heading structure:
- https://github.com/projectblacklight/spotlight/issues/3525
- https://github.com/projectblacklight/spotlight/issues/3434
- https://github.com/projectblacklight/spotlight/issues/3473
Proposal
- Leave the exhibit title in the masthead as h1.
- Change the page title h1 to h2.
- Visually style the page title h2 to look more like an h1 (i.e., keep the slightly larger font size).
- If a user has unchecked the "Show title" box for that page, visually-hide the title but still render the title h2 in the DOM.
- If a page doesn't have any title, visually-hide but render a generic "Main content" title h2 in the DOM.
- Leave the within-page headings (h2) and widget headings (h3) as they are.
Benefits and limitations
Here is a current heading structure that frequently appears in Spotlight:
h1 (exhibit title)
h1 (page title, optional)
h3 (widget header)
h3 (widget header)
This structure violates two accessibility principles: there should only be one h1 per page, and the heading level order shouldn't skip from h1 to h3. These violations cause exhibit pages to fail automatic accessibility checks.
The proposal is to change the page title h1 to h2, and to make it always visible to screen readers, even if visually-hidden.
Benefits: this addresses the two accessibility violations, allowing (possibly many) exhibit pages to pass automatic accessibility checks without manual remediation from exhibit creators.
Limitations: for some exhibit pages, this approach will introduce a new accessibility issue. Because the page title is now an h2, it is on the same heading level as the page heading widgets. With the proposal implemented, the following heading structure will appear:
h1 (exhibit title)
h2 (page title, styled to look like h1)
h2 (heading widget)
h3 (widget header)
h2 (heading widget)
h3 (widget header)
Strictly-speaking, this does not violate heading level order, but it does not reflect the page's visual organization, even as it passes automatic checkers.
Summary
The proposal moves Spotlight toward a less-violating heading structure, with minimal code intervention and manual remediation. It does not fix all of Spotlight's heading issues, which are too complex to address in a short sprint. A future scheduled work cycle should more comprehensively revisit the application's default heading structure, including:
- Should the exhibit title be an h1? If not, should every page have an h1 page title?
- Do exhibit creators need the ability to specify heading levels (h1-h6) for the heading widget and widget heading?
new ticket for the sidebar feature page header issue: https://github.com/projectblacklight/spotlight/issues/3582
