fix: #3621200 Add a site name level 1 heading to the Varbase Starter home Canvas page

Rajab Natshahrequested to merge
issue/varbase_starter-3621200:3621200-accessibility-the-home into 1.0.x

Closes #3621200.

The Varbase Starter home page rendered zero h1 elements, so axe reported page-has-heading-one (moderate). A Canvas landing page renders no page-title block, so nothing supplies an h1.

The change

content/canvas_page/01-home.yml gains a new sdc.vartheme_bs5.heading component at level: 1, placed first in the page's component tree so the document outline starts with the page heading. It sits at the top level of the tree, beside the sections, which is where the pages already place standalone headings, spacers and dividers.

Every existing heading keeps the level it had. The hero slides' title_tag, the theme and the component manifests are untouched.

The heading text is a literal

The text is Varbase Starter, matching the recipe name. It is a literal and will not follow a site rename. None of Canvas's prop sources reads configuration, so a heading's text cannot be bound to system.site.name, and the recipe ships no site name of its own.

This depends on the theme rule in the linked issue

On its own, this change makes a visible "Varbase Starter" heading appear at the top of the home page. It is meant to be invisible, and what makes it invisible is the front-page heading rule added in https://www.drupal.org/project/vartheme_bs5/issues/3621201, which hides it with the clip technique so it stays in the accessibility tree. Merging this without that theme change would put visible text on the home page that the design does not have.

Automated testing coverage

tests/features/15-quality/15-02-accessibility.feature already audited the home page, but only through the impact gated steps no critical accessibility violations and no serious accessibility violations. page-has-heading-one is a moderate rule, so neither gate ever looked at it. The 15-quality job ran green on every 1.0.x pipeline with the home page carrying zero h1 elements (for example job 12007563 in pipeline 949537: 23 scenarios, 92 steps, all passed).

Three home page scenarios are added, in the file's existing style and tag line:

  • Then the page should not violate the accessibility rule "page-has-heading-one" - this is the one that fails without the heading added by this MR and passes with it.
  • Then the page should have exactly one h1 - page-has-heading-one only requires that at least one exists, so this pins the count.
  • Then the page should not violate the accessibility rule "color-contrast".

cucumber-js --dry-run on the file resolves 13 scenarios and 52 steps with no undefined or ambiguous step.

What the colour contrast scenario does not cover

Being honest about its reach: the color-contrast scenario gates the real text on the home page, but it would not have caught the footer social icon contrast defect fixed in https://www.drupal.org/project/vartheme_bs5/issues/3621197.

Those links carry font-size: 0 and letter-spacing: -9999px, so the accessible text ("Linkedin", "Facebook", ...) is not rendered, and the visible glyph is a Bootstrap Icons ::before pseudo-element. axe-core does not evaluate pseudo-element content for colour contrast, so the rule never applies to those nodes. Verified against a running Varbase 11 site on axe-core 4.13 by re-injecting the old #0d6efd colour: axe reported zero color-contrast violations either way, and the four social links appeared in neither violations nor incomplete.

Genuinely covering that regression needs a computed style pin rather than an axe rule, for example a registered footer social link selector plus:

Then the "footer social link" element should contain "color: rgb(10, 88, 202)"

That is not added here: it hardcodes a value the theme owns, so it is a maintainer call whether the recipe suite should pin it.

Scope

The blog Canvas page has the same gap. It is deliberately out of scope here and is handled separately.

This change was created with the help of AI, and reviewed by a human. Per the Drupal AI policy: https://www.drupal.org/about/core/policies/core-change-policies/drupal-ai-policy

Checkpoints

  • File an issue about this project
  • Addition/Change/Update/Fix to this project
  • Testing to ensure no regression
  • Automated unit/functional testing coverage
  • Developer Documentation support on feature change/addition
  • User Guide Documentation support on feature change/addition
  • UX/UI designer responsibilities
  • Accessibility and Readability
  • Reviewed by a human
  • Code review by maintainers
  • Full testing and approval
  • Credit contributors
  • Review with the product owner
  • Update Release Notes
  • Release
Edited by Rajab Natshah

Merge request reports