Cursor rule

1---
2description: Enforce animation accessibility standards per WCAG 2.2.2 Pause Stop Hide, 2.3.1 Three Flashes or Below Threshold, and 2.3.3 Animation from Interactions requirements
3globs: *.vue, *.jsx, *.tsx, *.html, *.php, *.js, *.ts, *.css, *.scss, *.sass, *.less
4alwaysApply: false
5---
6 
7# Animation Accessibility Standards
8 
9Ensures animations follow WCAG compliance and provide inclusive motion design for users with different accessibility needs including photosensitivity, motion sickness, and cognitive impairments.
10 
11<rule>
12name: animation_accessibility_standards
13description: Enforce animation accessibility standards per WCAG 2.2.2 Pause Stop Hide, 2.3.1 Three Flashes or Below Threshold, and 2.3.3 Animation from Interactions requirements
14filters:
15  - type: file_extension
16    pattern: "\\.(vue|jsx|tsx|html|liquid|php|js|ts|css|scss|sass|less)$"
17 
18actions:
19  - type: enforce
20    conditions:
21      # Missing prefers-reduced-motion media query for animations
22      - pattern: "(animation|transition|transform|@keyframes)"
23        pattern_negate: "@media\\s*\\(prefers-reduced-motion:\\s*reduce\\)"
24        message: "Animations should include prefers-reduced-motion: reduce media query to provide safer alternatives for motion-sensitive users."
25 
26      # Flashing animations exceeding 3Hz frequency
27      - pattern: "animation.*(?:pulse|flash|blink|flicker)"
28        pattern_negate: "animation-duration:\\s*[0-9]*\\.?[0-9]+s|animation-duration:\\s*[0-9]*\\.?[0-9]+ms"
29        message: "Flashing animations must have duration ensuring frequency is below 3Hz (0.33s) to prevent seizures per WCAG 2.3.1."
30 
31      # Rapid color transitions that may trigger photosensitivity
32      - pattern: "transition.*color.*[0-9]*\\.?[0-9]+s|transition.*background.*[0-9]*\\.?[0-9]+s"
33        pattern_negate: "transition.*color.*[0-9]*\\.?[0-9]+s.*[0-9]*\\.?[0-9]+s|transition.*background.*[0-9]*\\.?[0-9]+s.*[0-9]*\\.?[0-9]+s"
34        message: "Color transitions should be slow and smooth to avoid triggering photosensitivity. Use longer durations and easing functions."
35 
36      # Large spatial movements without reduced motion alternatives
37      - pattern: "transform.*translate\\([^)]*[0-9]{2,}[^)]*\\)|transform.*translate\\([^)]*-[0-9]{2,}[^)]*\\)"
38        pattern_negate: "@media\\s*\\(prefers-reduced-motion:\\s*reduce\\)"
39        message: "Large spatial movements should have reduced motion alternatives using prefers-reduced-motion media query."
40 
41      # Parallax effects without user control
42      - pattern: "(parallax|scroll.*jack|scroll.*hijack)"
43        pattern_negate: "(prefers-reduced-motion|user.*control|pause.*animation)"
44        message: "Parallax and scroll jacking effects should respect user motion preferences and provide controls to pause/disable."
45 
46      # Auto-playing animations without pause controls
47      - pattern: "animation.*infinite|animation.*loop"
48        pattern_negate: "(pause.*control|user.*control|prefers-reduced-motion)"
49        message: "Looping animations must provide pause controls and respect prefers-reduced-motion preferences."
50 
51      # Unexpected system-triggered animations
52      - pattern: "animation.*(?:appear|fade.*in|slide.*in)"
53        pattern_negate: "(user.*interaction|click|hover|focus|prefers-reduced-motion)"
54        message: "System-triggered animations should be subtle and respect user motion preferences."
55 
56      # Missing animation alternatives for essential UI changes
57      - pattern: "(?:loading|spinner|progress|status)"
58        pattern_negate: "(animation|transition|@keyframes)"
59        message: "Essential UI elements like loading indicators should have appropriate animations to communicate state changes."
60 
61      # Excessive animation duration that may cause motion sickness
62      - pattern: "animation-duration:\\s*[5-9]\\.[0-9]+s|animation-duration:\\s*[0-9]{2,}s"
63        message: "Long animation durations may cause motion sickness. Consider shorter durations and provide reduced motion alternatives."
64 
65      # Missing focus indicators for animated interactive elements
66      - pattern: "(?:button|a|input|select|textarea).*\\{[^}]*animation"
67        pattern_negate: "(focus|focus-visible|outline|box-shadow)"
68        message: "Animated interactive elements must have visible focus indicators for keyboard navigation accessibility."
69 
70      # Animation without meaningful purpose or context
71      - pattern: "animation.*(?:bounce|wiggle|shake|rotate)"
72        pattern_negate: "(loading|status|feedback|interaction)"
73        message: "Animations should serve a meaningful purpose. Avoid decorative animations that may distract or confuse users."
74 
75      # Missing animation state management
76      - pattern: "animation.*(?:play|pause|stop)"
77        pattern_negate: "(prefers-reduced-motion|user.*control|aria.*live)"
78        message: "Animation state changes should be communicated to assistive technology and respect user preferences."
79 
80  - type: suggest
81    message: |
82      **Animation Accessibility Best Practices:**
83 
84      **1. Respect Motion Preferences (WCAG 2.3.3):**
85```css
86      /* Default animation */
87      .fade-in {
88        animation: fadeIn 0.3s ease-in-out;
89      }
90 
91      /* Reduced motion alternative */
92      @media (prefers-reduced-motion: reduce) {
93        .fade-in {
94          animation: none;
95          opacity: 1;
96        }
97      }
98```
99 
100      **2. Seizure Prevention (WCAG 2.3.1):**
101```css
102      /* Safe flashing animation - below 3Hz threshold */
103      .pulse {
104        animation: pulse 0.4s ease-in-out infinite;
105      }
106 
107      /* Reduced motion alternative */
108      @media (prefers-reduced-motion: reduce) {
109        .pulse {
110          animation: none;
111          opacity: 0.8;
112        }
113      }
114```
115 
116      **3. Motion Sickness Prevention:**
117```css
118      /* Gentle, predictable animations */
119      .slide-in {
120        transform: translateX(20px);
121        transition: transform 0.2s ease-out;
122      }
123 
124      /* Reduced motion alternative */
125      @media (prefers-reduced-motion: reduce) {
126        .slide-in {
127          transform: none;
128          transition: none;
129          opacity: 1;
130        }
131      }
132```
133 
134      **4. Essential UI Animations:**
135```css
136      /* Loading spinner - essential for user understanding */
137      .loading-spinner {
138        animation: spin 1s linear infinite;
139      }
140 
141      /* Keep essential animations even with reduced motion */
142      @media (prefers-reduced-motion: reduce) {
143        .loading-spinner {
144          animation: spin 2s linear infinite; /* Slower but still visible */
145        }
146      }
147```
148 
149      **5. User Control Implementation:**
150```javascript
151      // Animation pause control
152      class AnimationController {
153        constructor() {
154          this.isPaused = false;
155          this.animations = document.querySelectorAll('[data-animation]');
156          this.setupControls();
157        }
158 
159        setupControls() {
160          const pauseButton = document.getElementById('pause-animations');
161          if (pauseButton) {
162            pauseButton.addEventListener('click', () => this.togglePause());
163          }
164        }
165 
166        togglePause() {
167          this.isPaused = !this.isPaused;
168          this.animations.forEach(animation => {
169            if (this.isPaused) {
170              animation.style.animationPlayState = 'paused';
171            } else {
172              animation.style.animationPlayState = 'running';
173            }
174          });
175        }
176      }
177```
178 
179      **6. CSS Animation Best Practices:**
180```css
181      /* Safe animation defaults */
182      .safe-animation {
183        /* Keep travel distances short */
184        transform: translateY(10px);
185 
186        /* Use gentle easing */
187        transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
188 
189        /* Respect motion preferences */
190        @media (prefers-reduced-motion: reduce) {
191          transform: none;
192          transition: none;
193        }
194      }
195 
196      /* Fade as safe default */
197      .fade-transition {
198        opacity: 0;
199        transition: opacity 0.3s ease-in-out;
200      }
201 
202      .fade-transition.visible {
203        opacity: 1;
204      }
205 
206      /* Reduced motion alternative */
207      @media (prefers-reduced-motion: reduce) {
208        .fade-transition {
209          transition: none;
210          opacity: 1;
211        }
212      }
213```
214 
215      **7. JavaScript Animation Control:**
216```javascript
217      // Check motion preferences
218      function shouldReduceMotion() {
219        return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
220      }
221 
222      // Safe animation function
223      function safeAnimate(element, animation, options = {}) {
224        if (shouldReduceMotion()) {
225          // Provide alternative experience
226          element.style.opacity = '1';
227          element.style.transform = 'none';
228          return;
229        }
230 
231        // Apply animation
232        element.style.animation = animation;
233 
234        // Add pause control
235        if (options.looping) {
236          element.addEventListener('click', () => {
237            element.style.animationPlayState =
238              element.style.animationPlayState === 'paused' ? 'running' : 'paused';
239          });
240        }
241      }
242```
243 
244      **8. HTML Structure for Animation Control:**
245```html
246      <!-- Animation control panel -->
247      <div class="animation-controls" role="region" aria-label="Animation controls">
248        <button id="pause-animations" aria-pressed="false">
249          Pause All Animations
250        </button>
251 
252        <button id="reduce-motion" aria-pressed="false">
253          Reduce Motion
254        </button>
255      </div>
256 
257      <!-- Animated element with controls -->
258      <div class="animated-element"
259           data-animation="fade-in"
260           aria-live="polite">
261        Content that animates
262      </div>
263```
264 
265      **9. Animation State Management:**
266```css
267      /* Animation states */
268      .animated-element {
269        opacity: 0;
270        transform: translateY(20px);
271        transition: all 0.3s ease-out;
272      }
273 
274      .animated-element.animate {
275        opacity: 1;
276        transform: translateY(0);
277      }
278 
279      .animated-element.paused {
280        animation-play-state: paused;
281      }
282 
283      /* Reduced motion states */
284      @media (prefers-reduced-motion: reduce) {
285        .animated-element {
286          opacity: 1;
287          transform: none;
288          transition: none;
289        }
290      }
291```
292 
293      **10. Testing and Validation:**
294```javascript
295      // Test animation accessibility
296      function testAnimationAccessibility() {
297        const issues = [];
298 
299        // Check for flashing animations
300        const flashingElements = document.querySelectorAll('[class*="flash"], [class*="pulse"]');
301        flashingElements.forEach(element => {
302          const style = window.getComputedStyle(element);
303          const duration = parseFloat(style.animationDuration);
304          if (duration < 0.33) { // Below 3Hz threshold
305            issues.push(`Flashing animation too fast: ${element.className}`);
306          }
307        });
308 
309        // Check for motion preference support
310        const hasReducedMotion = document.querySelector('@media (prefers-reduced-motion: reduce)');
311        if (!hasReducedMotion) {
312          issues.push('Missing reduced motion alternatives');
313        }
314 
315        return issues;
316      }
317```
318 
319      **Animation Guidelines:**
320 
321      **Keep These Animations:**
322      - **Fading:** Safe default for most transitions
323      - **Loading indicators:** Essential for user understanding
324      - **Subtle scaling:** Gentle size changes for feedback
325      - **Color transitions:** Slow, smooth color changes
326 
327      **Subdue These Animations:**
328      - **System-triggered:** Make unexpected animations subtle
329      - **Large movements:** Reduce distance and speed
330      - **Color changes:** Use gentler transitions
331 
332      **Remove These Animations:**
333      - **Decorative effects:** Remove purely visual animations
334      - **Spatial movement:** Replace with gentle fades
335      - **Auto-playing loops:** Remove or provide pause controls
336 
337      **Testing Checklist:**
338      - Test with prefers-reduced-motion: reduce
339      - Verify animations don't exceed 3Hz frequency
340      - Check that essential UI changes are clear without animation
341      - Ensure pause controls work for looping animations
342      - Test with screen readers and assistive technology
343      - Validate motion doesn't cause disorientation
344 
345      **Common Mistakes to Avoid:**
346      - Missing prefers-reduced-motion media queries
347      - Flashing animations above 3Hz threshold
348      - Large spatial movements without alternatives
349      - Auto-playing animations without pause controls
350      - Parallax effects that ignore user preferences
351      - Animations that patch design shortcomings
352      - Missing focus indicators on animated elements
353      - Excessive animation duration causing motion sickness
354 
355metadata:
356  priority: high
357  version: 1.0
358</rule>
359description:
360globs:
361alwaysApply: false
362---
363