In v6.0.0 we only style HTML heading levels 1, 2 and 3. Heading levels 4, 5 and 6 are rendered with default browser styles, typically Times New Roman. You also can't format a heading as 4, 5 or 6 in the Umbraco rich text editor. For upcoming work we need to support deeper nesting of headings.
"For a question page, or pages with long headings, follow the usual hierarchy of heading levels and styles associated with them. For example, govuk-heading-l for an <h1>, followed by govuk-heading-m for an <h2> and so on."
This is what we support already. It goes on to say:
"In rare cases, you might want to alter how you use the headings hierarchy to achieve a better visual balance.
...
If your page has lots of long form content, start with govuk-heading-xl for an <h1>, govuk-heading-l for an <h2>, and so on."
In v6.0.0 we don't support any of this flexibility. Headings always start with govuk-heading-l.
Constraints and considerations
GOV.UK Frontend has a new typography scale, but it's behind a flag until GOV.UK Frontend 6.0.0 with a warning that "We may release significant changes to the scale in releases between now and GOV.UK Frontend 6.0.0". Due to this warning I'm sticking with the existing typography scale for pure GOV.UK styles.
TPR doesn't have an agreed standard to implement. The TPR UI Kit defines heading styles and our existing support for h1, h2 and h3 is somewhat based on this. However the status of this specification is 'Draft', and for h4 and h5 it specifies some use of 14px text which research by the GOV.UK Frontend team has found to be an accessibility issue, and h6 is not defined at all.
In the absence of an agreed TPR standard, keep the styles we have now for h1, h2 and h3 to make this a non-breaking change, and otherwise follow the GOV.UK Design System.
Accept that we may need to revisit this for TPR styles, but know that with the ability to apply all heading levels and use classes at every level we can adjust them however we choose to at a later date. Heading levels 4, 5 and 6 currently look the same but they are semantically different and correct, and we can adjust the appearance later if desired.
Implementation
Introduce the new concept of a 'Page setting' and create a new page setting to choose the starting point for the heading scale. Create a composition which can be added to any document type, allowing the setting to be made available on any page. The setting defaults to the existing starting point of govuk-heading-l if nothing is selected, but allows selection of govuk-heading-xl as an alternative.
Adding the setting to pages rather than a separate 'Settings' node means we can use Fallback.ToAncestors to set the desired starting size for headings at the root of a site and have all descendant pages inherit that setting, or override it if they need to. In either case the setting is read efficiently and automatically from the Umbraco cache.
Adding the page setting to a tab rather than a group provides a neater separation of content and metadata in the backoffice UI (see screenshot above), now that we have metadata at a page level for the first time in this package. Sticking with groups would mean content and metadata would become intermingled on the same page.
Add a new method GovUkTypography.HeadingClasses() to return appropriate classes for each heading level based on a starting class. This includes classes for other elements used as page headings when using the 'one thing per page' pattern, ie form labels and legends. Non-Umbraco apps can call this to determine which classes they need, and GovUkTypography.Apply() will respect heading classes if provided in TypographyOptions.
GovUkTypography.Apply() updated to apply classes to h4, h5 and h6.
Updated Umbraco components to use the new page setting to get the class with which to start the heading scale. A new GovUkPageSetting static class makes it easy to get this value from the current content item. This setting is fed into GovUkTypography.HeadingClasses() to find the classes to apply, and the components use those classes.
The caption component also changes size along with the page heading, which reflects how it is used on the GOV.UK Design System website. Spacing between the two is adjusted slightly as we use a different font to GOV.UK Frontend.
Fixed a bug in the backoffice preview of the 'Page heading' component GovUkPageHeading.html, where if you use the 'Text' property to override the heading text it was still displaying the page name. This was confusing as totally different text would actually appear on the page.
Added new heading levels and sizes to the rich text editor style menu. Adjusted font-sizes for the backoffice only as they were too big in this menu.
Limitations
Any text you enter in an Umbraco rich text editor is formatted automatically with GOV.UK Frontend classes. This happens automatically for any rich text value using a PropertyValueConverter, so consuming apps cannot forget. However a PropertyValueConverter has no access to the current page, so it can't read and apply the page setting. Instead it always applies the default setting starting with govuk-heading-l.
However, this only affects headings pasted into the rich text editor with no class or the wrong class, and these can easily be corrected by selecting the correct class from the style dropdown. If you are formatting text from scratch in the editor, the user applies the class when they select the heading level.
Documentation
Documented when and how to use different types of setting including the new 'Page setting' concept, for devs contributing to this repo
Documented how to use the new page setting and rich text editor options to control heading levels.
Added new constants for task list dictionary entries, when documenting this feature highlighted that they were missing.
Updated example apps
Both example apps have two new pages demonstrating the new typography scale starting with both govuk-heading-l and govuk-heading-xl.
The Umbraco app has the page setting applied to every document type, so that users can experiment with the effect. The new page demonstrating larger headings uses the page setting to change the size of the headings.
In the Umbraco app all page document types move their properties from a group to a tab, to align with the fact that the new page setting uses a tab.
Re-saving all pages in the Umbraco app has updated the way uSync writes its data, as uSync has been upgraded since the last time they were all saved.
Heading styles starting with govuk-heading-l (unchanged)
Heading styles starting with govuk-heading-xl (new)
What problem does this solve?
In v6.0.0 we only style HTML heading levels 1, 2 and 3. Heading levels 4, 5 and 6 are rendered with default browser styles, typically Times New Roman. You also can't format a heading as 4, 5 or 6 in the Umbraco rich text editor. For upcoming work we need to support deeper nesting of headings.
The GOV.UK Design System page on headings says:
This is what we support already. It goes on to say:
In v6.0.0 we don't support any of this flexibility. Headings always start with
govuk-heading-l.Constraints and considerations
Proposed approach
In the absence of an agreed TPR standard, keep the styles we have now for h1, h2 and h3 to make this a non-breaking change, and otherwise follow the GOV.UK Design System.
Accept that we may need to revisit this for TPR styles, but know that with the ability to apply all heading levels and use classes at every level we can adjust them however we choose to at a later date. Heading levels 4, 5 and 6 currently look the same but they are semantically different and correct, and we can adjust the appearance later if desired.
Implementation
Introduce the new concept of a 'Page setting' and create a new page setting to choose the starting point for the heading scale. Create a composition which can be added to any document type, allowing the setting to be made available on any page. The setting defaults to the existing starting point of
govuk-heading-lif nothing is selected, but allows selection ofgovuk-heading-xlas an alternative.Adding the setting to pages rather than a separate 'Settings' node means we can use
Fallback.ToAncestorsto set the desired starting size for headings at the root of a site and have all descendant pages inherit that setting, or override it if they need to. In either case the setting is read efficiently and automatically from the Umbraco cache.Adding the page setting to a tab rather than a group provides a neater separation of content and metadata in the backoffice UI (see screenshot above), now that we have metadata at a page level for the first time in this package. Sticking with groups would mean content and metadata would become intermingled on the same page.
Add a new method
GovUkTypography.HeadingClasses()to return appropriate classes for each heading level based on a starting class. This includes classes for other elements used as page headings when using the 'one thing per page' pattern, ie form labels and legends. Non-Umbraco apps can call this to determine which classes they need, andGovUkTypography.Apply()will respect heading classes if provided inTypographyOptions.GovUkTypography.Apply()updated to apply classes to h4, h5 and h6.Updated Umbraco components to use the new page setting to get the class with which to start the heading scale. A new
GovUkPageSettingstatic class makes it easy to get this value from the current content item. This setting is fed intoGovUkTypography.HeadingClasses()to find the classes to apply, and the components use those classes.The caption component also changes size along with the page heading, which reflects how it is used on the GOV.UK Design System website. Spacing between the two is adjusted slightly as we use a different font to GOV.UK Frontend.
Fixed a bug in the backoffice preview of the 'Page heading' component
GovUkPageHeading.html, where if you use the 'Text' property to override the heading text it was still displaying the page name. This was confusing as totally different text would actually appear on the page.Added new heading levels and sizes to the rich text editor style menu. Adjusted font-sizes for the backoffice only as they were too big in this menu.
Limitations
Any text you enter in an Umbraco rich text editor is formatted automatically with GOV.UK Frontend classes. This happens automatically for any rich text value using a
PropertyValueConverter, so consuming apps cannot forget. However aPropertyValueConverterhas no access to the current page, so it can't read and apply the page setting. Instead it always applies the default setting starting withgovuk-heading-l.However, this only affects headings pasted into the rich text editor with no class or the wrong class, and these can easily be corrected by selecting the correct class from the style dropdown. If you are formatting text from scratch in the editor, the user applies the class when they select the heading level.
Documentation
Updated example apps
govuk-heading-landgovuk-heading-xl.Heading styles starting with
govuk-heading-l(unchanged)Heading styles starting with
govuk-heading-xl(new)Work item reference
AB#204479