From 7287ee0f637076c9e4d735f4c754f42473149b50 Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Fri, 17 Oct 2025 14:52:30 +1300 Subject: [PATCH 01/19] Add Steve to authors --- hell/_data/authors.js | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/hell/_data/authors.js b/hell/_data/authors.js index 2586ddff..eba2dbcb 100644 --- a/hell/_data/authors.js +++ b/hell/_data/authors.js @@ -89,6 +89,11 @@ module.exports = { "id": "moritzglantz", "name": "Moritz Glantz", "link": "https://moritzglantz.de" + }, + { + "id": "stevebarnett", + "name": "Steve Barnett", + "link": "https://human-centred.nz/" } ] }; From 607f44235f715ed796e25ff529462aa52bb6aedf Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Fri, 17 Oct 2025 14:53:08 +1300 Subject: [PATCH 02/19] Add headings post --- hell/adventcalendar/2025/18/index.md | 94 +++++++++++++++++++++------- 1 file changed, 73 insertions(+), 21 deletions(-) diff --git a/hell/adventcalendar/2025/18/index.md b/hell/adventcalendar/2025/18/index.md index 55fa9df5..9a5c7f36 100644 --- a/hell/adventcalendar/2025/18/index.md +++ b/hell/adventcalendar/2025/18/index.md @@ -1,35 +1,87 @@ --- title: "Giving pages a clear shape by using headings" -author: "Your Name" -author_bio: "Your short bio" +author: "Steve Barnett" +author_bio: "Steve Barnett is a human-centred front-end developer and user experience designer living in Aotearoa New Zealand. He helps software teams have happier customers by making more user-friendly software. That means making sites that everyone can use, regardless of their device, the network they’re on, or any disabilities they might have." date: 2025-12-18 author_links: - - label: "Site" - url: "https://linktoyourblog123.com" - link_label: "linktoyourblog123.com" -intro: "

Short introductory text

" + - label: "Personal website" + url: "https://human-centred.nz/" + link_label: "human-centred.nz" + - label: "Where I work" + url: "https://intopia.digital/" + link_label: "Intopia" +intro: "

The three most common ways that headings go wonky, and how to fix them!

" image: "advent25_18" --- -Some text. -Some text. -Some text. Some text. -## Heading +We can make our pages easier to understand by using headings to give our pages a clear shape. Our users might visually scan the page, use an extension or bookmarklet, jump around using assistive technology like a screen reader, or ask AI for a summary of the page. High quality headings can make things better for everyone. -Some text. +In my day job as a Digital Accessibility Consultant, there are a couple of ways that I've seen things go a bit... wonky. Let's go through the three most common ways, and how to fix them. -## Heading +## Text *should not* be a heading -Some text. +Ah, this one's a real classic! When we have some big and bold text, for Design Reasons, we sometimes take a bit of a shortcut and mark it up as a heading. Let's say an `

`, because it seems about the right size, or that’s what it says in the design file. But here's the thing: this text doesn't introduce or describe the content that follows. It just "needs" to be big for the look of it. +This is an issue because when things are marked up as headings that are not headings, it makes the page harder to understand. For example: users of assistive technology like screen readers hear things read as headings of section that are not headings. -

Note: Some text.

+### How to fix it -```html -

- - Hello World - -

-``` +Stop using HTML and start using CSS. Instead of using a heading element, using a `

` or `` or `

` element and use CSS to make it big and bold. Noice. + +## Text *should* be a heading + +Now let's come from the other side. We look at a design and see some bold text with some big, some bigger, some biggest. Sweet! We fling down a bunch of `
` elements, add some styles and we're done. It looks just like the design, chef's kiss, and so on. But here's the thing: this text looks like a heading, but doesn't have any semantics. + +This is an issue because when things that are headings aren't marked up as headings, it makes the page harder to understand. For example: screen readers won't announce it as a heading with its level, making it hard to understand the content and structure when listening to all the headings. Excellent. + +### How to fix it + +Stop using CSS and start using HTML. Instead of using a `

` or `` or `

` element, use a heading element at the right level to give it semantic structure: from `

` to `

