Cursor rule

1---
2description: Landmark element accessibility compliance and WCAG 2.4.1 Bypass Blocks requirements
3globs: *.vue, *.jsx, *.tsx, *.html, *.php, *.js, *.ts, *.liquid
4alwaysApply: true
5---
6# Landmark Element Accessibility Standards
7 
8Ensures landmark elements follow WCAG compliance and provide proper content structure for screen reader navigation and bypass blocks functionality.
9 
10<rule>
11name: landmark_accessibility_standards
12description: Enforce landmark 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      # Multiple instances of single-instance landmarks
21      - pattern: "(?i)<(header|banner)[^>]*>.*<(header|banner)[^>]*>"
22        message: "Page should not contain more than one instance of header/banner landmark."
23 
24      - pattern: "(?i)<main[^>]*>.*<main[^>]*>"
25        message: "Page should not contain more than one instance of main landmark."
26 
27      - pattern: "(?i)<(footer|contentinfo)[^>]*>.*<(footer|contentinfo)[^>]*>"
28        message: "Page should not contain more than one instance of footer/contentinfo landmark."
29 
30      # Missing distinguishable names for multiple landmarks of same type
31      - pattern: "(?i)<nav[^>]*>.*<nav[^>]*>"
32        pattern_negate: "(aria-label|aria-labelledby)"
33        message: "Multiple navigation landmarks should have distinguishable names using aria-label or aria-labelledby."
34 
35      - pattern: "(?i)<(section|region)[^>]*>.*<(section|region)[^>]*>"
36        pattern_negate: "(aria-label|aria-labelledby)"
37        message: "Multiple section/region landmarks should have distinguishable names using aria-label or aria-labelledby."
38 
39      - pattern: "(?i)<(aside|complementary)[^>]*>.*<(aside|complementary)[^>]*>"
40        pattern_negate: "(aria-label|aria-labelledby)"
41        message: "Multiple aside/complementary landmarks should have distinguishable names using aria-label or aria-labelledby."
42 
43      # Content outside landmarks
44      - pattern: "(?i)<body[^>]*>"
45        pattern_negate: "(<header|<nav|<main|<aside|<section|<footer|<banner|<navigation|<complementary|<contentinfo|<region)"
46        message: "All content should be contained within landmark regions."
47 
48      # Excessive number of landmarks (more than 8-10)
49      - pattern: "(?i)(<header|<nav|<main|<aside|<section|<footer|<banner|<navigation|<complementary|<contentinfo|<region)"
50        pattern_negate: "(aria-label|aria-labelledby)"
51        message: "Consider reducing the number of landmarks to minimize navigation complexity."
52 
53      # Missing main landmark
54      - pattern: "(?i)<body[^>]*>"
55        pattern_negate: "<main[^>]*>"
56        message: "Page should contain a main landmark for primary content."
57 
58      # Landmark without proper role or semantic element
59      - pattern: "(?i)role=\"(banner|navigation|main|complementary|contentinfo|region)\""
60        pattern_negate: "(<header|<nav|<main|<aside|<section|<footer)"
61        message: "Landmark roles should be used with semantic HTML elements when possible."
62 
63      # Nested landmarks of same type
64      - pattern: "(?i)<nav[^>]*>.*<nav[^>]*>.*</nav>.*</nav>"
65        message: "Avoid nesting landmarks of the same type."
66 
67      - pattern: "(?i)<section[^>]*>.*<section[^>]*>.*</section>.*</section>"
68        message: "Avoid nesting landmarks of the same type."
69 
70      # Landmark without accessible name
71      - pattern: "(?i)<(section|region|aside|complementary)[^>]*>"
72        pattern_negate: "(aria-label|aria-labelledby|<h[1-6])"
73        message: "Landmarks should have accessible names via aria-label, aria-labelledby, or heading elements."
74 
75      # Generic landmark names
76      - pattern: "(?i)aria-label=\"(section|region|content|area)\""
77        message: "Landmark names should be specific and descriptive, not generic."
78 
79      # Landmark with empty or meaningless name
80      - pattern: "(?i)aria-label=\"\\s*\""
81        message: "Landmark aria-label should contain meaningful text."
82 
83  - type: suggest
84    message: |
85      **WCAG 2.4.1 Landmark Accessibility Requirements:**
86 
87      **Bypass Blocks Functionality:**
88      - **Screen Reader Navigation:** Landmarks allow users to navigate by page sections
89      - **Content Structure:** Landmarks provide clear layout organization
90      - **Alternative Methods:** Skip links, headings, and expand/collapse regions can also be used
91 
92      **Landmark Structural Organization:**
93 
94      **1. Page Layout Groupings:**
95```html
96      <!-- Good: Proper page structure with landmarks -->
97      <body>
98        <header role="banner">
99          <h1>Company Name</h1>
100          <nav role="navigation" aria-label="Primary">
101            <ul>
102              <li><a href="/">Home</a></li>
103              <li><a href="/about">About</a></li>
104            </ul>
105          </nav>
106        </header>
107 
108        <main role="main">
109          <h2>Page Content</h2>
110          <p>Main content goes here...</p>
111        </main>
112 
113        <aside role="complementary" aria-label="Related information">
114          <h3>Related Links</h3>
115          <ul>
116            <li><a href="/related">Related Content</a></li>
117          </ul>
118        </aside>
119 
120        <footer role="contentinfo">
121          <p>&copy; 2024 Company Name</p>
122        </footer>
123      </body>
124```
125 
126      **2. Content Within Landmarks:**
127```html
128      <!-- Good: All content within landmarks -->
129      <body>
130        <header>
131          <h1>Page Title</h1>
132          <nav aria-label="Main navigation">
133            <!-- Navigation content -->
134          </nav>
135        </header>
136 
137        <main>
138          <section aria-labelledby="intro-heading">
139            <h2 id="intro-heading">Introduction</h2>
140            <p>Content here...</p>
141          </section>
142 
143          <section aria-labelledby="details-heading">
144            <h2 id="details-heading">Details</h2>
145            <p>More content...</p>
146          </section>
147        </main>
148 
149        <footer>
150          <p>Footer content</p>
151        </footer>
152      </body>
153```
154 
155      **3. Landmark Names for Multiple Instances:**
156```html
157      <!-- Good: Distinguishable landmark names -->
158      <nav aria-label="Primary navigation">
159        <ul>
160          <li><a href="/">Home</a></li>
161          <li><a href="/about">About</a></li>
162        </ul>
163      </nav>
164 
165      <nav aria-label="Secondary navigation">
166        <ul>
167          <li><a href="/help">Help</a></li>
168          <li><a href="/contact">Contact</a></li>
169        </ul>
170      </nav>
171 
172      <aside aria-label="Product sidebar">
173        <h3>Product Categories</h3>
174        <!-- Sidebar content -->
175      </aside>
176 
177      <aside aria-label="News sidebar">
178        <h3>Latest News</h3>
179        <!-- News content -->
180      </aside>
181```
182 
183      **4. Single Instance Landmarks:**
184```html
185      <!-- Good: One instance of each single-instance landmark -->
186      <body>
187        <header role="banner">
188          <!-- Header content -->
189        </header>
190 
191        <main role="main">
192          <!-- Main content -->
193        </main>
194 
195        <footer role="contentinfo">
196          <!-- Footer content -->
197        </footer>
198      </body>
199```
200 
201      **5. Landmark Markup Options:**
202```html
203      <!-- Option 1: Semantic HTML elements -->
204      <header role="banner">
205        <h1>Page Title</h1>
206      </header>
207 
208      <nav role="navigation" aria-label="Main menu">
209        <ul>
210          <li><a href="/">Home</a></li>
211        </ul>
212      </nav>
213 
214      <main role="main">
215        <h2>Content</h2>
216      </main>
217 
218      <footer role="contentinfo">
219        <p>Footer</p>
220      </footer>
221 
222      <!-- Option 2: ARIA roles on div elements -->
223      <div role="banner">
224        <h1>Page Title</h1>
225      </div>
226 
227      <div role="navigation" aria-label="Main menu">
228        <ul>
229          <li><a href="/">Home</a></li>
230        </ul>
231      </div>
232 
233      <div role="main">
234        <h2>Content</h2>
235      </div>
236 
237      <div role="contentinfo">
238        <p>Footer</p>
239      </div>
240```
241 
242      **Landmark Guidelines:**
243 
244      **Available Landmarks:**
245      - **banner:** Page header (usually one per page)
246      - **navigation:** Navigation menus (can have multiple with different names)
247      - **main:** Main content area (one per page)
248      - **complementary:** Supporting content (sidebars, related info)
249      - **contentinfo:** Page footer (usually one per page)
250      - **region:** Generic landmark for page sections
251      - **search:** Search functionality
252      - **form:** Form sections
253 
254      **Naming Requirements:**
255      - **Multiple instances:** Must have distinguishable names
256      - **Descriptive names:** Use aria-label or aria-labelledby
257      - **Specific names:** Avoid generic terms like "section" or "content"
258      - **Meaningful names:** Describe the purpose or content
259 
260      **Implementation Best Practices:**
261 
262      **Page Structure Example:**
263```html
264      <body>
265        <!-- Header landmark -->
266        <header role="banner">
267          <h1>Acme Corporation</h1>
268          <nav role="navigation" aria-label="Primary">
269            <ul>
270              <li><a href="/">Home</a></li>
271              <li><a href="/products">Products</a></li>
272              <li><a href="/about">About</a></li>
273              <li><a href="/contact">Contact</a></li>
274            </ul>
275          </nav>
276        </header>
277 
278        <!-- Main content landmark -->
279        <main role="main">
280          <h2>Welcome to Acme Corporation</h2>
281 
282          <!-- Content sections -->
283          <section aria-labelledby="services-heading">
284            <h2 id="services-heading">Our Services</h2>
285            <p>Service descriptions...</p>
286          </section>
287 
288          <section aria-labelledby="products-heading">
289            <h2 id="products-heading">Featured Products</h2>
290            <p>Product information...</p>
291          </section>
292        </main>
293 
294        <!-- Complementary landmark -->
295        <aside role="complementary" aria-label="Related information">
296          <h3>Quick Links</h3>
297          <ul>
298            <li><a href="/support">Support</a></li>
299            <li><a href="/faq">FAQ</a></li>
300          </ul>
301        </aside>
302 
303        <!-- Footer landmark -->
304        <footer role="contentinfo">
305          <p>&copy; 2024 Acme Corporation. All rights reserved.</p>
306          <nav role="navigation" aria-label="Footer">
307            <ul>
308              <li><a href="/privacy">Privacy Policy</a></li>
309              <li><a href="/terms">Terms of Service</a></li>
310            </ul>
311          </nav>
312        </footer>
313      </body>
314```
315 
316      **Multiple Navigation Landmarks:**
317```html
318      <!-- Primary navigation -->
319      <nav role="navigation" aria-label="Primary">
320        <ul>
321          <li><a href="/">Home</a></li>
322          <li><a href="/products">Products</a></li>
323          <li><a href="/services">Services</a></li>
324        </ul>
325      </nav>
326 
327      <!-- Secondary navigation -->
328      <nav role="navigation" aria-label="Secondary">
329        <ul>
330          <li><a href="/help">Help</a></li>
331          <li><a href="/contact">Contact</a></li>
332          <li><a href="/about">About</a></li>
333        </ul>
334      </nav>
335 
336      <!-- Footer navigation -->
337      <nav role="navigation" aria-label="Footer">
338        <ul>
339          <li><a href="/privacy">Privacy</a></li>
340          <li><a href="/terms">Terms</a></li>
341        </ul>
342      </nav>
343```
344 
345      **Landmark with Accessible Names:**
346```html
347      <!-- Using aria-label -->
348      <section role="region" aria-label="Product specifications">
349        <h2>Product Specifications</h2>
350        <p>Detailed specifications...</p>
351      </section>
352 
353      <!-- Using aria-labelledby -->
354      <section role="region" aria-labelledby="reviews-heading">
355        <h2 id="reviews-heading">Customer Reviews</h2>
356        <p>Review content...</p>
357      </section>
358 
359      <!-- Using heading element -->
360      <section role="region">
361        <h2>Product Features</h2>
362        <p>Feature descriptions...</p>
363      </section>
364```
365 
366      **Testing and Validation:**
367      - Test with screen reader landmark navigation
368      - Verify landmark names are descriptive and unique
369      - Check that all content is within landmarks
370      - Ensure single-instance landmarks appear only once
371      - Test keyboard navigation between landmarks
372      - Validate landmark hierarchy is logical
373 
374      **Common Mistakes to Avoid:**
375      - Multiple instances of single-instance landmarks
376      - Missing accessible names for multiple landmarks
377      - Content outside landmark regions
378      - Excessive number of landmarks
379      - Generic or meaningless landmark names
380      - Nested landmarks of same type
381      - Missing main landmark
382      - Using landmarks for styling only
383 
384metadata:
385  priority: high
386  version: 1.0
387</rule>
388