Cursor rule

1---
2description: Dropdown Navigation component accessibility compliance pattern
3globs: *.vue, *.jsx, *.tsx, *.html, *.php, *.js, *.ts, *.liquid
4alwaysApply: false
5---
6# Dropdown Navigation Component Accessibility Standards
7 
8Ensures dropdown navigation components follow WCAG compliance and proper navigation semantics, including mobile modal patterns and disclosure controls.
9 
10<rule>
11name: dropdown_navigation_accessibility_standards
12description: Enforce dropdown navigation component accessibility standards and proper navigation semantics
13filters:
14  - type: file_extension
15    pattern: "\\.(vue|jsx|tsx|html|liquid|php|js|ts)$"
16 
17actions:
18  - type: enforce
19    conditions:
20      # Navigation landmark requirement
21      - pattern: "(?i)<nav[^>]*(?:navigation|menu|dropdown)[^>]*>"
22        pattern_negate: "(aria-label|aria-labelledby)=\"[^\"]+\""
23        message: "Navigation elements must have aria-label or aria-labelledby attribute for accessibility."
24 
25      # Navigation list structure requirement
26      - pattern: "(?i)<nav[^>]*(?:navigation|menu|dropdown)[^>]*>"
27        pattern_negate: "<ul[^>]*>"
28        message: "Navigation should use unordered list (ul) for proper semantic structure."
29 
30      # Dropdown button role requirement
31      - pattern: "(?i)<(button|div|span)[^>]*(?:dropdown|expand|collapse)[^>]*>"
32        pattern_negate: "role=\"button\""
33        message: "Dropdown controls must have role='button' (or use native button element which has implicit role)."
34 
35      # Dropdown button aria-expanded requirement
36      - pattern: "(?i)<[^>]*role=\"button\"[^>]*(?:dropdown|expand|collapse)[^>]*>"
37        pattern_negate: "aria-expanded=\"(true|false)\""
38        message: "Dropdown controls must have aria-expanded attribute set to 'true' or 'false'."
39 
40      # Dropdown content missing proper identification
41      - pattern: "(?i)<(div|section)[^>]*(?:dropdown.*content|content.*dropdown)[^>]*>"
42        pattern_negate: "id=\"[^\"]+\""
43        message: "Dropdown content must have unique ID attributes for aria-controls reference."
44 
45      # Missing aria-current on navigation items
46      - pattern: "(?i)<a[^>]*(?:nav|navigation)[^>]*>"
47        pattern_negate: "aria-current=\"(page|false)\""
48        message: "Navigation links should have aria-current attribute set to 'page' for active items or 'false' for inactive."
49 
50      # Mobile modal missing dialog role
51      - pattern: "(?i)<(div|section)[^>]*(?:mobile.*nav|nav.*mobile|modal.*nav)[^>]*>"
52        pattern_negate: "role=\"dialog\""
53        message: "Mobile navigation modal containers must have role='dialog' attribute."
54 
55      # Mobile modal missing aria-modal
56      - pattern: "(?i)<[^>]*role=\"dialog\"[^>]*(?:mobile.*nav|nav.*mobile)[^>]*>"
57        pattern_negate: "aria-modal=\"true\""
58        message: "Mobile navigation dialog elements must have aria-modal='true' attribute."
59 
60      # Mobile modal missing proper labeling
61      - pattern: "(?i)<[^>]*role=\"dialog\"[^>]*(?:mobile.*nav|nav.*mobile)[^>]*>"
62        pattern_negate: "(aria-labelledby|aria-label)"
63        message: "Mobile navigation dialog elements must have either aria-labelledby or aria-label for accessibility."
64 
65      # Mobile launcher missing aria-haspopup
66      - pattern: "(?i)<button[^>]*(?:mobile.*nav|nav.*mobile|hamburger|menu)[^>]*>"
67        pattern_negate: "aria-haspopup=\"dialog\""
68        message: "Mobile navigation launcher buttons must include aria-haspopup='dialog' to inform users a dialog will open."
69 
70      # Mobile close button missing aria-label
71      - pattern: "(?i)<button[^>]*(?:close|dismiss|×|&times;)[^>]*(?:mobile.*nav|nav.*mobile)[^>]*>"
72        pattern_negate: "aria-label=\"[^\"]*[Cc]lose[^\"]*\""
73        message: "Mobile navigation close buttons should have aria-label='Close navigation' or similar descriptive text."
74 
75      # Missing keyboard event handlers for dropdown
76      - pattern: "(?i)<[^>]*role=\"button\"[^>]*(?:dropdown|expand|collapse)[^>]*>"
77        pattern_negate: "(onKeyDown|onkeydown|@keydown|v-on:keydown)"
78        message: "Dropdown controls should handle keyboard events (Enter, Space, and Escape)."
79 
80      # Missing Escape key support for dropdown content
81      - pattern: "(?i)<div[^>]*(?:dropdown.*content|content.*dropdown)[^>]*>"
82        pattern_negate: "(onKeyDown|onkeydown|@keydown|v-on:keydown)"
83        message: "Dropdown content areas should handle Escape key to close dropdown and return focus to launcher."
84 
85      # Incorrect menu role usage
86      - pattern: "(?i)role=\"(menu|menuitem|menubar|menuitemcheckbox|menuitemradio)\""
87        message: "Navigation components should NOT use menu roles. Use proper navigation semantics with ul/li/a elements."
88 
89      # Incorrect aria-haspopup usage
90      - pattern: "(?i)aria-haspopup=\"(true|menu|listbox)\""
91        pattern_negate: "aria-haspopup=\"dialog\""
92        message: "Navigation components should NOT use aria-haspopup except for mobile modal launchers with aria-haspopup='dialog'."
93 
94  - type: suggest
95    message: |
96      **Dropdown Navigation Component Accessibility Best Practices:**
97 
98      **Navigation Semantics:**
99      - **role='navigation':** Implicit on nav element, provides landmark
100      - **aria-label/aria-labelledby:** On nav element to describe the navigation
101      - **aria-current:** Set on active navigation items ('page' for current page, 'false' for inactive)
102      - **ul + li + a:** Use semantic list structure for navigation items
103      - **NO menu roles:** Do not use role="menu", role="menuitem", etc.
104 
105      **Dropdown Disclosure Pattern:**
106      - **role='button':** Set on dropdown launcher elements (or use native button)
107      - **aria-expanded:** 'true' if dropdown content is visible, 'false' if hidden
108      - **aria-controls:** Reference to the ID of the associated dropdown content
109      - **aria-current:** Set on active dropdown items
110 
111      **Mobile Modal Pattern:**
112      - **role='dialog':** Set on mobile navigation modal container
113      - **aria-modal='true':** Indicates the dialog is modal
114      - **aria-labelledby/aria-label:** On mobile dialog for accessibility
115      - **aria-haspopup='dialog':** Set on mobile launcher button
116      - **aria-label:** Set on mobile close button
117 
118      **Keyboard Interaction Requirements:**
119      - **Tab:** Move through natural tab order on page
120      - **Enter:** Activate links
121      - **Space/Enter:** Open/close dropdown when launcher is focused
122      - **Escape:** Close dropdown component (launcher focused or not)
123      - **NO auto-open:** Do not open dropdown on keyboard focus
124      - **Mobile:** Focus management for modal open/close
125 
126      **Mouse Interaction Requirements:**
127      - **Hover:** Show underline on links
128      - **Hover:** Open dropdown, close on mouse-away
129      - **Click:** Activate links (include mouse-specific click handlers)
130      - **Mobile:** Click launcher opens modal, click close button closes modal
131      - **Double-click:** Mobile dropdown launchers navigate to associated page
132 
133      **Mobile Interaction Requirements:**
134      - **Three-line button:** Opens modal, focus moves to first focusable item
135      - **X close button:** Closes modal, focus returns to launcher
136      - **Dropdown launcher:** Reveals content section, single-click toggles, double-click navigates
137      - **Focus management:** Proper focus trapping and restoration
138 
139      **Implementation Patterns:**
140 
141      **Desktop Navigation Structure:**
142```html
143      <header>
144        <nav aria-label="Main navigation">
145          <ul>
146            <li>
147              <a href="/home" aria-current="page">Home</a>
148            </li>
149            <li>
150              <button type="button"
151                      role="button"
152                      aria-expanded="false"
153                      aria-controls="products-dropdown">
154                Products
155                <span class="chevron">▼</span>
156              </button>
157              <div id="products-dropdown" hidden>
158                <ul>
159                  <li><a href="/products/category1">Category 1</a></li>
160                  <li><a href="/products/category2">Category 2</a></li>
161                </ul>
162              </div>
163            </li>
164            <li>
165              <a href="/about" aria-current="false">About</a>
166            </li>
167          </ul>
168        </nav>
169      </header>
170```
171 
172      **Mobile Navigation Structure:**
173```html
174      <header>
175        <button type="button"
176                aria-haspopup="dialog"
177                aria-label="Open navigation menu"
178                onclick="openMobileNav()">
179          <span class="hamburger">☰</span>
180        </button>
181      </header>
182 
183      <div role="dialog"
184           aria-modal="true"
185           aria-labelledby="mobile-nav-title"
186           class="mobile-nav-modal"
187           hidden>
188        <button type="button"
189                aria-label="Close navigation menu"
190                onclick="closeMobileNav()">
191          ×
192        </button>
193        <h2 id="mobile-nav-title">Navigation</h2>
194        <nav aria-label="Mobile navigation">
195          <ul>
196            <li>
197              <a href="/home" aria-current="page">Home</a>
198            </li>
199            <li>
200              <button type="button"
201                      role="button"
202                      aria-expanded="false"
203                      aria-controls="mobile-products-dropdown"
204                      data-href="/products">
205                Products
206                <span class="chevron">▼</span>
207              </button>
208              <div id="mobile-products-dropdown" hidden>
209                <ul>
210                  <li><a href="/products/category1">Category 1</a></li>
211                  <li><a href="/products/category2">Category 2</a></li>
212                </ul>
213              </div>
214            </li>
215            <li>
216              <a href="/about" aria-current="false">About</a>
217            </li>
218          </ul>
219        </nav>
220      </div>
221```
222 
223      **JavaScript for Dropdown Toggle:**
224```javascript
225      function toggleDropdown(button) {
226        const isExpanded = button.getAttribute('aria-expanded') === 'true';
227        const content = document.getElementById(button.getAttribute('aria-controls'));
228 
229        button.setAttribute('aria-expanded', !isExpanded);
230        content.hidden = isExpanded;
231 
232        // Update chevron icon
233        const chevron = button.querySelector('.chevron');
234        if (chevron) {
235          chevron.textContent = isExpanded ? '▼' : '▲';
236        }
237 
238        if (!isExpanded) {
239          // Add escape key listener to content
240          content.addEventListener('keydown', handleDropdownEscapeKey);
241        } else {
242          // Remove escape key listener
243          content.removeEventListener('keydown', handleDropdownEscapeKey);
244        }
245      }
246 
247      function handleDropdownEscapeKey(event) {
248        if (event.key === 'Escape') {
249          const content = event.target.closest('[hidden]');
250          if (content) {
251            const button = document.querySelector(`[aria-controls="${content.id}"]`);
252            if (button) {
253              button.setAttribute('aria-expanded', 'false');
254              content.hidden = true;
255              button.focus(); // Return focus to launcher
256              content.removeEventListener('keydown', handleDropdownEscapeKey);
257            }
258          }
259        }
260      }
261```
262 
263      **JavaScript for Mobile Modal:**
264```javascript
265      function openMobileNav() {
266        const modal = document.querySelector('.mobile-nav-modal');
267        const closeButton = modal.querySelector('button[aria-label*="Close"]');
268 
269        modal.hidden = false;
270        closeButton.focus(); // Focus first focusable element
271      }
272 
273      function closeMobileNav() {
274        const modal = document.querySelector('.mobile-nav-modal');
275        const launcher = document.querySelector('[aria-haspopup="dialog"]');
276 
277        modal.hidden = true;
278        launcher.focus(); // Return focus to launcher
279      }
280 
281      // Handle escape key for mobile modal
282      document.addEventListener('keydown', function(event) {
283        if (event.key === 'Escape') {
284          const modal = document.querySelector('.mobile-nav-modal');
285          if (!modal.hidden) {
286            closeMobileNav();
287          }
288        }
289      });
290 
291      // Mobile dropdown click and double-click handlers
292      document.addEventListener('DOMContentLoaded', function() {
293        const mobileDropdownButtons = document.querySelectorAll('.mobile-dropdown-button');
294 
295        mobileDropdownButtons.forEach(button => {
296          // Single click toggles dropdown
297          button.addEventListener('click', (event) => {
298            event.preventDefault();
299            toggleDropdown(button);
300          });
301 
302          // Double click navigates to page
303          button.addEventListener('dblclick', (event) => {
304            event.preventDefault();
305            const href = button.getAttribute('data-href') || '/default';
306            window.location.href = href;
307          });
308        });
309      });
310```
311 
312      **CSS for Hover Interactions:**
313```css
314      /* Link hover underline */
315      nav a:hover {
316        text-decoration: underline;
317      }
318 
319      /* Dropdown hover behavior */
320      .dropdown-launcher:hover + .dropdown-content,
321      .dropdown-content:hover {
322        display: block;
323      }
324 
325      .dropdown-content {
326        display: none;
327      }
328 
329      /* Chevron rotation */
330      .chevron {
331        transition: transform 0.2s ease;
332      }
333 
334      button[aria-expanded="true"] .chevron {
335        transform: rotate(180deg);
336      }
337```
338 
339      **JavaScript Considerations:**
340      - Implement proper event listeners for all keyboard interactions
341      - Handle mouse hover events for dropdown display
342      - Manage focus for mobile modal open/close
343      - Update aria-current states based on current page
344      - Handle chevron icon rotation
345      - Implement proper escape key handling
346      - Ensure no auto-opening on keyboard focus
347      - Handle mouse-specific click events for navigation
348      - Implement double-click navigation for mobile dropdown launchers
349 
350      **Accessibility Notes:**
351      - Navigation is NOT a menu - use proper navigation semantics
352      - Avoid menu roles and aria-haspopup (except mobile modal)
353      - Ensure proper focus management for mobile modal
354      - Test with screen readers for proper announcement
355      - Maintain clear visual indicators for active states
356      - Consider implementing skip links for large navigation
357      - Ensure sufficient color contrast for all navigation elements
358      - Test keyboard navigation flow thoroughly
359 
360      **Testing Requirements:**
361      - Test keyboard navigation through all navigation items
362      - Verify dropdown opens/closes with keyboard and mouse
363      - Test mobile modal focus management
364      - Verify screen reader announcement of navigation structure
365      - Test aria-current updates correctly
366      - Ensure escape key closes dropdowns and modals
367      - Test hover interactions work as expected
368      - Verify no auto-opening on keyboard focus
369 
370metadata:
371  priority: high
372  version: 1.0
373</rule>
374description:
375globs:
376alwaysApply: false
377---
378description:
379globs:
380alwaysApply: false
381---
382