`. + +## Headings do not reflect the content structure + +Okay, we've sorted out text that should and shouldn't be a heading: only things that are structural headings are marked as headings. Hooray! There's one more snag that we might hit: when the headings are in a weird order. For example: let's say we have a page listing edible things. We mark up `

`Fruit`

` as a section, and then `

`Apples`

` as a sub-section of Fruit. Maybe we've done this because that's what the styles in the design file suggest. But here's the thing: it's wonky because the headings don't represent the hierarchical relationships. + +This is an issue because users of assistive technology like screen readers use headings to understand how each section of the page relates to each other and the page as a whole. When the headings are wonky, the shape of the page is harder to understand. + +### How to fix it + +Use HTML to give the headings the correct nesting and ordering. Use CSS to make them look appropriately sized and shiny. + +I like to start from the page as a whole and work my way down. + +1. What’s the topic or purpose of this page? That text should be in an `

` element near the top of the page. +2. What are the sections of the page? The name of each section should be in an `

` element, at the start of the section. +3. What (if any) are the subsections of each section? The name of each subsection should be in an `

` element, at the start of the subsection. +4. What (if any) are the sub-subsections of each subsection? The name of each sub-subsection should be in an `

` element, at the start of the sub-subsection. +5. And so on, down to an `

` element. Although if you've reached an `
` element, it might be worth reviewing the content and seeing if there's Too Much Stuff there! + +The list of headings should read a bit like a table of contents for the page. + +## Other weird heading things + +There are other aspects of wonkiness that may occur. Keep a watch for these too! + +- **No headings at all on the page.** There's probably some text that should be a heading. +- **`

` shenanigans: no `

` element, or multiple `

` elements.** Just one `

` element, please! It should describe the topic or purpose of page. +- **Skipped heading levels**, for example: jumping from an `

` element to an `

` element. Keep the nesting and order correct: `

` elements for subsections of a section with an `

` heading. + +## Accessibility nerd corner + +The big three issues we started with all fall under [Web Content Accessibility Guidelines Success Criteria 1.3.1 Info and Relationships (A)](https://www.w3.org/TR/WCAG22/#info-and-relationships): "Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text." + +- "Text should not be a heading" and "Text should be a heading" are "If it looks like a thing, it must be the thing in code too" +- "Headings do not reflect the content structure" are "If it looks nested and order, it must be nested and ordered in code too" + +When we spot these issue in the course of an [Accessibility Assessment](https://intopia.digital/services/accessibility-usability-testing/), we usually log them as Medium Severity: it causes problems or frustrations for users. + +## Use your head(ings) + +Using headings to give our pages a clear shape makes them easier to understand. + +Make sure that: + +- text that functions as a heading is marked up as a heading +- text that does not function as a heading is not marked up as a heading +- headings reflect the content structure From 38e71ada3a1efd0c494e23a664ab4de68354c1c6 Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Wed, 5 Nov 2025 14:02:17 +1300 Subject: [PATCH 03/19] Update hell/adventcalendar/2025/18/index.md Co-authored-by: Manuel Matuzovic --- hell/adventcalendar/2025/18/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hell/adventcalendar/2025/18/index.md b/hell/adventcalendar/2025/18/index.md index 9a5c7f36..087e0b67 100644 --- a/hell/adventcalendar/2025/18/index.md +++ b/hell/adventcalendar/2025/18/index.md @@ -27,7 +27,7 @@ This is an issue because when things are marked up as headings that are not head ### How to fix it -Stop using HTML and start using CSS. Instead of using a heading element, using a `

` or `` or `

` element and use CSS to make it big and bold. Noice. +Stop using HTML and start using CSS. Instead of using a heading element, using a `

` or `` or `

