Cursor rule

1---
2description: Accordion component accessibility compliance and WAI-ARIA Accordion Pattern
3globs: *.vue, *.jsx, *.tsx, *.html, *.php, *.js, *.ts, *.liquid
4alwaysApply: false
5---
6 
7# Accordion Component Accessibility Standards
8 
9Ensures accordion components follow WCAG compliance and WAI-ARIA Accordion Pattern specifications.
10 
11<rule>
12name: accordion_accessibility_standards
13description: Enforce accordion component accessibility standards and WAI-ARIA Accordion Pattern compliance
14filters:
15  - type: file_extension
16    pattern: "\\.(vue|jsx|tsx|html|liquid|php|js|ts)$"
17 
18actions:
19 
20- type: enforce
21  conditions:
22 
23  # Accordion header button role requirement
24 
25  - pattern: "(?i)<button[^>]_(?:accordion|expand|collapse)[^>]_>"
26    pattern_negate: "role=\"button\""
27    message: "Accordion header buttons should have role='button' (or use native button element which has implicit role)."
28 
29  # Accordion header missing aria-expanded
30 
31  - pattern: "(?i)<button[^>]_(?:accordion|expand|collapse)[^>]_>"
32    pattern_negate: "aria-expanded=\"(true|false)\""
33    message: "Accordion header buttons must have aria-expanded attribute set to 'true' or 'false'."
34 
35  # Accordion header missing aria-controls
36 
37  - pattern: "(?i)<button[^>]_(?:accordion|expand|collapse)[^>]_>"
38    pattern_negate: "aria-controls=\"[^\"]+\""
39    message: "Accordion header buttons must have aria-controls attribute referencing the ID of the associated panel."
40 
41  # Heading wrapper missing role
42 
43  - pattern: "(?i)<(div|section)[^>]*(?:accordion.*header|header._accordion)[^>]_>"
44    pattern_negate: "role=\"heading\""
45    message: "Accordion header wrappers should have role='heading' or use native heading elements (h1-h6)."
46 
47  # Heading role missing aria-level
48 
49  - pattern: "(?i)<[^>]_role=\"heading\"[^>]_>"
50    pattern_negate: "aria-level=\"[1-6]\""
51    message: "Elements with role='heading' must have aria-level attribute set to appropriate level (1-6)."
52 
53  # Panel missing proper identification
54 
55  - pattern: "(?i)<(div|section)[^>]*(?:accordion.*panel|panel._accordion)[^>]_>"
56    pattern_negate: "id=\"[^\"]+\""
57    message: "Accordion panels must have unique ID attributes for aria-controls reference."
58 
59  # Panel with region role missing aria-labelledby
60 
61  - pattern: "(?i)<[^>]_role=\"region\"[^>]_>"
62    pattern_negate: "aria-labelledby=\"[^\"]+\""
63    message: "Accordion panels with role='region' must have aria-labelledby referencing the heading element."
64 
65  # Missing keyboard event handlers
66 
67  - pattern: "(?i)<button[^>]_(?:accordion|expand|collapse)[^>]_>"
68    pattern_negate: "(onKeyDown|onkeydown|@keydown|v-on:keydown)"
69    message: "Accordion header buttons should handle keyboard events (Enter, Space, optionally Arrow keys)."
70 
71  # Missing Escape key support for accordion content
72 
73  - pattern: "(?i)<(div|section)[^>]*(?:accordion.*panel|panel._accordion)[^>]_>"
74    pattern_negate: "(onKeyDown|onkeydown|@keydown|v-on:keydown)"
75    message: "Accordion panels should handle Escape key to close panel and return focus to header."
76 
77- type: suggest
78  message: |
79  **Accordion Component Accessibility Best Practices:**
80 
81  **Required ARIA Attributes:**
82 
83  - **role='button':** Set on accordion header elements (or use native button)
84  - **role='heading':** Set on accordion header container with aria-level
85  - **aria-expanded:** 'true' if panel is visible, 'false' if collapsed
86  - **aria-controls:** Reference to the ID of the associated panel content
87  - **aria-level:** Appropriate heading level (1-6) for information architecture
88  - **aria-disabled:** 'true' if panel cannot be collapsed (optional)
89 
90  **Optional ARIA Attributes:**
91 
92  - **role='region':** On panel content containers (avoid with >6 panels)
93  - **aria-labelledby:** On panels with role='region', referencing the heading element
94 
95  **Keyboard Interaction Requirements:**
96 
97  - **Enter/Space:** Toggle panel expansion/collapse
98  - **Tab/Shift+Tab:** Move through all focusable elements in page order
99  - **Down/Up Arrow:** (Optional) Navigate between accordion headers
100  - **Home/End:** (Optional) Jump to first/last accordion header
101  - **Escape:** Close open panel and return focus to header button
102 
103  **Structure Requirements:**
104 
105  - Header button must be the only element inside heading container
106  - Each panel must have unique ID for aria-controls reference
107  - Use native heading elements (h1-h6) when possible instead of role='heading'
108  - Avoid role='region' on panels when many accordions exist (>6 panels)
109 
110  **Implementation Patterns:**
111 
112  **Single Accordion Item:**
113 
114```html
115  <div class="accordion-item">
116    <h3
117      role="heading"
118      aria-level="3"
119      id="header-1"
120    >
121      <button
122        aria-expanded="false"
123        aria-controls="panel-1"
124      >
125        Section Title
126      </button>
127    </h3>
128    <div
129      id="panel-1"
130      role="region"
131      aria-labelledby="header-1"
132      hidden
133    >
134      <p>Panel content...</p>
135    </div>
136  </div>
137```
138 
139  **JavaScript for Accordion with Escape Support:**
140 
141```javascript
142  function toggleAccordion(button) {
143    const isExpanded = button.getAttribute('aria-expanded') === 'true';
144    const panel = document.getElementById(button.getAttribute('aria-controls'));
145 
146    button.setAttribute('aria-expanded', !isExpanded);
147    panel.hidden = isExpanded;
148 
149    if (!isExpanded) {
150      // Add escape key listener to panel
151      panel.addEventListener('keydown', handleAccordionEscapeKey);
152    } else {
153      // Remove escape key listener
154      panel.removeEventListener('keydown', handleAccordionEscapeKey);
155    }
156  }
157 
158  function handleAccordionEscapeKey(event) {
159    if (event.key === 'Escape') {
160      const panel = event.target.closest('[hidden]');
161      if (panel) {
162        const button = document.querySelector(`[aria-controls="${panel.id}"]`);
163        if (button) {
164          button.setAttribute('aria-expanded', 'false');
165          panel.hidden = true;
166          button.focus(); // Return focus to header
167          panel.removeEventListener('keydown', handleAccordionEscapeKey);
168        }
169      }
170    }
171  }
172```
173 
174  **Using Native Heading:**
175 
176```html
177  <div class="accordion-item">
178    <h3 id="header-2">
179      <button
180        aria-expanded="false"
181        aria-controls="panel-2"
182      >
183        Section Title
184      </button>
185    </h3>
186    <div
187      id="panel-2"
188      aria-labelledby="header-2"
189    >
190      <p>Panel content...</p>
191    </div>
192  </div>
193```
194 
195  **JavaScript Considerations:**
196 
197  - Implement Enter and Space key handlers for expansion/collapse
198  - Optionally implement Arrow key navigation between headers
199  - Update aria-expanded state when panels toggle
200  - Consider implementing single-expand vs multi-expand behavior
201  - Use hidden attribute or CSS to show/hide panels (note: CSS visibility property can be animated)
202  - Ensure smooth keyboard navigation flow
203  - Implement Escape key handler to close open panel and return focus to header
204  - Add/remove event listeners when panels open/close to manage Escape key support
205 
206  **Accessibility Notes:**
207 
208  - Role 'region' helps screen readers understand panel structure
209  - Avoid role='region' proliferation with many simultaneous panels
210  - Button should be direct child of heading element
211  - Consider aria-disabled='true' for panels that cannot be collapsed
212  - Test with screen readers to ensure proper announcement
213 
214metadata:
215priority: high
216version: 1.0
217</rule>
218