Hmrc Heading Component to fit inside Gov Uk components

[DanielConnelly]

Related component

HmrcPageHeading being used in combination with Fieldsets or Radios

Context

We have had an accessibility issue raised around nested h2 inside label

Alternatives

we are using a workaround suggested by this team, however, it requires a re-writing component.

Additional information (if applicable)

As this library is meant to be used in combination with the govuk components ideally everything should be able to compose together.

[oscarduignan]

Hi @DanielConnelly thanks for this, would you be able to share the report with us at platform-ui@digital.hmrc.gov.uk

It sounds like there might be some misunderstanding about when you need to include heading elements within legends. When you are following the one question per page pattern, and there is no heading on the page other than the legend, then it's recommended to include the h1 the page needs within the heading (which the govuk components have the isPageHeading=true option to control, and if you need to include a caption above the heading - following the hmrc page heading pattern - you can use the helpers in play-frontend-hmrc). However, if you already have a h1 on the page, you would not need to include an additional h2 within the legend, the legend already provides the semantic meaning the browser or assistive technology needs to understand the structure of the page. Here's an example of that from the design system.

Then we are currently working with the design team and DIAS to identify different places that the hmrc page heading pattern can be used to try and simplify the API and improve the guidance we can give to teams (where the HmrcPageHeading component is one implementation, and the helpers linked above are another.) If you want to follow or contribute to the discovery work for that, then it's being done under jira PLATUI-1492, though still in the really early stages at the moment.

[DanielConnelly]

@oscarduignan the failure is explained on https://jira.tools.tax.service.gov.uk/browse/RORO-2943 - can you let me know if you can see it.

[oscarduignan]

Hi @DanielConnelly I managed to catch up with DIAS about https://github.com/hmrc/accessibility-audits-external/issues/3053#issuecomment-1034794596 and it seems like the main point here is that the HmrcPageHeading component is not intended to be used within a label or legend. My current understanding is that it's only intended to be used if you need a heading with a caption that is separate to any form elements on the page. Which you might need because you're asking multiple questions on the page or because the page has no form fields. And if you didn't need a caption, you could also use a h1 by itself without needing to use the HmrcPageHeading component.

Then if you do need a legend to be a heading, for example because you're following the one question per page pattern, then you can use the isPageHeading = true option if you don't need to include a section caption. Or, if you need to include a section caption then for now we advise you use the HmrcPageHeadingLabel or HmrcPageHeadingLegend helpers. If you have imported the implicits we provide then you'll find for the GovukRadios component there's a couple of helpers to make using these easier / more discoverable https://github.com/hmrc/play-frontend-hmrc/blob/main/src/test/scala/uk/gov/hmrc/govukfrontend/views/implicits/RichRadiosSpec.scala#L146-L158

Going to close this ticket for now, but grab me if you have any follow up questions around this or reopen the ticket 👍