HTML coding style
Browser support
The GOV.UK Service Manual lists the minimum browsers that GOV.UK services are required to support.
Your project may need to support additional browsers. You should use analytics to see which browsers are commonly used by your users. You may also need to support additional browsers based on how your project is used - for example, GOV.UK Frontend’s browser policy is designed to support a wide range of services.
You will need to test your code in the browsers your project supports.
Your page should work with only HTML, before adding any CSS or JavaScript. Read building a robust frontend using progressive enhancement.
Document structure
Use HTML5 to structure your page semantically.
Header
<header> should be used to contain your home link, branding, search, and any global navigation you may have.
Main content
<main> should be used to identify the main content of your page.
A “Skip to main content” link should be added to help screen reader and keyboard users bypass your general site navigation and get straight to the content. You can use the skip link component from the GOV.UK Design System for this.
Navigational elements
Use <nav> to wrap groups of links that are not already in another context (for example, <footer>). Common examples of navigation sections are menus, tables of contents, and indexes.
If you use more than one <nav> block in your page it is advisable to give each one an accessible name using aria-labelledby or aria-label, to make clear the type of navigation contained by each.
The GOV.UK blog has more information regarding the use of the <nav>tag.
Aside
<aside> should be used for content related to the primary content of the webpage, but which does not constitute the primary content of the page.
Examples include related links, related content and author information.
Footer
<footer> should be used for the footer of the site.
Region landmarks
Use region landmarks to surface important areas of a page where it’s not appropriate to use any of the other types of landmarks.
You can create region landmarks by using the <section> tag. The <section> must have an accessible name, which can be provided using the aria-labelledby or aria-label attributes. A <section> tag without an accessible name is semantically the same as a <div> tag.
Region landmarks should only be used where users will likely want to be able to navigate to the grouping easily and to have it listed in a summary of the page.
You can already use headings and the other landmarks to identify sections of the page. Region landmarks should be used only when those are proven not to work well enough and doing so saves users more effort than it adds.
Supporting older browsers with ARIA landmark roles
The semantic HTML elements mentioned above have implicit ARIA roles. Some older browsers, such as Internet Explorer, do not support these implicit roles, or support them inconsistently. If this is the case for one of your supported browsers, you should make the roles explicit, for example:
<header role="banner"></header>
<nav role="navigation"></nav>
<main role="main"></main>
<aside role="complementary"></aside>
<section role="region" aria-labelledby="section-heading"></section>
<footer role="contentinfo"></footer>
Check HTML5 Accessibility to determine whether you need to do this. Léonie Watson explains how to use ARIA landmark roles to deliver the best experience for screen reader users.
Individual element guidance
Headings
Headings should be in order - for example <h1> then <h2>, but not <h1> then <h3>.
There should only be one <h1> element in a page.
Text emphasis
Italics should be avoided. Bold can be used sparingly, but can make large blocks of text difficult to read. There is guidance on how to use bold and alternatives to italics in the GOV.UK content style guide.
Semantically, words voiced with emphasis can be marked up with <em>, whereas words conveying a sense or urgency or warning should be marked up with <strong>. Currently none of the major screen readers change their tone of voice when reading emphasised text, but in theory they could.
Browsers will render em in italics and strong in bold by default, so you may need to override em to not use italics.
As a rule, avoid using <i> or <b>, which are only useful in rare cases. It is usually better to use the font-style and font-weight CSS properties.
Images
Follow the guidance in the Design System’s Images section.
Buttons vs links
Links should be used for navigating to another page. Buttons should be used for submitting forms or interactions within the page (for example, expanding an element). Empty links (<a href="#">) should be avoided.
Links should not open new tabs or windows by default, but if users choose to do so (through keyboard shortcuts or right-click context menu) then we should respect their choice.
Visually hidden elements
Sometimes it can be helpful to provide additional content for screen reader users that might not be needed for sighted users.
Do not use display: none on this text, as this will hide the text from screen readers.
Instead, use CSS which ensures the text gets ‘conceptually’ rendered, even if the result is not visible on the screen. You can use the Sass mixins from govuk-frontend or the classes govuk-visually-hidden and govuk-visually-hidden-focusable.
Visually hidden text is often a sign that something can be simplified or made visible to benefit sighted users too, so should be used sparingly.
Formatting
There is currently no uniform GDS policy on HTML code formatting. This covers things like:
- whether to use single or double quotes in attributes
- whether to omit values from attributes that do not need them
- whether to add trailing slashes to void elements.
However, the approach you adopt should be consistent throughout your codebase. You should consider using a formatter like Prettier to enforce consistency.