Add label and legend headingLevel option

[colinrotherham]

Description

The Nunjucks option isPageHeading sets whether the label or legend also acts as the heading for the page.

This PR adds a new headingLevel Nunjucks option as a replacement for isPageHeading when a custom heading level is necessary, for example when a label or legend acts as the heading for a landmark:

<aside>
  {{ input({
    label: {
      text: 'Search',
-     isPageHeading: true
+     headingLevel: 2
    }
  }) }}

  <!-- // … -->
</aside>

This aligns with support already in NHS.UK React components

See related PR and issue over on GOV.UK Frontend

• Add heading level option to label component called headingLevel alphagov/govuk-frontend#5240
• Confirm accessibility and use cases of using <h2> or deeper headings as label or legend of fields alphagov/govuk-frontend#6471

Checklist

• Tested against our testing policy (Resolution, Browser & Accessibility)
• Follows our coding standards and style guide
• CHANGELOG entry

[edwardhorsford]

I support adding a size option, but am unsure / cautious about headingLevel and wonder if it should be considered separately. I think we'd want to be cautious about the guidance for headingLevel whereas size is probably much more straightforward to document.

We don't expect users to navigate form pages by heading - they typically need to complete the entire form. I'll note GOV.UK does not have such an option, and only added isPageHeading because there's a strict requirement for pages to have an h1, and in 'page per thing', having both a legend and a heading on the page was messy. I don't think we've seen a requirement that other things get marked up as headings. They could do, but it would be good to hear from screen reader users about whether that's valuable vs extra noise and overly semantic.

More generally on the web I don't think forms tend to mark up every legend as a heading, and I worry that if this headingLevel option were introduced, we'd start to see these extra semantics added that may not actually be helpful. If they are, then great - but we should understand first if that's the case.

@selfthinker have you looked at this at all before?

[frankieroberto]

I like the size option! That feels uncontroversial, and a lot easier for people to remember than the right class.

I don't have strong views on headingLevel (needs detailed accessibility research), but if we do add that, then does it make isPageHeading: true redundant?

[colinrotherham]

I don't have strong views on headingLevel (needs detailed accessibility research), but if we do add that, then does it make isPageHeading: true redundant?

It does indeed. The same point was made in alphagov/govuk-frontend#5240 (comment)

Makes sense

[colinrotherham]

I shared an example with the GOV.UK Design System team:

For extra context, some staff facing services can have multiple <form> elements on a page:

• Main content (e.g. comment box) <form> with <h1>
• Aside content (e.g. search box) <form> with <h2>

An update from the GOV.UK team has been passed back in return

They're using custom heading levels in smart answers and (internal) publishing applications

But other than that the heading level options are not widely used

• checkboxes allows a legend to contain a H1 with a toggle option: https://components.publishing.service.gov.uk/component-guide/checkboxes
• fieldset allows a custom size and heading level for the legend but I don't know if we're actually using it anywhere (it's not clearly documented): https://components.publishing.service.gov.uk/component-guide/fieldset#with_heading
• file upload allows a custom size and heading level but this isn't on the public site, used by publishing applications: https://components.publishing.service.gov.uk/component-guide/file_upload#with_label_as_heading
• input allows a custom size and heading level but again don't think this is actually used anywhere: https://components.publishing.service.gov.uk/component-guide/input#with_label_as_heading
• label allows allows a H1 to wrap the label, but only as a toggle option: https://components.publishing.service.gov.uk/component-guide/label#as_page_heading
• radios allows a custom size and heading level, I believe this is used in smart answers: https://components.publishing.service.gov.uk/component-guide/radio#with_custom_heading_size
• textarea has a toggle to allow the label to be wrapped in a H1 but this is only used in publishing: https://components.publishing.service.gov.uk/component-guide/textarea#with_label_as_page_heading

[colinrotherham]

HTML examples shared with the GOV.UK Design System team

We've reached an early agreement that custom heading levels should be limited to:

• Whether the label or legend also acts as the heading for the page
• Whether the label or legend also acts as the heading for the page or landmark

They'd like to discuss this further at their dev catch up sessions, with emphasis on guiding people to only use headingLevel option when strictly necessary (e.g. avoiding duplicate content and ensuring unique landmarks)

Main content with aside

E.g. Search sidebar alongside main content

<main>
  <h1><label for="question">Question</label></h1>
  <input id="question">

  <!-- // … -->
</main>

<aside>
  <h2><label for="search">Search</label></h2>
  <input id="search">

  <label for="sort-by">Sort by</label></h2>
  <select id="sort-by">

  <!-- // … -->
</aside>

Main content with multiple sections

E.g. Staff facing team profile page with editable sections per team member

<main>
  <h1>Your team</h1>

  <!-- // … -->
</main>

<section>
  <h2><label for="person1-question1">What about Colin?</label></h2>
  <input id="person1-question1">

  <label for="person1-question2">Another question</label>
  <input id="person1-question2">

  <!-- // … -->
</section>

<section>
  <h2><label for="person2-question1">What about Romaric?</label></h2>
  <input id="person2-question1">

  <label for="person2-question2">Another question</label>
  <input id="person2-question2">

  <!-- // … -->
</section>

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud