---
description: Heading element accessibility compliance and WCAG 2.4.1 Bypass Blocks requirements
globs: *.vue, *.jsx, *.tsx, *.html, *.php, *.js, *.ts, *.liquid
alwaysApply: true
---
# Heading Element Accessibility Standards

Ensures heading elements follow WCAG compliance and provide proper content structure for screen reader navigation and bypass blocks functionality.

<rule>
name: heading_accessibility_standards
description: Enforce heading element accessibility standards per WCAG 2.4.1 Bypass Blocks requirements
filters:
  - type: file_extension
    pattern: "\\.(vue|jsx|tsx|html|liquid|php|js|ts)$"

actions:
  - type: enforce
    conditions:
      # Missing heading markup for visually styled headings
      - pattern: "(?i)<(div|span|p)[^>]*(?:heading|title|header)[^>]*>"
        pattern_negate: "(role=\"heading\"|h[1-6])"
        message: "Text that acts as a heading visually or structurally must be designated as a true heading (h1-h6) or use role='heading' with aria-level."

      # Heading markup on non-heading content
      - pattern: "(?i)<(h[1-6]|div[^>]*role=\"heading\")[^>]*>"
        pattern_negate: "(heading|title|header|section|main|content|page)"
        message: "Text that does not act as a heading visually or structurally should not be marked as a heading."

      # Missing aria-level on role="heading"
      - pattern: "(?i)<[^>]*role=\"heading\"[^>]*>"
        pattern_negate: "aria-level=\"[1-6]\""
        message: "Elements with role='heading' must have aria-level attribute set to appropriate level (1-6)."

      # Invalid aria-level values
      - pattern: "(?i)aria-level=\"[^1-6]\""
        message: "aria-level must be set to a value between 1 and 6 for heading elements."

      # Missing h1 in main content
      - pattern: "(?i)<main[^>]*>"
        pattern_negate: "<h1[^>]*>"
        message: "Main content should start with an h1 heading for proper document structure."

      # Multiple h1 elements (potential issue)
      - pattern: "(?i)<h1[^>]*>.*<h1[^>]*>"
        message: "Most web pages should have only one h1 element. Consider using h2-h6 for section headings."

      # Skipped heading levels
      - pattern: "(?i)<h1[^>]*>.*<h3[^>]*>"
        message: "Headings should not skip hierarchical levels. Consider using h2 before h3."

      - pattern: "(?i)<h2[^>]*>.*<h4[^>]*>"
        message: "Headings should not skip hierarchical levels. Consider using h3 before h4."

      # Clickable headings with improper structure
      - pattern: "(?i)<a[^>]*>.*<h[1-6][^>]*>.*</h[1-6]>.*</a>"
        message: "Heading elements should not be children of link elements. The heading should wrap the link to maintain semantic structure."

      # Empty or meaningless heading text
      - pattern: "(?i)<h[1-6][^>]*>\\s*(?:&nbsp;|\\s|&amp;nbsp;)*</h[1-6]>"
        message: "Heading elements should contain meaningful text content."

      # Generic heading text
      - pattern: "(?i)<h[1-6][^>]*>\\s*(?:heading|title|header|section)\\s*</h[1-6]>"
        message: "Heading text should be specific and informative, not generic."

      # Heading text too long
      - pattern: "(?i)<h[1-6][^>]*>[^<]{100,}</h[1-6]>"
        message: "Heading text should be concise and relatively brief."

      # Missing heading for major content sections
      - pattern: "(?i)<(section|article|main)[^>]*>"
        pattern_negate: "<h[1-6][^>]*>"
        message: "Major content sections should have appropriate heading elements for navigation."

  - type: suggest
    message: |
      **WCAG 2.4.1 Heading Accessibility Requirements:**

      **Bypass Blocks Functionality:**
      - **Screen Reader Navigation:** Headings allow users to navigate by content sections
      - **Content Structure:** Headings provide clear outline of page content
      - **Landmark Support:** Headings work with landmarks and skip links for navigation

      **Heading Markup Requirements:**

      **1. Use Real Heading Elements:**
      ```html
      <!-- Good: Proper heading markup -->
      <h1>Main Page Title</h1>
      <h2>Section Heading</h2>
      <h3>Subsection Heading</h3>

      <!-- Good: Role heading when real markup not possible -->
      <div role="heading" aria-level="1">Main Page Title</div>
      <div role="heading" aria-level="2">Section Heading</div>
      ```

      **2. Proper Heading Hierarchy:**
      ```html
      <!-- Good: Logical heading structure -->
      <h1>Product Catalog</h1>
      <h2>Electronics</h2>
      <h3>Smartphones</h3>
      <h3>Laptops</h3>
      <h2>Clothing</h2>
      <h3>Men's Clothing</h3>
      <h3>Women's Clothing</h3>

      <!-- Bad: Skipped levels -->
      <h1>Product Catalog</h1>
      <h3>Electronics</h3> <!-- Skipped h2 -->
      ```

      **3. Clickable Headings:**
      ```html
      <!-- Good: Heading wraps the link -->
      <h2><a href="/products/electronics">Electronics</a></h2>

      <!-- Bad: Heading as child of link -->
      <a href="/products/electronics">
        <h2>Electronics</h2>
      </a>
      ```

      **4. Meaningful Heading Text:**
      ```html
      <!-- Good: Specific and informative -->
      <h1>Acme Corporation - Leading Tech Solutions</h1>
      <h2>Our Services</h2>
      <h3>Web Development</h3>
      <h3>Mobile App Development</h3>

      <!-- Bad: Generic or meaningless -->
      <h1>Welcome</h1>
      <h2>Section</h2>
      <h3>Content</h3>
      ```

      **5. Single H1 Per Page:**
      ```html
      <!-- Good: One main heading -->
      <h1>Company Homepage</h1>
      <h2>About Us</h2>
      <h2>Our Services</h2>
      <h2>Contact</h2>

      <!-- Bad: Multiple h1 elements -->
      <h1>Company Homepage</h1>
      <h1>About Us</h1> <!-- Should be h2 -->
      ```

      **6. Proper Content Structure:**
      ```html
      <!-- Good: Clear content outline -->
      <main>
        <h1>Product Documentation</h1>
        <section>
          <h2>Installation Guide</h2>
          <h3>System Requirements</h3>
          <h3>Installation Steps</h3>
        </section>
        <section>
          <h2>User Manual</h2>
          <h3>Getting Started</h3>
          <h3>Advanced Features</h3>
        </section>
      </main>
      ```

      **7. Role Heading Implementation:**
      ```html
      <!-- When real heading elements cannot be used -->
      <div role="heading" aria-level="1">Main Page Title</div>
      <div role="heading" aria-level="2">Section Heading</div>
      <div role="heading" aria-level="3">Subsection Heading</div>

      <!-- With proper aria-level values -->
      <div role="heading" aria-level="1">Company Overview</div>
      <div role="heading" aria-level="2">Our Mission</div>
      <div role="heading" aria-level="2">Our Values</div>
      ```

      **Heading Guidelines:**

      **Content Structure:**
      - **H1:** Main page title or primary content heading
      - **H2:** Major section headings
      - **H3:** Subsection headings
      - **H4-H6:** Further subdivisions as needed

      **Text Requirements:**
      - **Concise:** Keep heading text brief and to the point
      - **Descriptive:** Accurately describe the content that follows
      - **Unique:** Each heading should be distinct and meaningful
      - **Hierarchical:** Follow logical content structure

      **Navigation Benefits:**
      - **Screen Reader Users:** Can jump between sections using heading navigation
      - **Keyboard Users:** Can navigate page structure efficiently
      - **All Users:** Clear content organization and hierarchy

      **Implementation Best Practices:**

      **Page Structure Example:**
      ```html
      <header>
        <nav>
          <!-- Navigation content -->
        </nav>
      </header>

      <main>
        <h1>Product Documentation</h1>

        <section>
          <h2>Getting Started</h2>
          <h3>Installation</h3>
          <h3>Configuration</h3>
        </section>

        <section>
          <h2>User Guide</h2>
          <h3>Basic Features</h3>
          <h3>Advanced Features</h3>
          <h4>Customization</h4>
          <h4>Integration</h4>
        </section>

        <section>
          <h2>Troubleshooting</h2>
          <h3>Common Issues</h3>
          <h3>Support</h3>
        </section>
      </main>
      ```

      **Dynamic Content:**
      ```html
      <!-- Good: Proper heading for dynamic content -->
      <h2>Search Results</h2>
      <p>Found 15 results for "accessibility"</p>

      <!-- Good: Descriptive heading for filtered content -->
      <h2>Electronics (25 items)</h2>
      <p>Showing 1-10 of 25 products</p>
      ```

      **Form Sections:**
      ```html
      <!-- Good: Clear form structure with headings -->
      <h2>Contact Information</h2>
      <form>
        <label for="name">Name:</label>
        <input type="text" id="name">

        <label for="email">Email:</label>
        <input type="email" id="email">
      </form>

      <h2>Shipping Address</h2>
      <form>
        <label for="address">Address:</label>
        <input type="text" id="address">
      </form>
      ```

      **Testing and Validation:**
      - Test with screen reader heading navigation
      - Verify heading hierarchy is logical
      - Check that heading text is descriptive
      - Ensure no skipped heading levels
      - Validate single h1 per page
      - Test keyboard navigation between headings

      **Common Mistakes to Avoid:**
      - Using heading elements for styling only
      - Skipping heading levels (h1 → h3)
      - Multiple h1 elements on same page
      - Generic or meaningless heading text
      - Missing headings for major content sections
      - Improper heading structure for clickable elements
      - Using heading markup for non-heading content
      - Missing aria-level on role="heading" elements

metadata:
  priority: high
  version: 1.0
</rule>