Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update HTML guidance #617

Closed
chris-gds opened this issue Jun 8, 2021 · 6 comments · Fixed by #781
Closed

Update HTML guidance #617

chris-gds opened this issue Jun 8, 2021 · 6 comments · Fixed by #781

Comments

@chris-gds
Copy link

After a short review we noted there are various aspects that are out of date and could go with an update especially around
aria-labelledby= guidance and <section> use.

https://gds-way.cloudapps.digital/manuals/programming-languages/html.html
@timblair
Copy link
Member

@chris-gds Thank for looking. Is there any more detail you can provide on what aspects need updating? Or even better, a PR...?

@chris-gds
Copy link
Author

👋🏼 @timblair - Sure, more details below - initial thoughts centre around section use. This most likely could be tested further across assistive tech.

<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>
  • I don't think this pattern is used commonly within GOV.UK nor is it present in the Design System
  • After testing it might be not needed
  • Or the reverse might be true and many parent containers that contain headings should be updated accordingly as well as the relevant publishing apps.

(I've also requested time to see if I can review / update in lot more detail).

@timblair
Copy link
Member

@chris-gds Did you manage to carve out any more time to to a full review of the HTML guidance?

timblair added a commit that referenced this issue Jul 23, 2021
@timblair
Update last-review date on the HTML style guide
3afc6e6 
#617 notes the need for some parts of this guidance to be reviewed, but this has been raised in community meetings a few times and the position is that it's still broadly correct and there are no significant changes required.

Marking this as reviewed, but reducing the review time to three months.
@timblair timblair mentioned this issue Jul 23, 2021
Merged
@tombye
Copy link
Contributor

tombye commented Aug 6, 2021

I noticed the ARIA in HTML spec' states that the technique of using aria-labelledby to assign an accessible name to <section>s gives them the role of region. Without it, they have no role:

https://w3c.github.io/html-aria/#el-section

Should be a consideration if this is added in this guidance.

@chris-gds chris-gds mentioned this issue Sep 16, 2021
Merged
@tombye
Copy link
Contributor

tombye commented Sep 17, 2021

Myself and @chris-gds had a very long discussion about this outside of here and decided that the current guidance on use of <section> needs to change and that I'll create a PR to that end. When I do, I'll update this comment and close this issue.

timblair added a commit that referenced this issue Nov 16, 2021
@timblair
Bump review date on HTML guidance
a44acd9 
Still awaiting #617, but in general is still OK.
@timblair timblair mentioned this issue Nov 16, 2021
Merged
@tombye
Copy link
Contributor

tombye commented May 25, 2022

I haven't found time to put together a PR for the proposed changes and, after discussing it with others, I intend to consult with the frontend community first. I'll update the status of that here when it happens.

tombye added a commit that referenced this issue Jan 5, 2023
@tombye
Change guidance on sections and landmarks in HTML
c7388a4 
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
@tombye tombye mentioned this issue Jan 5, 2023
Merged
tombye added a commit that referenced this issue Jan 5, 2023
@tombye
Change guidance on sections and landmarks in HTML
ecf6031 
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.
@36degrees 36degrees linked a pull request Mar 22, 2023 that will close this issue
Change guidance on sections and landmarks in HTML #781
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Change guidance on sections and landmarks in HTML alphagov/gds-way
3 participants
@timblair @tombye @chris-gds