Skip to content

Commit

Permalink
Change guidance on sections and landmarks in HTML
Browse files Browse the repository at this point in the history
The current guidance on use of `<section>` tags is
unclear because:
- the approach it recommends (using
  `aria-labelledby` to use the heading as their
  accessible name) creates a region landmark but
  the examples seem to show content that shouldn't
  be split off into 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
  now says you should use `<section>` tags to wrap
  groupings of content marked by a heading without
  use of `aria-labelledby` to make the heading the
  `<section>`s accessible name

See 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"`.

The original opinion that this guidance is unclear
was stated in this issue:

#617

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

These changes intend to ensure guidance around use
of `<section>` tags is clearer by only referencing
them in the bit on region landmarks and making it
clear 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
  • Loading branch information
tombye committed Jan 5, 2023
1 parent ac4c99b commit c7388a4
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 c7388a4

Please sign in to comment.