Cursor rule

1---
2description: Heading element accessibility compliance and WCAG 2.4.1 Bypass Blocks requirements
3globs: *.vue, *.jsx, *.tsx, *.html, *.php, *.js, *.ts, *.liquid
4alwaysApply: true
5---
6# Heading Element Accessibility Standards
7 
8Ensures heading elements follow WCAG compliance and provide proper content structure for screen reader navigation and bypass blocks functionality.
9 
10<rule>
11name: heading_accessibility_standards
12description: Enforce heading element accessibility standards per WCAG 2.4.1 Bypass Blocks requirements
13filters:
14  - type: file_extension
15    pattern: "\\.(vue|jsx|tsx|html|liquid|php|js|ts)$"
16 
17actions:
18  - type: enforce
19    conditions:
20      # Missing heading markup for visually styled headings
21      - pattern: "(?i)<(div|span|p)[^>]*(?:heading|title|header)[^>]*>"
22        pattern_negate: "(role=\"heading\"|h[1-6])"
23        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."
24 
25      # Heading markup on non-heading content
26      - pattern: "(?i)<(h[1-6]|div[^>]*role=\"heading\")[^>]*>"
27        pattern_negate: "(heading|title|header|section|main|content|page)"
28        message: "Text that does not act as a heading visually or structurally should not be marked as a heading."
29 
30      # Missing aria-level on role="heading"
31      - pattern: "(?i)<[^>]*role=\"heading\"[^>]*>"
32        pattern_negate: "aria-level=\"[1-6]\""
33        message: "Elements with role='heading' must have aria-level attribute set to appropriate level (1-6)."
34 
35      # Invalid aria-level values
36      - pattern: "(?i)aria-level=\"[^1-6]\""
37        message: "aria-level must be set to a value between 1 and 6 for heading elements."
38 
39      # Missing h1 in main content
40      - pattern: "(?i)<main[^>]*>"
41        pattern_negate: "<h1[^>]*>"
42        message: "Main content should start with an h1 heading for proper document structure."
43 
44      # Multiple h1 elements (potential issue)
45      - pattern: "(?i)<h1[^>]*>.*<h1[^>]*>"
46        message: "Most web pages should have only one h1 element. Consider using h2-h6 for section headings."
47 
48      # Skipped heading levels
49      - pattern: "(?i)<h1[^>]*>.*<h3[^>]*>"
50        message: "Headings should not skip hierarchical levels. Consider using h2 before h3."
51 
52      - pattern: "(?i)<h2[^>]*>.*<h4[^>]*>"
53        message: "Headings should not skip hierarchical levels. Consider using h3 before h4."
54 
55      # Clickable headings with improper structure
56      - pattern: "(?i)<a[^>]*>.*<h[1-6][^>]*>.*</h[1-6]>.*</a>"
57        message: "Heading elements should not be children of link elements. The heading should wrap the link to maintain semantic structure."
58 
59      # Empty or meaningless heading text
60      - pattern: "(?i)<h[1-6][^>]*>\\s*(?:&nbsp;|\\s|&amp;nbsp;)*</h[1-6]>"
61        message: "Heading elements should contain meaningful text content."
62 
63      # Generic heading text
64      - pattern: "(?i)<h[1-6][^>]*>\\s*(?:heading|title|header|section)\\s*</h[1-6]>"
65        message: "Heading text should be specific and informative, not generic."
66 
67      # Heading text too long
68      - pattern: "(?i)<h[1-6][^>]*>[^<]{100,}</h[1-6]>"
69        message: "Heading text should be concise and relatively brief."
70 
71      # Missing heading for major content sections
72      - pattern: "(?i)<(section|article|main)[^>]*>"
73        pattern_negate: "<h[1-6][^>]*>"
74        message: "Major content sections should have appropriate heading elements for navigation."
75 
76  - type: suggest
77    message: |
78      **WCAG 2.4.1 Heading Accessibility Requirements:**
79 
80      **Bypass Blocks Functionality:**
81      - **Screen Reader Navigation:** Headings allow users to navigate by content sections
82      - **Content Structure:** Headings provide clear outline of page content
83      - **Landmark Support:** Headings work with landmarks and skip links for navigation
84 
85      **Heading Markup Requirements:**
86 
87      **1. Use Real Heading Elements:**
88```html
89      <!-- Good: Proper heading markup -->
90      <h1>Main Page Title</h1>
91      <h2>Section Heading</h2>
92      <h3>Subsection Heading</h3>
93 
94      <!-- Good: Role heading when real markup not possible -->
95      <div role="heading" aria-level="1">Main Page Title</div>
96      <div role="heading" aria-level="2">Section Heading</div>
97```
98 
99      **2. Proper Heading Hierarchy:**
100```html
101      <!-- Good: Logical heading structure -->
102      <h1>Product Catalog</h1>
103      <h2>Electronics</h2>
104      <h3>Smartphones</h3>
105      <h3>Laptops</h3>
106      <h2>Clothing</h2>
107      <h3>Men's Clothing</h3>
108      <h3>Women's Clothing</h3>
109 
110      <!-- Bad: Skipped levels -->
111      <h1>Product Catalog</h1>
112      <h3>Electronics</h3> <!-- Skipped h2 -->
113```
114 
115      **3. Clickable Headings:**
116```html
117      <!-- Good: Heading wraps the link -->
118      <h2><a href="/products/electronics">Electronics</a></h2>
119 
120      <!-- Bad: Heading as child of link -->
121      <a href="/products/electronics">
122        <h2>Electronics</h2>
123      </a>
124```
125 
126      **4. Meaningful Heading Text:**
127```html
128      <!-- Good: Specific and informative -->
129      <h1>Acme Corporation - Leading Tech Solutions</h1>
130      <h2>Our Services</h2>
131      <h3>Web Development</h3>
132      <h3>Mobile App Development</h3>
133 
134      <!-- Bad: Generic or meaningless -->
135      <h1>Welcome</h1>
136      <h2>Section</h2>
137      <h3>Content</h3>
138```
139 
140      **5. Single H1 Per Page:**
141```html
142      <!-- Good: One main heading -->
143      <h1>Company Homepage</h1>
144      <h2>About Us</h2>
145      <h2>Our Services</h2>
146      <h2>Contact</h2>
147 
148      <!-- Bad: Multiple h1 elements -->
149      <h1>Company Homepage</h1>
150      <h1>About Us</h1> <!-- Should be h2 -->
151```
152 
153      **6. Proper Content Structure:**
154```html
155      <!-- Good: Clear content outline -->
156      <main>
157        <h1>Product Documentation</h1>
158        <section>
159          <h2>Installation Guide</h2>
160          <h3>System Requirements</h3>
161          <h3>Installation Steps</h3>
162        </section>
163        <section>
164          <h2>User Manual</h2>
165          <h3>Getting Started</h3>
166          <h3>Advanced Features</h3>
167        </section>
168      </main>
169```
170 
171      **7. Role Heading Implementation:**
172```html
173      <!-- When real heading elements cannot be used -->
174      <div role="heading" aria-level="1">Main Page Title</div>
175      <div role="heading" aria-level="2">Section Heading</div>
176      <div role="heading" aria-level="3">Subsection Heading</div>
177 
178      <!-- With proper aria-level values -->
179      <div role="heading" aria-level="1">Company Overview</div>
180      <div role="heading" aria-level="2">Our Mission</div>
181      <div role="heading" aria-level="2">Our Values</div>
182```
183 
184      **Heading Guidelines:**
185 
186      **Content Structure:**
187      - **H1:** Main page title or primary content heading
188      - **H2:** Major section headings
189      - **H3:** Subsection headings
190      - **H4-H6:** Further subdivisions as needed
191 
192      **Text Requirements:**
193      - **Concise:** Keep heading text brief and to the point
194      - **Descriptive:** Accurately describe the content that follows
195      - **Unique:** Each heading should be distinct and meaningful
196      - **Hierarchical:** Follow logical content structure
197 
198      **Navigation Benefits:**
199      - **Screen Reader Users:** Can jump between sections using heading navigation
200      - **Keyboard Users:** Can navigate page structure efficiently
201      - **All Users:** Clear content organization and hierarchy
202 
203      **Implementation Best Practices:**
204 
205      **Page Structure Example:**
206```html
207      <header>
208        <nav>
209          <!-- Navigation content -->
210        </nav>
211      </header>
212 
213      <main>
214        <h1>Product Documentation</h1>
215 
216        <section>
217          <h2>Getting Started</h2>
218          <h3>Installation</h3>
219          <h3>Configuration</h3>
220        </section>
221 
222        <section>
223          <h2>User Guide</h2>
224          <h3>Basic Features</h3>
225          <h3>Advanced Features</h3>
226          <h4>Customization</h4>
227          <h4>Integration</h4>
228        </section>
229 
230        <section>
231          <h2>Troubleshooting</h2>
232          <h3>Common Issues</h3>
233          <h3>Support</h3>
234        </section>
235      </main>
236```
237 
238      **Dynamic Content:**
239```html
240      <!-- Good: Proper heading for dynamic content -->
241      <h2>Search Results</h2>
242      <p>Found 15 results for "accessibility"</p>
243 
244      <!-- Good: Descriptive heading for filtered content -->
245      <h2>Electronics (25 items)</h2>
246      <p>Showing 1-10 of 25 products</p>
247```
248 
249      **Form Sections:**
250```html
251      <!-- Good: Clear form structure with headings -->
252      <h2>Contact Information</h2>
253      <form>
254        <label for="name">Name:</label>
255        <input type="text" id="name">
256 
257        <label for="email">Email:</label>
258        <input type="email" id="email">
259      </form>
260 
261      <h2>Shipping Address</h2>
262      <form>
263        <label for="address">Address:</label>
264        <input type="text" id="address">
265      </form>
266```
267 
268      **Testing and Validation:**
269      - Test with screen reader heading navigation
270      - Verify heading hierarchy is logical
271      - Check that heading text is descriptive
272      - Ensure no skipped heading levels
273      - Validate single h1 per page
274      - Test keyboard navigation between headings
275 
276      **Common Mistakes to Avoid:**
277      - Using heading elements for styling only
278      - Skipping heading levels (h1 → h3)
279      - Multiple h1 elements on same page
280      - Generic or meaningless heading text
281      - Missing headings for major content sections
282      - Improper heading structure for clickable elements
283      - Using heading markup for non-heading content
284      - Missing aria-level on role="heading" elements
285 
286metadata:
287  priority: high
288  version: 1.0
289</rule>
290