` element and use CSS to make it big and bold. ## Text *should* be a heading From 8b1fdc5f7ab39e8bf11973e14f69bce0c250f655 Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Wed, 5 Nov 2025 14:02:29 +1300 Subject: [PATCH 04/19] Update hell/adventcalendar/2025/18/index.md Co-authored-by: Manuel Matuzovic --- hell/adventcalendar/2025/18/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hell/adventcalendar/2025/18/index.md b/hell/adventcalendar/2025/18/index.md index 087e0b67..c444db18 100644 --- a/hell/adventcalendar/2025/18/index.md +++ b/hell/adventcalendar/2025/18/index.md @@ -33,7 +33,7 @@ Stop using HTML and start using CSS. Instead of using a heading element, using a Now let's come from the other side. We look at a design and see some bold text with some big, some bigger, some biggest. Sweet! We fling down a bunch of `
` elements, add some styles and we're done. It looks just like the design, chef's kiss, and so on. But here's the thing: this text looks like a heading, but doesn't have any semantics. -This is an issue because when things that are headings aren't marked up as headings, it makes the page harder to understand. For example: screen readers won't announce it as a heading with its level, making it hard to understand the content and structure when listening to all the headings. Excellent. +This is an issue because when things that are headings aren't marked up as headings, it makes the page harder to understand. For example: screen readers won't announce it as a heading with its level, making it hard to understand the content and structure when listening to all the headings. ### How to fix it From 637b960155389911896f343f8d473a95cedfcb68 Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Wed, 5 Nov 2025 14:08:33 +1300 Subject: [PATCH 05/19] Tweak intro --- hell/adventcalendar/2025/18/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hell/adventcalendar/2025/18/index.md b/hell/adventcalendar/2025/18/index.md index c444db18..c7a4b230 100644 --- a/hell/adventcalendar/2025/18/index.md +++ b/hell/adventcalendar/2025/18/index.md @@ -15,7 +15,7 @@ image: "advent25_18" --- -We can make our pages easier to understand by using headings to give our pages a clear shape. Our users might visually scan the page, use an extension or bookmarklet, jump around using assistive technology like a screen reader, or ask AI for a summary of the page. High quality headings can make things better for everyone. +We can make our pages easier to understand by using headings to give our pages a clear shape. Our users might visually scan the page, use an extension or bookmarklet to list the headings, navigate using assistive technology like a screen reader, or ask AI for a summary of the page. High quality headings can make things better for everyone. In my day job as a Digital Accessibility Consultant, there are a couple of ways that I've seen things go a bit... wonky. Let's go through the three most common ways, and how to fix them. From 31f16e59b737185c5e14852a701062f262e250ee Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Wed, 5 Nov 2025 14:11:03 +1300 Subject: [PATCH 06/19] Add "what's a heading" helper bit --- hell/adventcalendar/2025/18/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hell/adventcalendar/2025/18/index.md b/hell/adventcalendar/2025/18/index.md index c7a4b230..1e17dd41 100644 --- a/hell/adventcalendar/2025/18/index.md +++ b/hell/adventcalendar/2025/18/index.md @@ -37,7 +37,7 @@ This is an issue because when things that are headings aren't marked up as headi ### How to fix it -Stop using CSS and start using HTML. Instead of using a `

` or `` or `

` element, use a heading element at the right level to give it semantic structure: from `

` to `

`. +Stop using CSS and start using HTML. Instead of using a `

` or `` or `

` element, use a heading element at the right level to give it semantic structure: from `

` to `

`. If we have some big and bold text that introduces or describes the content that follows, it should probably be a heading. ## Headings do not reflect the content structure From 8d1a6d222f3db944efa86f9d313262e0d283a011 Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Wed, 5 Nov 2025 14:23:39 +1300 Subject: [PATCH 07/19] Add a bit about WCAG SC 2.4.6 --- hell/adventcalendar/2025/18/index.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/hell/adventcalendar/2025/18/index.md b/hell/adventcalendar/2025/18/index.md index 1e17dd41..02b92319 100644 --- a/hell/adventcalendar/2025/18/index.md +++ b/hell/adventcalendar/2025/18/index.md @@ -63,6 +63,7 @@ The list of headings should read a bit like a table of contents for the page. There are other aspects of wonkiness that may occur. Keep a watch for these too! +- **Heading text that doesn't make sense.** The heading text should describe and introduce the content that follows it. - **No headings at all on the page.** There's probably some text that should be a heading. - **`

` shenanigans: no `

` element, or multiple `

` elements.** Just one `

` element, please! It should describe the topic or purpose of page. - **Skipped heading levels**, for example: jumping from an `

` element to an `

