Cursor rule

1---
2description: Disclosure component accessibility compliance pattern
3globs: *.vue, *.jsx, *.tsx, *.html, *.php, *.js, *.ts, *.liquid
4alwaysApply: false
5---
6# Disclosure Component Accessibility Standards
7 
8Ensures disclosure components follow WCAG compliance and WAI-ARIA Disclosure Pattern specifications.
9 
10<rule>
11name: disclosure_accessibility_standards
12description: Enforce disclosure component accessibility standards and WAI-ARIA Disclosure Pattern compliance
13filters:
14  - type: file_extension
15    pattern: "\\.(vue|jsx|tsx|html|liquid|php|js|ts)$"
16 
17actions:
18  - type: enforce
19    conditions:
20      # Button role requirement
21      - pattern: "(?i)<(button|div|span)[^>]*(?:disclosure|expand|collapse)[^>]*>"
22        pattern_negate: "role=\"button\""
23        message: "Disclosure controls must have role='button' (or use native button element which has implicit role)."
24 
25      # aria-expanded requirement
26      - pattern: "(?i)<[^>]*role=\"button\"[^>]*(?:disclosure|expand|collapse)[^>]*>"
27        pattern_negate: "aria-expanded=\"(true|false)\""
28        message: "Disclosure controls must have aria-expanded attribute set to 'true' or 'false'."
29 
30      # Missing keyboard event handlers
31      - pattern: "(?i)<[^>]*role=\"button\"[^>]*(?:disclosure|expand|collapse)[^>]*>"
32        pattern_negate: "(onKeyDown|onkeydown|@keydown|v-on:keydown)"
33        message: "Disclosure controls should handle keyboard events (Enter and Space)."
34 
35  - type: suggest
36    message: |
37      **Disclosure Component Accessibility Best Practices:**
38 
39      **Required ARIA Attributes:**
40      - **role='button':** Set on the disclosure control element (or use native button)
41      - **aria-expanded:** 'true' if content is visible, 'false' if hidden
42      - **aria-controls:** (Optional) Reference to the ID of the associated content
43 
44      **DOM Structure Requirements:**
45      - The disclosure content MUST be a sibling to the disclosure control in the DOM
46      - This ensures proper content discovery and navigation for all users
47      - Avoid placing content in different containers or far from the control
48      - Maintain a logical reading order in the DOM
49 
50      **Keyboard Interaction Requirements:**
51      - **Enter:** Toggle disclosure content visibility
52      - **Space:** Toggle disclosure content visibility
53      - **Tab:** Move focus to next focusable element
54      - **Shift+Tab:** Move focus to previous focusable element
55 
56      **Implementation Example:**
57```html
58      <!-- ✅ Correct: Content is a sibling to the control -->
59      <div class="disclosure">
60        <button type="button"
61                role="button"
62                aria-expanded="false"
63                aria-controls="disclosure-content">
64          Disclosure Title
65        </button>
66        <div id="disclosure-content"
67             hidden>
68          Disclosure content goes here...
69        </div>
70      </div>
71 
72      <!-- ❌ Incorrect: Content is not a sibling to the control -->
73      <div class="disclosure">
74        <button type="button"
75                role="button"
76                aria-expanded="false"
77                aria-controls="disclosure-content">
78          Disclosure Title
79        </button>
80      </div>
81      <div class="some-other-container">
82        <p>Other content...</p>
83        <div id="disclosure-content" hidden>
84          Disclosure content goes here...
85        </div>
86      </div>
87 
88      <script>
89        const button = document.querySelector('[role="button"]');
90        const content = document.getElementById('disclosure-content');
91 
92        function toggleDisclosure() {
93          const isExpanded = button.getAttribute('aria-expanded') === 'true';
94          button.setAttribute('aria-expanded', !isExpanded);
95          content.hidden = isExpanded;
96        }
97 
98        // Click handler
99        button.addEventListener('click', toggleDisclosure);
100 
101        // Keyboard handler
102        button.addEventListener('keydown', (event) => {
103          if (event.key === 'Enter' || event.key === ' ') {
104            event.preventDefault();
105            toggleDisclosure();
106          }
107        });
108      </script>
109```
110 
111      **JavaScript Considerations:**
112      - Implement Enter and Space key handlers for toggling
113      - Update aria-expanded state when content toggles
114      - Use hidden attribute or CSS to show/hide content
115      - Consider implementing smooth transitions
116 
117      **Accessibility Notes:**
118      - Button should be the only element inside the control
119      - Content MUST be a sibling to the control in the DOM
120      - Visual focus indicators should be clear
121      - Test with screen readers to ensure proper announcement
122      - Consider adding aria-label if the button text is not descriptive
123      - Maintain proper reading order for screen reader users
124      - Avoid complex DOM structures that could confuse navigation
125 
126metadata:
127  priority: high
128  version: 1.0
129</rule>
130