TOP013 - Descriptive headings

Tags: accessibility, headings

Aliases: descriptive-headings

Fixable via script: Not fixable due to being context-based

This rule is triggered when a heading exactly matches one of our blacklisted headings (case insensitive and ignoring trailing punctuation). This list contains commonly used headings that are insufficiently descriptive for their contents and are thus insufficiently accessible.

Examples include (but are not limited to) "Note", "Tip", "A tip", "Warning", "Important", "Important note", and "Remember":

### Important

The HTML boilerplate in the `index.html` file is complete at this point, but how do you view it in the browser? There are a couple of different options:

<div class="lesson-note lesson-note--warning" markdown="1">

#### Remember!

In order to avoid branching our lesson’s instructions to accommodate for all of the differences between browsers, we are going to be using Google Chrome as our primary browser for the remainder of this course. All references to the browser will pertain specifically to Google Chrome. We strongly suggest that you use Google Chrome for all of your testing going forward.

</div>

In the above, there are two headings and neither of them really let you know what the section or note box's contents will talk about.

Headings should ideally be brief; being descriptive does not mean they have to be some long paragraph. Both headings can be rephrased to be more descriptive by themselves:

### Viewing HTML files in the browser

The HTML boilerplate in the `index.html` file is complete at this point, but how do you view it in the browser? There are a couple of different options:

<div class="lesson-note lesson-note--warning" markdown="1">

#### Use Google Chrome

In order to avoid branching our lesson’s instructions to accommodate for all of the differences between browsers, we are going to be using Google Chrome as our primary browser for the remainder of this course. All references to the browser will pertain specifically to Google Chrome. We strongly suggest that you use Google Chrome for all of your testing going forward.

</div>

Rationale

Anyone navigating by heading, whether that's via assistive technology or just scanning the page, will find it much harder to locate information if headings are too generic. It can also be easier to follow the contents of a section or note box when the heading sets an expectation for the topic to come. Headings are also linkable via ID fragments based on their text. It's easier to know what the link will go to if the heading is sufficiently descriptive of its contents.