missing-heading-ai

Ensure that headings should be marked using standard semantic HTML elements or ARIA.

Description

The missing-heading-ai rule uses AI to detects content that looks like a heading but is not correctly identified as one using standard semantic HTML elements or ARIA.

Text intended to function as a heading must be programmatically identified as such. This ensures that users of assistive technologies, like screen readers, can efficiently navigate the page structure.

The rule uses Artificial Intelligence (AI) to determine heading intent based on several visual and contextual factors, including:

• Visual styling (e.g., font size, bolding, capitalization)
• Position on the page
• Context and structure within the neighboring content

This rule aligns with WCAG Success Criterion 1.3.1 (Info and Relationships), which requires that structure and relationships conveyed through visual presentation are also programmatically determinable. It also supports WCAG Success Criterion 2.4.6 (Headings and Labels), which requires clear and descriptive headings.

Examples

In the following example, the text is styled to look like a heading (large, bold font) but is wrapped in a generic <div> element instead of a semantic heading tag (<h1> through <h6>).

In the following corrected example, the same content uses the appropriate semantic heading tag (<h2>) to convey its structural role.

How to fix?

To fix violations of the missing-heading-ai rule, ensure you use the correct semantic HTML for content that visually functions as a heading.

• Identify the intent: If the text introduces a section of content and looks like a heading (e.g., larger font, bolded, or separated from the main text), it must be marked as one.

• Use semantic tags: Wrap the heading text in the appropriate heading element, from <h1> to <h6>. Use only one <h1> per page. Maintain a logical, hierarchical structure (e.g., do not jump from <h2> to <h4>).

• Use ARIA as a fallback: If you cannot use a semantic heading element (e.g., due to limitations in a third-party component), apply the ARIA role role="heading" and the appropriate level aria-level="N" (where N is 1 through 6).

Example using ARIA:

<div role="heading" aria-level="2">
    Pricing Plans
</div>

Reference

WCAG Success Criterion 1.3.1: Info and Relationships

WCAG Success Criterion 2.4.6: Headings and Labels