Related Page cards raise Wagtail accessibility error

[rosslaird]

When a user selects to show Related Pages, each card in the resulting card block has the following header:

<h5 class="card-title">

Unless the main content of the page has h4 as the final header tag, this raises an Accessibility error in Wagtail:

Incorrect heading hierarchy
Avoid skipping levels

The CRX cards could be excluded from the accessibility check, using Wagtail's accessibility settings; however, the error would still be there, and the page would not be fully accessible.

Another option would be to change the card header tags (to <span>, for example), and style with CSS. (Using a <p> element would not solve the issue, as it would raise yet another accessibility error: p-as-heading).

Using <span> with role=heading would be one method, though this is not recommended from an accessibility point of view:

The best way to use this role is to not use it at all, and instead use the native heading tags h1 through h6.

So, I'm not sure what would be best here.

[vsalvino]

Specifically for related pages, that heading is always an H2, so we could in theory use an H3. BUT - the miniviews are extremely modular and are often used throughout the site (page preview blocks, latest pages block, etc.). So changing them to H3's would potentially just shift the issue elsewhere.

I'm wondering if H3 might be a better default, and then if we can adjust the template to be more dynamic, i.e. set the heading level with a variable.

[vsalvino]

Good timing on your part, I just happened to be working on the affected components in #659 .

I switched them to h3 by default, and added an h variable to change the heading level in the template. With default CRX templates, this fixes most of the issues.