` element. Keep the nesting and order correct: `

` elements for subsections of a section with an `

` heading. @@ -76,6 +77,8 @@ The big three issues we started with all fall under [Web Content Accessibility G When we spot these issue in the course of an [Accessibility Assessment](https://intopia.digital/services/accessibility-usability-testing/), we usually log them as Medium Severity: it causes problems or frustrations for users. +Headings that aren't descriptive fall under [WCAG Success Criteria 2.4.6 Headings and Labels (AA)](https://www.w3.org/TR/WCAG22/#headings-and-labels). These are usually Medium Severity too. + ## Use your head(ings) Using headings to give our pages a clear shape makes them easier to understand. From c2e1e893ef5faba35b969f23621e670b771f697e Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Thu, 6 Nov 2025 16:11:26 +1300 Subject: [PATCH 08/19] Add a section about tools --- hell/adventcalendar/2025/18/index.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/hell/adventcalendar/2025/18/index.md b/hell/adventcalendar/2025/18/index.md index 02b92319..15e5b180 100644 --- a/hell/adventcalendar/2025/18/index.md +++ b/hell/adventcalendar/2025/18/index.md @@ -88,3 +88,12 @@ Make sure that: - text that functions as a heading is marked up as a heading - text that does not function as a heading is not marked up as a heading - headings reflect the content structure + +### Useful tools + +Two of my favourite ways to visualising headings are: + +- the Headings bookmarklet at [Accessibility Bookmarklets](https://accessibility-bookmarklets.org/install.html) +- the Headings toggle (in Ad hoc tools) of the [Accessibility Insights for Web](https://accessibilityinsights.io/docs/web/overview/) extension. + +Both of them add annotation-like boxes and text, making it easier scroll through and visually spot weird heading things. From fd9f457c61015b96a29096cedbcc788e751618e8 Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Thu, 6 Nov 2025 16:29:19 +1300 Subject: [PATCH 09/19] Add some example --- hell/adventcalendar/2025/18/index.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/hell/adventcalendar/2025/18/index.md b/hell/adventcalendar/2025/18/index.md index 15e5b180..48fefc5b 100644 --- a/hell/adventcalendar/2025/18/index.md +++ b/hell/adventcalendar/2025/18/index.md @@ -25,6 +25,18 @@ Ah, this one's a real classic! When we have some big and bold text, for Design R This is an issue because when things are marked up as headings that are not headings, it makes the page harder to understand. For example: users of assistive technology like screen readers hear things read as headings of section that are not headings. +### An example + +Let's say we have a page explaining colours, RGB-style. We might have headings marked up as follows. + +- `

`Colours + - `

`Red + - `

`Green + - `

`Your new favourite colour! + - `

`Blue + +In this case "Your new favourite colour!" is just some big text, designed to be eye-catching. It's not the start of a section of content. + ### How to fix it Stop using HTML and start using CSS. Instead of using a heading element, using a `

` or `` or `

` element and use CSS to make it big and bold. @@ -35,6 +47,17 @@ Now let's come from the other side. We look at a design and see some bold text w This is an issue because when things that are headings aren't marked up as headings, it makes the page harder to understand. For example: screen readers won't announce it as a heading with its level, making it hard to understand the content and structure when listening to all the headings. +### An example + +Let's say we have a page explaining what the web is made of. We might have some big bold text marked up as follows. + +- `

`The world wide web + - `

`HTML + - `

`CSS + - `

`JavaScript + +In this case "CSS" isn't just a paragraph. It's the start of a section of content. + ### How to fix it Stop using CSS and start using HTML. Instead of using a `

` or `` or `

` element, use a heading element at the right level to give it semantic structure: from `

` to `

