Typography

heading-hierarchy

Enforce sequential heading levels and at most one <h1> per file.

Flags heading sequences that skip levels (h1 → h3) and pages with more than one h1. Heading hierarchy is structural metadata for assistive tech, search engines, and outline generators — AI-generated marketing pages routinely break it.

Behavior

• Fixable: No.
• Suggestions: No.
• Maps to: WCAG 1.3.1 (Info and Relationships), 2.4.6 (Headings and Labels).

Examples

Bad:

<h1>Title</h1>
<h3>Subsection</h3>

Good:

<h1>Title</h1>
<h2>Section</h2>
<h3>Subsection</h3>

Related rules

• prefer-semantic-htmlPrefer semantic HTML over <div onClick> and redundant ARIA roles.
• no-arbitrary-typographyDisallow arbitrary font-size, weight, and line-height values.
• link-textForbid empty anchors and generic "click here" link text.

Use it

Enable heading-hierarchy in your eslint.config.js:

import deslint from '@deslint/eslint-plugin';

export default [
  {
    plugins: { deslint },
    rules: {
      'deslint/heading-hierarchy': 'error',
    },
  },
];

Found a false positive? Report it on GitHub →

← Back to all rules