Problem/Motivation

A Canvas landing page built on this theme has no h1, so axe-core reports page-has-heading-one. Verified on a running Varbase 11 site: zero h1 elements on the front page.

A site template cannot solve this on its own. Placing a heading at level: 1 in the Canvas tree does produce an h1, but it renders visible and duplicates the hero headline, and there is no way to hide it from the content side. Checked on 5.0.x:

  • The heading atom exposes nine props, all closed enums. There is no class or attributes prop, so visually-hidden cannot be passed to it.
  • A Canvas component tree has no per-placement class or attributes key.
  • container has free-form container_utility_classes but no slot, so it cannot wrap a heading. group has a slot but only closed enums.
  • Neither hero component can supply the h1: a slider can hold several slides, so a per-slide h1 would emit several, and a card is never a page's main heading. Both were tried and reverted in #3621197.

Steps to reproduce

  1. Install a site template built on this theme and open the front page.
  2. Evaluate document.querySelectorAll('h1').length. It is 0.
  3. Add a heading at level: 1 in the Canvas tree. It renders visible, duplicating the hero headline, because nothing can hide it.

Proposed resolution

A CSS rule in the theme, and nothing else. The front page already carries Drupal core's own body class, verified on a running Canvas front page:

<body class="canvas-page path-frontpage">

So the rule keys off body.path-frontpage and visually hides the front page's h1. A site template can then place a heading at level: 1 in its Canvas tree and get a correct document outline with no visible design change.

No PHP. No hook, no preprocess function, no new component prop. The change is one rule in the theme's SCSS plus the matching lines in the committed compiled CSS.

The rule must use the clip technique that Bootstrap's .visually-hidden uses, keeping the element in the accessibility tree. display: none and visibility: hidden remove it from that tree and would leave the axe violation in place while appearing to fix it.

For reference, the theme already expresses this same intent for the page-title block in vartheme_bs5_preprocess_page_title(), which adds visually-hidden to the title on the front page. That never fires on a Canvas landing page, because the site template recipes disable the page-title block there. It is cited here only to show that a screen-reader-only front page heading is existing theme behaviour, not a new policy; it is not being changed.

Verified with axe-core 4.10.2 on a running Varbase 11 site: with the footer contrast fix from #3621197 applied and a clipped h1 present on the front page, the scan reports zero violations across WCAG 2.0 and 2.1 A and AA plus best practice, 43 passes. The injected heading computed as display: block, visibility: visible, clip: rect(0px, 0px, 0px, 0px), rendering at 1x1 pixel and remaining in the accessibility tree.

The matching content change, adding a heading with the site name to the Varbase Starter home page, is #3621200. The two belong together: this issue makes the heading invisible, that one supplies it.

Remaining tasks

  • ✅ File an issue
  • ❌ Addition/Change/Update/Fix
  • ❌ Testing to ensure no regression
  • ❌ Reviewed by a human
  • ❌ Code review by maintainers
  • ❌ Release

User interface changes

  • An h1 on the front page is no longer visible. It remains available to screen readers and to the document outline.

API changes

  • None.

Data model changes

  • None.

Release notes snippet

  • Visually hide the front page h1, so a Canvas landing page can carry a top-level heading for screen readers and accessibility checks without changing the visible design.

Issue fork vartheme_bs5-3621201

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

About issue forks

Comments

rajab natshah created an issue. See original summary.

rajab natshah’s picture

rajab natshah
he/him
commented
Issue summary: View changes

rajab natshah opened merge request !211

  • rajab natshah committed 87dc2af5 on 5.0.x 
    fix: #3621201 Visually hide the front page h1 so a Canvas landing page...
rajab natshah’s picture

rajab natshah
he/him
commented
Issue summary: View changes
rajab natshah’s picture

rajab natshah
he/him
commented
Status: Active » Fixed
Issue tags: +vartheme_bs5-5.0.1

✅ Released vartheme_bs5-5.0.1

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.