`. If we have some big and bold text that introduces or describes the content that follows, it should probably be a heading. From d90687d014459ebeafb4a21025298217b3d1615b Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Wed, 12 Nov 2025 08:05:37 +1300 Subject: [PATCH 10/19] Remove repetition of ways --- hell/adventcalendar/2025/18/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hell/adventcalendar/2025/18/index.md b/hell/adventcalendar/2025/18/index.md index 48fefc5b..b9852e6f 100644 --- a/hell/adventcalendar/2025/18/index.md +++ b/hell/adventcalendar/2025/18/index.md @@ -17,7 +17,7 @@ image: "advent25_18" We can make our pages easier to understand by using headings to give our pages a clear shape. Our users might visually scan the page, use an extension or bookmarklet to list the headings, navigate using assistive technology like a screen reader, or ask AI for a summary of the page. High quality headings can make things better for everyone. -In my day job as a Digital Accessibility Consultant, there are a couple of ways that I've seen things go a bit... wonky. Let's go through the three most common ways, and how to fix them. +In my day job as a Digital Accessibility Consultant, there are a couple of ways that I've seen things go a bit... wonky. Let's go through the three most common issues, and how to fix them. ## Text *should not* be a heading From e693f9438d578dc52200743a70c267ebbb11a019 Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Wed, 12 Nov 2025 08:12:53 +1300 Subject: [PATCH 11/19] Try a different example text --- hell/adventcalendar/2025/18/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/hell/adventcalendar/2025/18/index.md b/hell/adventcalendar/2025/18/index.md index b9852e6f..15456f26 100644 --- a/hell/adventcalendar/2025/18/index.md +++ b/hell/adventcalendar/2025/18/index.md @@ -32,10 +32,10 @@ Let's say we have a page explaining colours, RGB-style. We might have headings m - `

`Colours - `

`Red - `

`Green - - `

`Your new favourite colour! + - `

`Make it pop! - `

`Blue -In this case "Your new favourite colour!" is just some big text, designed to be eye-catching. It's not the start of a section of content. +In this case "Make it pop!" is just some big text, designed to be eye-catching. It's not the start of a section of content. ### How to fix it From 217a54efdf558668073e99954ce49e8604476741 Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Wed, 12 Nov 2025 08:19:01 +1300 Subject: [PATCH 12/19] Remove "For examples", tweak text --- hell/adventcalendar/2025/18/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/hell/adventcalendar/2025/18/index.md b/hell/adventcalendar/2025/18/index.md index 15456f26..8526f7fa 100644 --- a/hell/adventcalendar/2025/18/index.md +++ b/hell/adventcalendar/2025/18/index.md @@ -23,7 +23,7 @@ In my day job as a Digital Accessibility Consultant, there are a couple of ways Ah, this one's a real classic! When we have some big and bold text, for Design Reasons, we sometimes take a bit of a shortcut and mark it up as a heading. Let's say an `

