✨ Inclusive components #2: the importance of headings
Tags: a11y, frontend, inclusive
Published: 2021-03-10 19:54:56

---
title: ✨ Inclusive components #2: the importance of headings
published: true
description: "Considerations for headings order and landmarks for users with the diversity of abilities. Comparison of inaccessible and accessible headings."
tags: #a11y, #accessibility, #frontend, #inclusive
cover_image: https://i.ibb.co/sRnhVgZ/core-design-system-template.jpg
---

# Introduction

Heading elements (`h1`, `h2`, `h3`, etc.) help to break up the content of the page into related “chunks” of information. They are incredibly important for people who use assistive technology. If headings and HTML landmarks are used correctly, the user understands the meaning of a page or view and has a better experience.


## Quick example

To illustrate the point, I want to show two examples:
Imagine that we have:

* 💡 A simple website, where visually we can distinguish the "blocks" of content, with headings, images and we clearly see the overall hierarchy. 
![a simple website of the page has 3 cards with images, logo, and headings, looking like posts](https://i.ibb.co/9nxX7KR/Screenshot-2021-03-10-at-18-16-11.png)

We don't know yet whether the code behind it actually using `h1`, `h2` and so on, but visually it's clear where the titles are and what is in front of us. 

* This is the same website with no heading structure and no hierarchy. For the users with assistive technology, it creates overall confusion since there is no way to know where to navigate.
This is how it looks for the users that use a screen reader. 
![a simple website of the page has 3 cards with images, logo, and headings, looking like posts and screen reader window](https://i.ibb.co/mGFChLt/Screenshot-2021-03-10-at-18-15-57.png)
* And here is how the website looks for them, when we - developers - code the correct document structure and respect heading order.
![a simple website of the page has 3 cards with images, logo, and headings, looking like posts and screen reader window](https://i.ibb.co/7JwN6dD/Screenshot-2021-03-10-at-18-18-27.png)

By the way, I'm taking the images example from A11ycasts#18 video with Rob Dondson, that I highly recommend watching 👉 [A11ycasts episode on Youtube](https://www.youtube.com/watch?v=vAAzdi1xuUY&ab_channel=GoogleChromeDevelopers)  

## "But I want to do it the right way. Where can I start?" 👩🏼‍💻

First, understand that users who use the keyboard and screen reader must be able to skip the content, navigate the web and get an equally good experience from the start. 

Secondly, let's answer some of the questions with accessibility in mind:

* Does your website makes sense if you view it after having turned off JS/CSS?
* DOM order matches the visual order?
* Can you navigate with the normal flow?
* Do users have the ability to jump to any section of the document and get to the information quickly?

As you may know, screen reader users use heading to navigate through the page.

✨VoiceOver Keyboard Shortcuts✨

`VO+H(Control+Option+H) to navigate`

`Control + Option + U to open rotor`

Can you see how users can immediately benefit from the correct HTML tag and order?
![Screenshot from Lindsey a11ywithlindsey.com with heading and the window of the screen "reading" heading out loud the first heading](https://i.ibb.co/YfhXJvr/Screenshot-2021-03-10-at-19-50-56.png =250x)

Consider the example: 

```html
<h1>Title of the Page</h1>
<p>Here's a little bit of information before we get started</p> 
<h2>Hey you, heading 2</h2>
<p>Here's a little bit of info about the second heading</p> 
<h2>Here's another heading for testing purposes</h2>
<p>Here's a little bit of info about the second heading</p>
```

### WCAG failures:
* Heading-like text that isn’t marked up as headings (Level A)
```html
❌
<p class="title">Introduction</p>
<div class="subtitle">Looks like a subtitle</div>
```
* Illogical heading order (`<h2>` is not followed directly by an `<h4>`) (Level A)
```html
❌
<h3>Bacon and mushroom risotto</h3>
<p>To cook a perfect risotto, it is essential to […] </p>
<h2>Instructions</h2>

❌
<h2 class="card-subheading">Subheading</h2>
<h4 class="card-heading">Heading</h4>
```
* Nondescriptive headings (Level AA)
```html
<h2>Recipe</h2>
<p>To cook a perfect risotto, it is essential to […] </p>
<h2>Recipe</h2>
<p>A coq au vin is a classic French stew in which […] </p>
```
### Bad scenarios 🤨:

Not every issue counts as a WCAG failure, but they all potentially cause some confusion and pose potential barriers for people with disabilities. Such as:

* A lack of headings (unless you’re striving for Level AAA)
* Missing `<h1>`
* More than one `<h1>` per page
* Do not select heading levels based on their appearance (font-size). Select the appropriate heading rank in your hierarchy.
* Using headings that don’t appropriately describe their related content does represent a failure of 2.4.6 Headings and Labels.
* **Headings should not be used as subheadings, subtitles, alternative titles, taglines, or slogans. In such cases, it is best to use a <p> tag.**

### Best practices (common sense)✅:
* Headings are ranked `<h1>` through `<h6>`.
    - `<h1>` representing the most important idea on the page
    - sub-sections organized with `<h2>` level headings. Those sub-sections can themselves be divided with `<h3>` level headings, and so on.
* Heading levels should increase by one h1 > h2 > h3 > h4 > h5 > h6

```html
❌
<h1>Title</h1>
<h3>Some text that's not a heading, but we want "bigger" text</h3>

✅
<h1>Title</h1>
<h2>Chapter1</h2>
<h3>Some subsection</h3> 
<h2>Chapter2</h2>
<h3>Some subsection</h3>
```
#### <h1> 
* The beginning of the main content should start with `<h1>`

```html
<body>
  <header>logo - navigation</header>
  <main>
    <h1>Home page</h1>
  </main>
</body>
```

* Most web pages should have only one `<h1>`
* `<h1>` representing the most important idea on the page. At the same time, hero `h1` does not **necessarily** represent the page, but it's just a slogan. 
#### What if the design doesn't have a heading?
![a simple website of the page has 3 cards with images, logo and headings, looking like posts](https://i.ibb.co/9nxX7KR/Screenshot-2021-03-10-at-18-16-11.png)

Or it's not always can be present, but the page still should have the `h1` heading to give the user context.

```html
<body>
  <header>logo - navigation</header>
  <main>
    <h1 class="sr-only">Showcase page or another heading name</h1>
  </main>
</body>
```

### Specs

* Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. **(Level A)**
* Screen readers allow users to navigate by headings, so headings are an effective way to bypass blocks of content, as required by WCAG 2.4.1 **(Level A)**
* Headings MUST be accurate and informative, as labels for the sections of text they describe. **(Level AA)**
* Section headings are used to organize the content. **(Level AAA)**

### Alternatives

If a scenario arises where you can’t make changes to existing elements’ hierarchy, there is an alternative method that you can use to provide semantics: using Accessible Rich Internet Applications (**ARIA**).

`role="heading"` can be placed on an element to assign it a role of heading.`aria-level` needs to be placed on the same element as `role="heading"` to assign the element’s heading level.


### HTML5 outline

Sadly, heading algorithm **was never really picked up by any browser or screen reader**, and the HTML 5.2 draft advises against using it any further.

### Real-world example

Here is a snippet from React library (linked in resources below) that implemented accessible `<Heading/>` and `<Section/>` components.

```jsx
// Section

<section aria-labelledby={labelId} className={hidden ? "ric-hidden" : className} {...rest}>
  <Heading id={labelId} element={`h${level}`} className={noHeading ? "ric-hidden" : ""}>
    {label}
  </Heading>
  {props.children}
</section>

// Heading

const Heading = props => {
  const { element, className = "", hidden, ...rest } = props;

  const Element = element;

  return (
    <Element
      className={hidden ? `ric-hidden ${className}` : className}
      {...rest}
    />
  );
};
```

## Resources 📂

### A collection of inclusive components for React created with styled-components worth your attention if you want to quickly improve #a11y of the app 👩🏼‍💻
{% github pbilyk/react-inclusive-components %}

### "Quick Reference" that I use a lot:
[A customizable quick reference to Web Content Accessibility Guidelines (WCAG) 2 requirements](https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0)

### WCAG criteria

[1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG21/#info-and-relationships): Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. (Level A)

[2.4.6 Headings and Labels](https://www.w3.org/TR/WCAG21/#headings-and-labels): Headings and labels describe topic or purpose. (Level AA)

WCAG 2.1 through Level AA doesn’t require subheadings. Level AAA takes it up a level

[2.4.10 Section Headings](https://www.w3.org/TR/WCAG21/#section-headings): Section headings are used to organize the content. (Level AAA)

## Conclusion 💡

Guess how many heading I used in order to structure this post? 

![Markdown rules about heading usage](https://i.ibb.co/ZXS1TCS/Screenshot-2021-03-10-at-20-20-57.png =250x)

I kept getting back and forth in between "code" and preview in order to make my markdown match the visual structure. Can we do the same with our webs?

Remember: 
✨**The more you do it, the less of the effort it takes**✨

If you like this article and the information that I have put together for you this time, please, share it with your colleague and reach out to me on Twitter, whether you liked it or have suggestions 💚


{% twitter 1363457207241740288 %}