Skip to content

Commit

Permalink
Change guidance on sections and landmarks in HTML
Browse files Browse the repository at this point in the history
An attempt to rewite the guidance on use of
`<section>` tags to solve the problems in
#617.

I think the current guidance on use of `<section>`
tags is unclear because:
- the approach it recommends (using
  `aria-labelledby` to get their accessible name
  from the heading) creates a region landmark
  but the examples seem to show content that
  wouldn't benefit from being in one
- from looking through a lot of GDS repos, I
  couldn't find any code following this pattern
- it seems to clash with the current HTML5
  spec', which includes similar content
  examples but doesn't use of `aria-labelledby` to
  set an accessible name

The HTML5 spec' on `<section>`:

https://html.spec.whatwg.org/multipage/sections.html#the-section-element).

By 'region landmark', I mean an element with
`role="region"`.

I think a major cause of this confusion comes from
the current guidance having been written when the
HTML5 spec' still said that `<section>`s should be
used with `<h1>`s to create the document outline,
something never implemented in any browser:

https://www.tpgi.com/html5-document-outline/)

This has since been changed:

whatwg/html#7829

The spec' now seems to advocate using `<section>`s
to identify the scope of a heading. This arguably
makes the HTML easier to read but doesn't add any
new semantics so I'm wary of including guidance
for it here.

These changes instead intend to clear up the
existing guidance on use of `<section>` tags by
making it clear that this approach creates region
landmarks and that using them in other ways
(without assigning an accessible name) removes any
semantics they add.

Worth noting that these changes gratefully borrow
from
https://www.scottohara.me/blog/2018/03/03/landmarks.html

Final note: I expect a bit of discussion on this
pull request so intend to update the date of the
page these changes are in if and when they are
agreed to be the correct approach to the issue.
  • Loading branch information
tombye committed Jan 5, 2023
1 parent ac4c99b commit ecf6031
Showing 1 changed file with 28 additions and 28 deletions.
56 changes: 28 additions & 28 deletions source/manuals/programming-languages/html.html.md.erb
Original file line number Diff line number Diff line change
Expand Up @@ -46,40 +46,15 @@ users skip past your general site navigation and get straight to the content.
You can use the [skip link component from the GOV.UK Design System](https://design-system.service.gov.uk/components/skip-link/)
for this.

### Sectioned content

Use the `<section>` tag to represent standalone, thematic groupings of content
where a more specific semantic element would not be appropriate.

Examples of sections would be chapters, or various tabbed pages in a tabbed dialog box,
or a home page split into sections such as introduction, news items and contact information.

You should add an `aria-labelledby` attribute linking to the id of the heading
that identifies that section.

Example:

```html
<section aria-labelledby="introduction">
<h2 id="introduction">Introduction</h2>
<p>People have been catching fish for food since before recorded history...</p>
</section>

<section aria-labelledby="equipment">
<h2 id="equipment">Equipment</h2>
<p>The first thing you'll need is a fishing rod or pole that you find comfortable
and is strong enough for the kind of fish you're expecting to try to land...</p>
</section>
```

### Navigational elements

Use `<nav role="navigation">` 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.

As with `<section>`, it is advisable to use `aria-labelledby` to label your `<nav>`.
This helps to distinguish different `<nav>` blocks in the page.
If you use more than one `<nav>` block in your page it is advisable to use
`aria-labelledby` to label each one, to make clear the type of navigation
contained by each.

The GOV.UK blog has [more information regarding the use of the `<nav>` tag](https://insidegovuk.blog.gov.uk/2013/07/03/rethinking-navigation/).

Expand All @@ -94,6 +69,31 @@ Examples include author information, related links and related content.

`<footer role="contentinfo">` should be used for the footer of the site.

### Region landmarks

Region landmarks can be used when you need to create a new type of landmark.

You can create region landmarks by using the `<section>` tag with an
`aria-labelledby` attribute linking to the id of the heading that identifies
it.

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
- none of the existing HTML5 tags or ARIA landmark roles used for document
structure would correctly identify the grouping

The use of region landmarks should be limited, as too many landmarks can dilute
their usefulness in quickly navigating to important areas of a page. If you
find there are many custom landmarks then the page’s structure should be
re-examined.

Note that use of `aria-labelledby` to assign an [accessible
name](https://www.tpgi.com/what-is-an-accessible-name/) is required for region
landmarks. Without an accessible name `<section>` tags are semantically the
same as `<div>` tags.

## Individual element guidance

### Headings
Expand Down

0 comments on commit ecf6031

Please sign in to comment.