`, because it seems about the right size, or that’s what it says in the design file. But here's the thing: this text doesn't introduce or describe the content that follows. It just "needs" to be big for the look of it. -This is an issue because when things are marked up as headings that are not headings, it makes the page harder to understand. For example: users of assistive technology like screen readers hear things read as headings of section that are not headings. +This is an issue because when things are marked up as headings that are not headings, it makes the page harder to understand. Users of assistive technology like screen readers hear things read as headings of section that are not headings. ### An example @@ -45,7 +45,7 @@ Stop using HTML and start using CSS. Instead of using a heading element, using a Now let's come from the other side. We look at a design and see some bold text with some big, some bigger, some biggest. Sweet! We fling down a bunch of `
` elements, add some styles and we're done. It looks just like the design, chef's kiss, and so on. But here's the thing: this text looks like a heading, but doesn't have any semantics. -This is an issue because when things that are headings aren't marked up as headings, it makes the page harder to understand. For example: screen readers won't announce it as a heading with its level, making it hard to understand the content and structure when listening to all the headings. +This is an issue because when text is marked up as a heading even though it isn’t one, it makes the page harder to understand. Screen readers won't announce it as a heading with its level, making it hard to understand the content and structure when listening to all the headings. ### An example From 0f1f3e13251e84caa26039a8263cd26e854499a3 Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Wed, 12 Nov 2025 08:22:49 +1300 Subject: [PATCH 13/19] Tweak sentence structure --- hell/adventcalendar/2025/18/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hell/adventcalendar/2025/18/index.md b/hell/adventcalendar/2025/18/index.md index 8526f7fa..c806bdb2 100644 --- a/hell/adventcalendar/2025/18/index.md +++ b/hell/adventcalendar/2025/18/index.md @@ -43,7 +43,7 @@ Stop using HTML and start using CSS. Instead of using a heading element, using a ## Text *should* be a heading -Now let's come from the other side. We look at a design and see some bold text with some big, some bigger, some biggest. Sweet! We fling down a bunch of `
` elements, add some styles and we're done. It looks just like the design, chef's kiss, and so on. But here's the thing: this text looks like a heading, but doesn't have any semantics. +Now let's come from the other side. We look at a design and see some bold text. Some big, some bigger, some biggest. Sweet! We fling down a bunch of `
` elements, add some styles and we're done. It looks just like the design, chef's kiss, and so on. But here's the thing: this text looks like a heading, but doesn't have any semantics. This is an issue because when text is marked up as a heading even though it isn’t one, it makes the page harder to understand. Screen readers won't announce it as a heading with its level, making it hard to understand the content and structure when listening to all the headings. From 6f02230c4c50919cead40ab81b7ccb63eb4c0aed Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Wed, 12 Nov 2025 08:27:07 +1300 Subject: [PATCH 14/19] Fix tpoy --- hell/adventcalendar/2025/18/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hell/adventcalendar/2025/18/index.md b/hell/adventcalendar/2025/18/index.md index c806bdb2..c3263ba6 100644 --- a/hell/adventcalendar/2025/18/index.md +++ b/hell/adventcalendar/2025/18/index.md @@ -114,7 +114,7 @@ Make sure that: ### Useful tools -Two of my favourite ways to visualising headings are: +Two of my favourite ways to visualise headings are: - the Headings bookmarklet at [Accessibility Bookmarklets](https://accessibility-bookmarklets.org/install.html) - the Headings toggle (in Ad hoc tools) of the [Accessibility Insights for Web](https://accessibilityinsights.io/docs/web/overview/) extension. From 809fbde889666c59fa2658a9317734e0b763618d Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Wed, 12 Nov 2025 08:31:00 +1300 Subject: [PATCH 15/19] Tweak "other weird" section --- hell/adventcalendar/2025/18/index.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/hell/adventcalendar/2025/18/index.md b/hell/adventcalendar/2025/18/index.md index c3263ba6..34cb17fd 100644 --- a/hell/adventcalendar/2025/18/index.md +++ b/hell/adventcalendar/2025/18/index.md @@ -86,10 +86,9 @@ The list of headings should read a bit like a table of contents for the page. There are other aspects of wonkiness that may occur. Keep a watch for these too! -- **Heading text that doesn't make sense.** The heading text should describe and introduce the content that follows it. -- **No headings at all on the page.** There's probably some text that should be a heading. +- **Heading text that doesn't describe the content that follows.** The words of the heading must introduce the section. - **`

` shenanigans: no `

` element, or multiple `

` elements.** Just one `

` element, please! It should describe the topic or purpose of page. -- **Skipped heading levels**, for example: jumping from an `

` element to an `

` element. Keep the nesting and order correct: `

` elements for subsections of a section with an `

` heading. +- **Skipped heading levels**, for example: jumping from an `

` element to an `

` element, without an `

` between them. Keep the nesting and order correct: `

` elements for subsections of a section with an `

` heading. ## Accessibility nerd corner From da8c2ec2f8db46977e91fd221045d4f8389b39e1 Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Wed, 12 Nov 2025 08:37:38 +1300 Subject: [PATCH 16/19] Tweak heading text bullet in weird section --- hell/adventcalendar/2025/18/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hell/adventcalendar/2025/18/index.md b/hell/adventcalendar/2025/18/index.md index 34cb17fd..11a4dbeb 100644 --- a/hell/adventcalendar/2025/18/index.md +++ b/hell/adventcalendar/2025/18/index.md @@ -86,7 +86,7 @@ The list of headings should read a bit like a table of contents for the page. There are other aspects of wonkiness that may occur. Keep a watch for these too! -- **Heading text that doesn't describe the content that follows.** The words of the heading must introduce the section. +- **Heading text that doesn't describe the content that follows.** The words of the heading must introduce the section. Ask your friendly Content writer for help! - **`

` shenanigans: no `

` element, or multiple `

