incorrect-heading-ai

Ensures that non-headings should not be incorrectly marked as headings.

Description

Text that does not functionally act as a heading must not be incorrectly marked using heading tags (<h1>–<h6>) or the WAI-ARIA role role="heading".

This rule uses AI to identify false headings. It analyzes contextual placement, surrounding content, semantics, and visual cues to determine if the text is truly a sectional heading.

Users rely on a logical heading structure to understand the document outline and navigate efficiently. Incorrectly marking non-heading text as headings confuses users of screen readers and other assistive tools.

The incorrect-heading-ai rule aligns with WCAG Success Criterion 1.3.1 (Info and Relationships) and WCAG Success Criterion 2.4.6 (Headings and Labels). These criteria ensure that structure is programmatically determinable and that headings accurately describe the content they introduce.

Examples

In the following example, a figure caption is incorrectly marked as a level 2 heading (<h2>).

In the following corrected example, the caption is placed inside a <figcaption> element. This ensures the text is correctly associated with the figure without appearing in the page’s heading outline:

How to fix?

To fix violations of the incorrect-heading-ai rule, follow these steps:

• Identify the element: Locate the text that the rule flagged as an incorrectly marked heading.

• Determine its function: Evaluate the text’s actual role on the page. If it does not introduce a new section of content, do not treat it as a heading.

• Remove incorrect markup: Remove the heading tag (<h1> - <h6>) or role="heading".

• Use correct semantics: Replace the incorrect markup with an appropriate tag, such as:

  • A standard paragraph tag (<p>).

  • A <figcaption> for descriptive content related to a <figure>.

• Maintain visual style: If you used the heading element solely for its visual appearance, apply the necessary styling (like font size or bolding) using CSS instead of a structural heading tag.

Reference

• WCAG Success Criterion 1.3.1: Info and Relationships
• WCAG Success Criterion 2.4.6: Headings and Labels