Make it clear that the heading class does not relate to the heading level

[edwardhorsford]

In #1201 the default heading size was changed to govuk-heading-l - however the typography page still gives the impression that govuk-heading-xl should be the default.

It says in words that the heading size should depend on the content - but all the examples continue to use xl.

Additionally the primary example showing the different heading classes also changes the heading level with each class. This gives the very strong impression that govuk-heading-xl is for h1, govuk-heading-l is for h2, etc.

I've spoken with several teams across gov (both new starters and people who have worked with the design system for some time), and universally every one took the main example (screenshot above) as indicating a correlation between class and heading level - which is not at all intended. This pr removes that association by making them all h1.

The updated example is similar to the Font size example as only one variable is changing, not two.

Updated:

The guidance also indicated you should pick one heading size and use the same throughout all pages of the service - which I don’t think is correct. Most of the time teams will want govuk-heading-l - but for some pages they may want govuk-heading-xl. Teams should vary it based on the page, not the service as a whole.

[govuk-design-system-ci]

You can preview this change here:

Built without sensitive environment variables with commit 31934c4

https://deploy-preview-1452--govuk-design-system-preview.netlify.app

[christopherthomasdesign]

Hi @edwardhorsford, thanks for the contribution.

We agree that the current examples might give the impression that govuk-heading-xl is for h1, govuk-heading-l is for h2 etc. Perhaps we could explain this better – any thoughts?

My fear with this proposed solution is that users might copy the headings, either without looking closely at the HTML, or without knowledge of HTML, and end up with prototypes/services with multiple h1s all over the place. That assumption is untested, but if true it seems a bigger risk to end users than teams styling their h1s with govuk-heading-xl.

On the point of picking one h1 size and using it on all pages of the service – I agree it's probably more nuanced than this. I think what you want to avoid is heading sizes changing on different pages for no reason – they should reflect the hierarchy or structure of the service?

Let us know what you think. If we can't easily think of a workable solution we could convert this to an issue for the team to work on in more depth at a later date.

[edwardhorsford]

@christopherthomasdesign I agree about it being a bit weird to have multiple h1s. But right now every person I've spoken to without fail reads that example as being explicit that xl is for h1, and l is for h2.

I don't think words can solve this - people visit the page to look up the class, and go first to the example, picking the one next to the heading level they're using.

An alternate suggestion would be to remove the snippet entirely:

I think if you do want to include a snippet - you could break up the headings section in to sub-sections - Headings for shorter pages which includes a snippet with govuk-heading-l and Headings for longer pages which has snippets for govuk-heading-xl - then later show the other available classes.

On the point of picking one h1 size and using it on all pages of the service – I agree it's probably more nuanced than this. I think what you want to avoid is heading sizes changing on different pages for no reason – they should reflect the hierarchy or structure of the service?

I hope the guidance makes clear you shouldn't change for no reason - but picking one heading level only across the service doesn't feel right - it should be based on the context of the page and the service.

[christopherthomasdesign]

Sorry for the delay getting back to you @edwardhorsford

I'm not sure hiding the snippet solves the problem – people still need to copy the code and are likely to copy whatever you put there.

I'm interested in the second suggestion you make. It could add a bit of nuance with visual examples to back it up, rather than just adding more guidance. Would you mind demonstrating how that might look? Either as a mock up or by updating the PR?

We recently made some small changes to add more information on styling table captions which might be relevant. Though that's different in that all those table captions use the same markup, just different styling...

Alternatively, I think this could be converted to an issue. There are other issues such as #1413 that concern how to structure pages, and the relationship between HTML structure and visual hierarchy. We might consider looking at them together to solve them in a more holistic way across the Design System site.

[morganfeeney]

Are pages for gov.uk usually designed and built in an ad-hoc manner? For instance, are there pre-defined templates that will include typographic hierarchy?

I can see how the function to copy the snippets is contributing to, through it's convenience, the issue described here. It sounds like an educational piece of work potentially, conveying the nuances of typography to the implementors of the design system, maybe some workshops? In the long-run, could be a matter of documentation that is easy to find.

[christopherthomasdesign]

Hey @edwardhorsford – have just suggested a couple of small changes:

• Removed the xl example from the default headings example
• Added a new example demonstrating what to do for longer form content
• Tweaked the copy (will get this reviewed by a content designer in any case)

It's a bit more repetitive but I think it gets the point across clearly without having any misleading markup or over-relying on guidance.

On looking at it again, I thought it should be fine to have multiple h1s in the examples with captions. We don't say it explicitly but I think they're really intended for page headings. I have only ever seen them used for page headings.

Let me know what you think.

[edwardhorsford]

@christopherthomasdesign this all seems great 👍

[calvin-lau-sig7]

Looking good! Made a couple of suggestions to make things a bit clearer.

[calvin-lau-sig7]

I fixed some bad backticks (that were actually apostrophes).

[edwardhorsford]

Thanks all!