` elements.** Just one `

` element, please! It should describe the topic or purpose of page. - **Skipped heading levels**, for example: jumping from an `

` element to an `

` element, without an `

` between them. Keep the nesting and order correct: `

` elements for subsections of a section with an `

` heading. From c67a162da1e57fd678cca168715bc2ec164915a0 Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Wed, 12 Nov 2025 08:45:31 +1300 Subject: [PATCH 17/19] Try a more clear nerd section --- hell/adventcalendar/2025/18/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/hell/adventcalendar/2025/18/index.md b/hell/adventcalendar/2025/18/index.md index 11a4dbeb..89fa4d8d 100644 --- a/hell/adventcalendar/2025/18/index.md +++ b/hell/adventcalendar/2025/18/index.md @@ -94,8 +94,8 @@ There are other aspects of wonkiness that may occur. Keep a watch for these too! The big three issues we started with all fall under [Web Content Accessibility Guidelines Success Criteria 1.3.1 Info and Relationships (A)](https://www.w3.org/TR/WCAG22/#info-and-relationships): "Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text." -- "Text should not be a heading" and "Text should be a heading" are "If it looks like a thing, it must be the thing in code too" -- "Headings do not reflect the content structure" are "If it looks nested and order, it must be nested and ordered in code too" +- The "Text should not be a heading" and "Text should be a heading" issues are about the information. +- The "Headings do not reflect the content structure" issue is about structure and relationships. When we spot these issue in the course of an [Accessibility Assessment](https://intopia.digital/services/accessibility-usability-testing/), we usually log them as Medium Severity: it causes problems or frustrations for users. From a9996537209794791ec537a08cb17e77d449d238 Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Fri, 14 Nov 2025 06:58:19 +1300 Subject: [PATCH 18/19] Bump bullet to sentence --- hell/adventcalendar/2025/18/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/hell/adventcalendar/2025/18/index.md b/hell/adventcalendar/2025/18/index.md index 89fa4d8d..baa6d838 100644 --- a/hell/adventcalendar/2025/18/index.md +++ b/hell/adventcalendar/2025/18/index.md @@ -78,7 +78,8 @@ I like to start from the page as a whole and work my way down. 2. What are the sections of the page? The name of each section should be in an `

` element, at the start of the section. 3. What (if any) are the subsections of each section? The name of each subsection should be in an `

` element, at the start of the subsection. 4. What (if any) are the sub-subsections of each subsection? The name of each sub-subsection should be in an `

` element, at the start of the sub-subsection. -5. And so on, down to an `

` element. Although if you've reached an `
` element, it might be worth reviewing the content and seeing if there's Too Much Stuff there! + +And we keep going, down to an `
` element. Although if you've reached an `
` element, it might be worth reviewing the content and seeing if there's Too Much Stuff there! The list of headings should read a bit like a table of contents for the page. From a815e675022918509e80649badd1bebaad9612dc Mon Sep 17 00:00:00 2001 From: Steve Barnett Date: Fri, 14 Nov 2025 07:11:11 +1300 Subject: [PATCH 19/19] Use a different example in "should" --- hell/adventcalendar/2025/18/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/hell/adventcalendar/2025/18/index.md b/hell/adventcalendar/2025/18/index.md index baa6d838..0da48efa 100644 --- a/hell/adventcalendar/2025/18/index.md +++ b/hell/adventcalendar/2025/18/index.md @@ -45,7 +45,8 @@ Stop using HTML and start using CSS. Instead of using a heading element, using a Now let's come from the other side. We look at a design and see some bold text. Some big, some bigger, some biggest. Sweet! We fling down a bunch of `
` elements, add some styles and we're done. It looks just like the design, chef's kiss, and so on. But here's the thing: this text looks like a heading, but doesn't have any semantics. -This is an issue because when text is marked up as a heading even though it isn’t one, it makes the page harder to understand. Screen readers won't announce it as a heading with its level, making it hard to understand the content and structure when listening to all the headings. +This is an issue because when text is marked up as a heading even though it isn’t one, it makes the page harder to understand. People using bookmarklets or browser extensions to list headings won't see this text in the list of headings. + ### An example