Cursor rule

1---
2description: Chat window component accessibility compliance and WCAG compliance for real-time communication features
3globs: *.vue, *.jsx, *.tsx, *.html, *.php, *.js, *.ts, *.liquid
4alwaysApply: false
5---
6# Chat Window Component Accessibility Standards
7 
8Ensures chat window components follow WCAG compliance and provide proper accessibility for real-time communication, notifications, and assistive technology support.
9 
10<rule>
11name: chat_window_accessibility_standards
12description: Enforce chat window component accessibility standards and WCAG compliance for real-time communication features
13filters:
14  - type: file_extension
15    pattern: "\\.(vue|jsx|tsx|html|liquid|php|js|ts|css|scss|sass|less)$"
16 
17actions:
18  - type: enforce
19    conditions:
20      # Chat window missing proper landmark role
21      - pattern: "(?i)<(div|section)[^>]*(?:chat|conversation|messages)[^>]*>"
22        pattern_negate: "role=\"(log|region|dialog)\""
23        message: "Chat window containers must have role='log' for message history, role='region' for general chat areas, or role='dialog' for popup windows."
24 
25      # Chat log missing accessible name
26      - pattern: "(?i)<[^>]*role=\"log\"[^>]*>"
27        pattern_negate: "(aria-labelledby|aria-label)"
28        message: "Chat log elements must have accessible names via aria-labelledby or aria-label for screen reader identification."
29 
30      # Chat messages missing author identification
31      - pattern: "(?i)<(p|div)[^>]*(?:message|chat|conversation)[^>]*>"
32        pattern_negate: "(aria-label|aria-labelledby|class.*visually-hidden|class.*sr-only)"
33        message: "Chat messages must include author identification via visible text, aria-label, or visually hidden content for screen reader users."
34 
35      # Chat messages in wrong DOM order
36      - pattern: "(?i)<div[^>]*class=\"[^\"]*(?:left|right|user|agent)[^\"]*\"[^>]*>"
37        pattern_negate: "(role=\"log\"|aria-live)"
38        message: "Chat messages must maintain chronological order in DOM structure. Avoid using separate columns that break reading sequence."
39 
40      # Chat notifications relying only on sound
41      - pattern: "(?i)(audio|sound|play|new.*message)"
42        pattern_negate: "(aria-live|role=\"status\"|visual.*notification|title.*change|notification.*badge)"
43        message: "Chat notifications must use multiple sensory channels. Combine sound with visual indicators, aria-live announcements, title changes, and notification badges."
44 
45      # Chat window missing keyboard support
46      - pattern: "(?i)<(div|section)[^>]*(?:chat|conversation)[^>]*>"
47        pattern_negate: "(onKeyDown|onkeydown|@keydown|v-on:keydown|tabindex)"
48        message: "Chat windows must support keyboard navigation for opening, closing, and message interaction."
49 
50      # Chat popup missing focus management
51      - pattern: "(?i)<(div|section)[^>]*role=\"dialog\"[^>]*(?:chat|conversation)[^>]*>"
52        pattern_negate: "(aria-modal|focus|tabindex)"
53        message: "Chat popup windows must implement proper focus management and aria-modal='true' for accessibility."
54 
55      # Chat launcher missing aria-haspopup
56      - pattern: "(?i)<(button|div)[^>]*(?:chat|conversation|support)[^>]*>"
57        pattern_negate: "aria-haspopup=\"dialog\""
58        message: "Chat launcher buttons must include aria-haspopup='dialog' to inform users a dialog will open."
59 
60      # Chat window missing focus trap
61      - pattern: "(?i)<[^>]*role=\"dialog\"[^>]*(?:chat|conversation)[^>]*>"
62        pattern_negate: "(focus.*trap|tabindex|aria-modal)"
63        message: "Chat popup windows must implement focus trapping to prevent keyboard navigation outside the dialog."
64 
65      # Chat input missing proper labeling
66      - pattern: "(?i)<(input|textarea)[^>]*(?:chat|message|reply)[^>]*>"
67        pattern_negate: "(aria-label|aria-labelledby|label|placeholder)"
68        message: "Chat input fields must have proper labels via label elements, aria-label, or aria-labelledby for screen reader context."
69 
70      # Chat button missing accessible name
71      - pattern: "(?i)<(button|div)[^>]*(?:chat|conversation|support)[^>]*>"
72        pattern_negate: "(aria-label|aria-labelledby|>.*[A-Za-z]{10,})"
73        message: "Chat buttons must have accessible names via visible text, aria-label, or aria-labelledby for screen reader identification."
74 
75      # Chat button missing proper role
76      - pattern: "(?i)<(div|span)[^>]*(?:chat|conversation|support)[^>]*>"
77        pattern_negate: "(role=\"button\"|<button)"
78        message: "Chat controls styled as buttons must have role='button' or use native button elements for proper semantics."
79 
80      # Chat window missing expandable state management
81      - pattern: "(?i)<(button|div)[^>]*(?:chat|conversation)[^>]*>"
82        pattern_negate: "aria-expanded=\"(true|false)\""
83        message: "Expandable chat windows must have aria-expanded attribute to indicate open/closed state for screen readers."
84 
85      # Chat window missing aria-controls
86      - pattern: "(?i)<(button|div)[^>]*(?:chat|conversation)[^>]*>"
87        pattern_negate: "aria-controls=\"[^\"]+\""
88        message: "Chat controls must have aria-controls referencing the chat window ID for proper association."
89 
90      # Chat timeout missing user notification
91      - pattern: "(?i)(timeout|session.*expir|inactive)"
92        pattern_negate: "(notification|warning|extend|20.*second)"
93        message: "Chat timeouts must notify users before expiration and provide at least 20 seconds to extend the session."
94 
95      # Chat auto-update missing pause controls
96      - pattern: "(?i)(auto.*update|real.*time|live.*update)"
97        pattern_negate: "(pause|stop|hide|user.*control)"
98        message: "Auto-updating chat content must provide pause/stop controls to prevent overwhelming screen reader users."
99 
100      # Chat missing persistent notification system
101      - pattern: "(?i)<(div|section)[^>]*(?:chat|conversation)[^>]*>"
102        pattern_negate: "(notification.*badge|aria-live.*polite|role.*status)"
103        message: "Chat windows must provide persistent notification system including visual badge counter and persistent screen reader announcements when closed."
104 
105      # Chat focus not contained within popup
106      - pattern: "(?i)<[^>]*role=\"dialog\"[^>]*(?:chat|conversation)[^>]*>"
107        pattern_negate: "(focus.*trap|tabindex|aria-modal)"
108        message: "Chat popup windows must contain keyboard focus to prevent focus from becoming obscured behind the dialog."
109 
110      # Chat messages missing proper contrast
111      - pattern: "(?i)<(p|div)[^>]*(?:message|chat)[^>]*>"
112        pattern_negate: "(color.*#[0-4][0-9a-fA-F]{5}|color.*#[5-9a-fA-F][0-9a-fA-F]{5})"
113        message: "Chat message text must meet WCAG contrast requirements (4.5:1 minimum for normal text, 3:1 for large text)."
114 
115      # Chat window not responsive
116      - pattern: "(?i)<(div|section)[^>]*(?:chat|conversation)[^>]*>"
117        pattern_negate: "(max-width|min-width|flex|grid|responsive)"
118        message: "Chat windows must be responsive and work on devices down to 320px width without horizontal scrolling."
119 
120      # Chat icon missing alt text
121      - pattern: "(?i)<img[^>]*(?:chat|conversation|support)[^>]*>"
122        pattern_negate: "alt=\"[^\"]+\""
123        message: "Chat-related images must have descriptive alt text for screen reader users."
124 
125      # Chat status messages missing role
126      - pattern: "(?i)<(div|span)[^>]*(?:status|notification|typing)[^>]*>"
127        pattern_negate: "role=\"(status|log|alert)\""
128        message: "Chat status messages must use appropriate ARIA roles (status, log, or alert) for screen reader announcements."
129 
130  - type: suggest
131    message: |
132      **WCAG Chat Window Accessibility Requirements:**
133 
134      **Key Accessibility Features:**
135      - **Easy to find and use:** Intuitive placement and clear labeling
136      - **Multi-sensory notifications:** Visual, auditory, and haptic feedback
137      - **Universal access:** All features available to all users
138      - **Message preservation:** All messages accessible to everyone
139 
140      **WCAG Criteria Implementation:**
141 
142      **1. Info and Relationships (WCAG 1.3.1):**
143      - **Author identification:** Each message must clearly indicate who sent it
144      - **Visual relationships:** Use semantic markup, not just visual styling
145      - **Screen reader support:** Provide context for message ownership
146 
147      **2. Meaningful Sequence (WCAG 1.3.2):**
148      - **Chronological order:** Messages must appear in DOM order matching visual order
149      - **Avoid columns:** Don't separate user/agent messages into different containers
150      - **Reading flow:** Maintain logical conversation sequence for screen readers
151 
152      **3. Sensory Characteristics (WCAG 1.3.3):**
153      - **Multiple notification methods:** Combine sound, visual, and screen reader announcements
154      - **No single sense dependency:** Don't rely solely on audio or visual cues
155      - **Universal alerts:** Ensure notifications work for all users
156 
157      **4. Orientation (WCAG 1.3.4):**
158      - **Responsive design:** Work in both portrait and landscape modes
159      - **No orientation locks:** Allow users to choose their preferred orientation
160      - **Flexible layouts:** Adapt to different screen sizes and orientations
161 
162      **5. Contrast (WCAG 1.4.3):**
163      - **Text contrast:** 4.5:1 minimum for normal text, 3:1 for large text
164      - **Background contrast:** Ensure sufficient contrast for all text elements
165      - **Visual clarity:** Make messages easily readable for all users
166 
167      **6. Reflow (WCAG 1.4.10):**
168      - **Responsive design:** Work on devices down to 320px width
169      - **No horizontal scroll:** Content must fit without horizontal scrolling
170      - **Flexible layouts:** Use CSS Grid and Flexbox for adaptability
171 
172      **7. Non-text Contrast (WCAG 1.4.11):**
173      - **Image alternatives:** Provide alt text for all images and icons
174      - **Icon identification:** Ensure chat icons are properly labeled
175      - **Visual elements:** Make all non-text content accessible
176 
177      **8. Keyboard (WCAG 2.1.1):**
178      - **Full keyboard support:** All chat functions must work with keyboard
179      - **Navigation:** Support Tab, Enter, Space, and Escape keys
180      - **No mouse dependency:** Ensure keyboard-only users can fully participate
181 
182      **9. No Keyboard Trap (WCAG 2.1.2):**
183      - **Focus management:** Proper focus trapping within chat windows
184      - **Escape mechanism:** Provide clear way to exit chat
185      - **Focus restoration:** Return focus to launcher when chat closes
186      - **Focus trap:** Prevent keyboard navigation outside chat window while open
187 
188      **11. Timing Adjustable (WCAG 2.2.1):**
189      - **Session timeouts:** Notify users before session expiration (minimum 30 seconds notice)
190      - **Extension options:** Provide at least 20 seconds to extend
191      - **Character monitoring:** Listen for input changes, not just key presses
192      - **Screen reader notification:** Use dedicated role="alert" element for important timeout warnings
193 
194      **12. Pause, Stop, Hide (WCAG 2.2.2):**
195      - **Content control:** Allow users to pause auto-updating content
196      - **Overwhelm prevention:** Provide mechanisms to reduce screen reader noise
197      - **Essential content:** Balance accessibility with functionality
198 
199      **13. Enhanced Notifications (WCAG 4.1.3):**
200      - **Persistent notifications:** Provide visual badge counter on chat launcher when closed
201      - **Screen reader announcements:** Persistent aria-live regions for notifications when chat window is closed
202      - **Multi-sensory feedback:** Combine visual, auditory, and screen reader notifications
203      - **Context awareness:** Notify users about new messages even when chat window is not open
204      - **Enhanced button labeling:** Dynamic accessible name that includes unread message count for better context
205 
206      **14. User Interaction Monitoring (WCAG 2.2.1):**
207      - **Session extension on interaction:** Extend chat session on any user interaction, not just sent messages
208      - **Comprehensive monitoring:** Monitor clicks, key presses, input changes, scrolling, and focus events
209      - **Assistive technology support:** Ensure users with typing difficulties can extend sessions through other interactions
210      - **Immediate response:** Reset session timer immediately on any user engagement
211 
212      **15. Focus Not Obscured (WCAG 2.4.11):**
213      - **Focus visibility:** Ensure keyboard focus is always visible
214      - **Modal containment:** Keep focus within chat popup windows
215      - **Background prevention:** Don't let focus move behind chat windows
216 
217      **16. Name, Role, Value (WCAG 4.1.2):**
218      - **Accessible names:** Clear labels for all interactive elements
219      - **Proper roles:** Use semantic HTML or appropriate ARIA roles
220      - **State management:** Maintain and communicate current states
221 
222      **17. Status Messages (WCAG 4.1.3):**
223      - **Real-time updates:** Announce new messages and status changes
224      - **Context awareness:** Provide appropriate level of detail
225      - **Screen reader support:** Use role='log' for message history
226 
227      **18. Modal Dialog Requirements:**
228      - **aria-haspopup="dialog":** Set on chat launcher buttons (no aria-controls or aria-expanded needed)
229      - **Focus trapping:** Prevent keyboard navigation outside chat window
230      - **Initial focus:** Move focus to first focusable element when chat opens
231      - **Focus restoration:** Return focus to launcher when chat closes
232      - **Escape key:** Close chat window with Escape key
233      - **Focus trap implementation:** Must handle both forward (Tab) and backward (Shift+Tab) navigation
234      - **Focusable element detection:** Include all interactive elements (buttons, inputs, textareas, links, custom focusable elements)
235      - **Safety checks:** Additional validation to ensure focus remains within chat window
236 
237      **Implementation Patterns:**
238 
239      **1. Basic Chat Window Structure (Modal Dialog Pattern):**
240```html
241      <!-- Chat launcher button -->
242      <button id="chat-launcher"
243              aria-haspopup="dialog">
244        <img src="chat-icon.png" alt="" />
245        Chat with Support
246        <span id="notification-badge" class="notification-badge" hidden>0</span>
247      </button>
248 
249      **Note:** For modal dialog pattern, use only `aria-haspup="dialog"`. Do not use `aria-controls` or `aria-expanded` as these are not needed for modal dialogs.
250 
251      <!-- Chat window -->
252      <div id="chat-window"
253           role="dialog"
254           aria-modal="true"
255           aria-labelledby="chat-heading"
256           hidden>
257        <div class="chat-header">
258          <h2 id="chat-heading">Chat: Customer Support</h2>
259          <button type="button"
260                  aria-label="Close chat"
261                  onclick="closeChat()">
262            ×
263          </button>
264        </div>
265 
266        <!-- Message log -->
267        <div class="chat-messages"
268             role="log"
269             aria-labelledby="chat-heading">
270          <div class="message agent" role="article">
271            <div class="message-content">
272              <span class="sr-only">Customer Support: </span>
273              Hi, how can I help you today?
274            </div>
275            <time class="message-time" datetime="2024-01-15T10:00:00Z">10:00 AM</time>
276          </div>
277          <div class="message user" role="article">
278            <div class="message-content">
279              <span class="sr-only">You sent: </span>
280              I'm having trouble resetting my password.
281            </div>
282            <time class="message-time" datetime="2024-01-15T10:01:00Z">10:01 AM</time>
283          </div>
284        </div>
285 
286        <!-- Input area -->
287        <div class="chat-input">
288          <label for="message-input" class="visually-hidden">Type your message:</label>
289          <textarea id="message-input"
290                    placeholder="Type your message..."
291                    aria-label="Type your message"></textarea>
292          <button type="button"
293                  aria-label="Send message"
294                  onclick="sendMessage()">
295            Send
296          </button>
297        </div>
298      </div>
299```
300 
301      **2. Chat Message Structure:**
302```html
303      <!-- Good: Proper message structure with author identification -->
304      <div class="chat-messages" role="log" aria-labelledby="chat-heading">
305        <div class="message agent">
306          <div class="message-content">
307            <span class="sr-only">Customer Support: </span>
308            Hi, how can I help you today?
309          </div>
310          <time class="message-time" datetime="2024-01-15T10:00:00Z">10:00 AM</time>
311        </div>
312        <div class="message user">
313          <div class="message-content">
314            <span class="sr-only">You sent: </span>
315            I'm having trouble resetting my password.
316          </div>
317          <time class="message-time" datetime="2024-01-15T10:01:00Z">10:01 AM</time>
318        </div>
319        <div class="message agent">
320          <div class="message-content">
321            <span class="sr-only">Customer Support: </span>
322            I can help with that. What's your email address?
323          </div>
324          <time class="message-time" datetime="2024-01-15T10:01:30Z">10:01 AM</time>
325        </div>
326      </div>
327 
328      **Note:** Use div elements for chat messages instead of role="article" to reduce navigation noise for screen reader users. Chat messages are conversational content rather than standalone articles.
329 
330      <!-- Bad: Separate columns that break reading order -->
331      <div class="chat-columns">
332        <div class="left-column">
333          <p>Customer Support: Hi</p>
334          <p>Customer Support: How can I help?</p>
335        </div>
336        <div class="right-column">
337          <p>Me: Hi</p>
338          <p>Me: I need help</p>
339        </div>
340      </div>
341```
342 
343      **3. Multi-Sensory Notifications:**
344```html
345      <!-- Status message for new messages -->
346      <div role="status" aria-live="polite" class="chat-status">
347        New message received
348      </div>
349 
350      <!-- Visual notification -->
351      <div class="chat-notification" aria-hidden="true">
352        <span class="notification-badge">1</span>
353      </div>
354 
355      <!-- Page title update -->
356      <script>
357        function updatePageTitle(message) {
358          const originalTitle = document.title;
359          document.title = `New message - ${originalTitle}`;
360 
361          // Restore title after 5 seconds
362          setTimeout(() => {
363            document.title = originalTitle;
364          }, 5000);
365        }
366      </script>
367```
368 
369      **4. Enhanced Notification System:**
370```html
371      <!-- Chat launcher with notification badge -->
372      <button id="chat-launcher"
373              class="chat-launcher"
374              aria-haspopup="dialog">
375        <img src="chat-icon.png" alt="" />
376        Chat with Support
377        <span id="notification-badge" class="notification-badge" hidden>0</span>
378      </button>
379 
380      **Note:** The notification badge is part of the button's accessible name, not hidden from screen readers. This provides better context about unread messages.
381 
382      **5. Enhanced Button Labeling:**
383      ```html
384      <!-- Dynamic accessible name based on message count -->
385      <button id="chat-launcher"
386              class="chat-launcher"
387              aria-haspopup="dialog">
388        <img src="chat-icon.png" alt="" />
389        Chat with Support
390        <span id="notification-badge" class="notification-badge" hidden>0</span>
391      </button>
392```
393 
394      **JavaScript for Dynamic Labeling:**
395```javascript
396      // Update button's accessible name to include message count
397      function updateNotificationBadge() {
398        const launcher = document.getElementById('chat-launcher');
399 
400        if (messageCount === 1) {
401          launcher.setAttribute('aria-label', 'Chat with Support - 1 new message');
402        } else if (messageCount > 1) {
403          launcher.setAttribute('aria-label', `Chat with Support - ${messageCount} new messages`);
404        }
405      }
406 
407      // Reset button's accessible name when chat is opened
408      function clearNotificationBadge() {
409        const launcher = document.getElementById('chat-launcher');
410        launcher.removeAttribute('aria-label');
411      }
412```
413 
414      <!-- Persistent notification area for screen readers -->
415      <div id="chat-notifications"
416           role="status"
417           aria-live="polite"
418           class="sr-only"
419           aria-label="Chat notifications">
420      </div>
421 
422      <style>
423        .notification-badge {
424          position: absolute;
425          top: -5px;
426          right: -5px;
427          background: #dc3545;
428          color: white;
429          border-radius: 50%;
430          width: 20px;
431          height: 20px;
432          display: flex;
433          align-items: center;
434          justify-content: center;
435          font-size: 0.75rem;
436          font-weight: bold;
437          transition: all 0.3s ease;
438        }
439 
440        .notification-badge.show {
441          animation: pulse 2s infinite;
442        }
443 
444        @keyframes pulse {
445          0% { transform: scale(1); }
446          50% { transform: scale(1.1); }
447          100% { transform: scale(1); }
448        }
449      </style>
450 
451      <script>
452        let messageCount = 0;
453 
454                // Update notification badge
455        function updateNotificationBadge() {
456          const badge = document.getElementById('notification-badge');
457          const chatWindow = document.getElementById('chat-window');
458          const launcher = document.getElementById('chat-launcher');
459 
460          if (badge) {
461            // Only show badge when chat is closed
462            if (chatWindow.classList.contains('hidden')) {
463              badge.hidden = false;
464              badge.textContent = messageCount;
465              badge.classList.add('show');
466 
467              // Update button's accessible name to include message count
468              if (messageCount === 1) {
469                launcher.setAttribute('aria-label', 'Chat with Support - 1 new message');
470              } else if (messageCount > 1) {
471                launcher.setAttribute('aria-label', `Chat with Support - ${messageCount} new messages`);
472              }
473 
474              // Remove animation after 2 seconds
475              setTimeout(() => {
476                badge.classList.remove('show');
477              }, 2000);
478            } else {
479              // Hide badge when chat is open
480              badge.hidden = true;
481            }
482          }
483        }
484 
485        // Announce persistent notification for screen readers
486        function announcePersistentNotification(sender) {
487          const notificationArea = document.getElementById('chat-notifications');
488          const chatWindow = document.getElementById('chat-window');
489 
490          if (notificationArea && chatWindow.classList.contains('hidden')) {
491            const message = `New message from ${sender === 'agent' ? 'Customer Support' : 'you'}. Chat window is closed.`;
492            notificationArea.textContent = message;
493 
494            // Clear notification after 3 seconds
495            setTimeout(() => {
496              notificationArea.textContent = '';
497            }, 3000);
498          }
499        }
500 
501        // Clear notification badge
502        function clearNotificationBadge() {
503          const badge = document.getElementById('notification-badge');
504          const launcher = document.getElementById('chat-launcher');
505 
506          if (badge) {
507            badge.hidden = true;
508            badge.classList.remove('show');
509          }
510 
511          // Reset button's accessible name
512          if (launcher) {
513            launcher.removeAttribute('aria-label');
514          }
515        }
516      </script>
517```
518 
519      **6. Focus Management:**
520      ```html
521      <!-- Chat popup with focus management -->
522      <div role="dialog"
523           aria-modal="true"
524           aria-labelledby="chat-heading"
525           class="chat-popup">
526        <div class="chat-header">
527          <h2 id="chat-heading">Chat Support</h2>
528          <button type="button"
529                  aria-label="Close chat"
530                  onclick="closeChat()">
531            ×
532          </button>
533        </div>
534 
535        <div class="chat-content" tabindex="-1">
536          <!-- Chat messages and input -->
537        </div>
538      </div>
539 
540      <script>
541        function openChat() {
542          const chatWindow = document.getElementById('chat-window');
543          const launcher = document.getElementById('chat-launcher');
544 
545          chatWindow.hidden = false;
546          launcher.setAttribute('aria-expanded', 'true');
547 
548          // Focus first focusable element in chat
549          const firstFocusable = chatWindow.querySelector('button, input, textarea');
550          if (firstFocusable) {
551            firstFocusable.focus();
552          }
553        }
554 
555        function closeChat() {
556          const chatWindow = document.getElementById('chat-window');
557          const launcher = document.getElementById('chat-launcher');
558 
559          chatWindow.hidden = true;
560          launcher.setAttribute('aria-expanded', 'false');
561 
562          // Return focus to launcher
563          launcher.focus();
564        }
565      </script>
566```
567 
568      **7. Session Timeout Management:**
569```html
570      <!-- Timeout warning -->
571      <div class="timeout-warning" hidden>
572        <p>This chat will end in <span id="timeout-countdown">20</span> seconds if you do not reply.</p>
573        <button type="button" onclick="extendSession()">Extend Session</button>
574      </div>
575 
576      <!-- Timeout alert for screen readers -->
577      <div role="alert" aria-live="assertive" class="timeout-alert" hidden>
578        This chat will end in 20 seconds if you do not reply.
579      </div>
580 
581      <script>
582        let sessionTimeout;
583        let warningTimeout;
584 
585        function startSessionTimer() {
586          // Start 5-minute session timer
587          sessionTimeout = setTimeout(() => {
588            showTimeoutWarning();
589          }, 280000); // 4 minutes 40 seconds
590        }
591 
592        function showTimeoutWarning() {
593          const warning = document.querySelector('.timeout-warning');
594          const countdown = document.getElementById('timeout-countdown');
595          const timeoutAlert = document.querySelector('.timeout-alert');
596 
597          warning.hidden = false;
598          timeoutAlert.hidden = false;
599 
600          // 20-second countdown
601          let timeLeft = 20;
602          const countdownInterval = setInterval(() => {
603            timeLeft--;
604            countdown.textContent = timeLeft;
605 
606            if (timeLeft <= 0) {
607              clearInterval(countdownInterval);
608              endSession();
609            }
610          }, 1000);
611        }
612 
613        function extendSession() {
614          // Set session as extended FIRST to prevent any race conditions
615          isSessionExtended = true;
616 
617          const warning = document.querySelector('.timeout-warning');
618          const timeoutAlert = document.querySelector('.timeout-alert');
619 
620          // Clear any existing warning timeout
621          if (warningTimeout) {
622            clearInterval(warningTimeout);
623            warningTimeout = null;
624          }
625 
626          // Clear the main session timeout as well
627          if (sessionTimeout) {
628            clearTimeout(sessionTimeout);
629            sessionTimeout = null;
630          }
631 
632          // Hide warning elements
633          if (warning) warning.hidden = true;
634          if (timeoutAlert) timeoutAlert.hidden = true;
635 
636          // Start fresh session timer
637          startSessionTimer();
638        }
639 
640        // Extend session on user interaction
641        function extendSessionOnInteraction() {
642          // Only extend if warning is currently showing
643          const warning = document.querySelector('.timeout-warning');
644          if (warning && !warning.hidden) {
645            extendSession();
646          } else {
647            // Just reset the session timer
648            clearTimeout(sessionTimeout);
649            clearInterval(warningTimeout); // Also clear any warning timeout that might be running
650            isSessionExtended = true; // Mark session as extended
651            startSessionTimer();
652          }
653        }
654 
655        // Monitor input for activity
656        document.getElementById('message-input').addEventListener('input', () => {
657          // Reset timer on any input
658          clearTimeout(sessionTimeout);
659          startSessionTimer();
660        });
661 
662        // Setup comprehensive user interaction monitoring
663        function setupUserInteractionListeners() {
664          const chatWindow = document.getElementById('chat-window');
665 
666          // Add listeners for various user interactions
667          chatWindow.addEventListener('click', extendSessionOnInteraction);
668          chatWindow.addEventListener('keydown', extendSessionOnInteraction);
669          chatWindow.addEventListener('keypress', extendSessionOnInteraction);
670          chatWindow.addEventListener('input', extendSessionOnInteraction);
671          chatWindow.addEventListener('scroll', extendSessionOnInteraction);
672 
673          // Also listen for focus events on interactive elements
674          const interactiveElements = chatWindow.querySelectorAll('button, input, textarea, [tabindex]:not([tabindex="-1"])');
675          interactiveElements.forEach(element => {
676            element.addEventListener('focus', extendSessionOnInteraction);
677          });
678        }
679      </script>
680```
681 
682      **Note:** The timeout warning should appear with sufficient notice (minimum 30 seconds) and use a dedicated `role="alert"` element for screen reader announcements. This ensures important timeout information is properly communicated without interfering with chat functionality.
683 
684      **8. User Interaction Monitoring:**
685```javascript
686      // Setup comprehensive user interaction monitoring
687      function setupUserInteractionListeners() {
688        const chatWindow = document.getElementById('chat-window');
689 
690        // Add listeners for various user interactions
691        chatWindow.addEventListener('click', extendSessionOnInteraction);
692        chatWindow.addEventListener('keydown', extendSessionOnInteraction);
693        chatWindow.addEventListener('keypress', extendSessionOnInteraction);
694        chatWindow.addEventListener('input', extendSessionOnInteraction);
695        chatWindow.addEventListener('scroll', extendSessionOnInteraction);
696 
697        // Also listen for focus events on interactive elements
698        const interactiveElements = chatWindow.querySelectorAll('button, input, textarea, [tabindex]:not([tabindex="-1"])');
699        interactiveElements.forEach(element => {
700          element.addEventListener('focus', extendSessionOnInteraction);
701        });
702      }
703```
704 
705      **Note:** Chat sessions should extend on any user interaction, not just sent messages. This is crucial for assistive technology users who may have difficulty typing or need more time to compose messages. Monitor clicks, key presses, input changes, scrolling, and focus events to ensure the session remains active during user engagement.
706 
707      **Important:** When extending sessions, ensure both the main session timeout and warning timeout are properly cleared to prevent race conditions where the session can end even after being extended.
708 
709      **Session State Management:** Use a dedicated boolean flag (`isSessionExtended`) to track session extension state, rather than relying on DOM element visibility. This prevents race conditions and ensures reliable session management.
710 
711      **Race Condition Prevention:** Set the session extension flag BEFORE clearing timeouts to prevent race conditions where the countdown might still call `endSession()` after the session has been extended.
712 
713      **Countdown Safety:** Implement proper bounds checking to prevent negative countdown values and ensure the countdown stops immediately when the session is extended. Clear existing intervals before starting new ones to prevent multiple countdowns from running simultaneously.
714 
715      **Session Ending Protection:** Implement multiple safety checks in the `endSession()` function to prevent premature session termination. Check session extension status, session activity state, and warning visibility before allowing the session to end.
716 
717      **Visual Design Consistency:** Follow the established design pattern used across all accessibility example files, including consistent container styling, typography, color scheme, and layout structure for a cohesive user experience.
718 
719      **9. Responsive Chat Design:**
720```css
721      /* Responsive chat window */
722      .chat-window {
723        position: fixed;
724        bottom: 20px;
725        right: 20px;
726        width: 350px;
727        height: 500px;
728        max-width: calc(100vw - 40px);
729        max-height: calc(100vh - 40px);
730        background: white;
731        border: 1px solid #ccc;
732        border-radius: 8px;
733        box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
734        display: flex;
735        flex-direction: column;
736      }
737 
738      /* Mobile responsive adjustments */
739      @media screen and (max-width: 480px) {
740        .chat-window {
741          bottom: 0;
742          right: 0;
743          width: 100%;
744          height: 100vh;
745          max-width: none;
746          max-height: none;
747          border-radius: 0;
748        }
749      }
750 
751      /* Ensure minimum width compliance */
752      @media screen and (max-width: 320px) {
753        .chat-window {
754          width: 320px;
755          min-width: 320px;
756        }
757      }
758```
759 
760      **10. Screen Reader Optimized Messages:**
761```html
762      <!-- Message with proper structure -->
763      <div class="message agent" role="article">
764        <div class="message-content">
765          <span class="sr-only">Customer Support: </span>
766          Hi, how can I help you today?
767        </div>
768        <time datetime="2024-01-15T10:30:00Z" class="timestamp">
769          <span class="sr-only">Message sent at </span>
770          10:30 AM
771        </time>
772      </div>
773 
774      <!-- Typing indicator -->
775      <div class="typing-indicator" aria-live="polite">
776        <span class="visually-hidden">Customer Support is typing</span>
777        <span class="typing-dots">...</span>
778      </div>
779```
780 
781      **11. Proper Focus Trap Implementation:**
782```javascript
783      // Focus trap variables
784      let focusableElements = [];
785      let firstFocusableElement = null;
786      let lastFocusableElement = null;
787 
788      // Setup focus trap
789      function setupFocusTrap() {
790        const chatWindow = document.getElementById('chat-window');
791 
792        // Get all focusable elements within the chat window
793        // Include all interactive elements that can receive focus
794        focusableElements = chatWindow.querySelectorAll(
795          'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"]), [role="button"]:not([disabled])'
796        );
797 
798        if (focusableElements.length > 0) {
799          firstFocusableElement = focusableElements[0];
800          lastFocusableElement = focusableElements[focusableElements.length - 1];
801 
802          // Add focus trap event listener
803          chatWindow.addEventListener('keydown', trapFocus);
804        }
805      }
806 
807      // Focus trap functionality
808      function trapFocus(event) {
809        if (event.key === 'Tab') {
810          // Check if focus is currently within the chat window
811          const chatWindow = document.getElementById('chat-window');
812          const isFocusInChat = chatWindow.contains(document.activeElement);
813 
814          if (event.shiftKey) {
815            // Shift + Tab: move backwards
816            if (document.activeElement === firstFocusableElement) {
817              event.preventDefault();
818              lastFocusableElement.focus();
819            }
820          } else {
821            // Tab: move forwards
822            if (document.activeElement === lastFocusableElement) {
823              event.preventDefault();
824              firstFocusableElement.focus();
825            }
826          }
827 
828          // Additional safety check: if focus somehow escapes, bring it back
829          if (!isFocusInChat && focusableElements.length > 0) {
830            event.preventDefault();
831            firstFocusableElement.focus();
832          }
833        }
834      }
835 
836      // Clean up focus trap when closing chat
837      function closeChat() {
838        const chatWindow = document.getElementById('chat-window');
839        const launcher = document.getElementById('chat-launcher');
840 
841        chatWindow.hidden = true;
842        launcher.setAttribute('aria-expanded', 'false');
843 
844        // Remove focus trap
845        chatWindow.removeEventListener('keydown', trapFocus);
846 
847        // Return focus to launcher
848        launcher.focus();
849      }
850```
851 
852      **JavaScript Considerations:**
853      - Implement proper focus management for popup windows
854      - Handle keyboard navigation (Tab, Enter, Escape)
855      - Manage session timeouts with user notifications
856      - Provide pause/stop controls for auto-updating content
857      - Update page titles for new message notifications
858      - Monitor input activity for session extension
859      - Handle focus restoration when chat closes
860      - Implement proper ARIA live regions for status updates
861 
862      **Accessibility Notes:**
863      - Use role="log" for message history with aria-labelledby
864      - Provide multi-sensory notifications for new messages
865      - Maintain chronological message order in DOM
866      - Ensure all interactive elements have accessible names
867      - Test with screen readers for proper announcement
868      - Consider user preferences for notification levels
869      - Provide alternatives to chat (phone, email, etc.)
870      - Test keyboard navigation thoroughly
871      - Validate focus management in popup windows
872      - Use div elements for chat messages to reduce navigation noise (avoid role="article")
873      - Chat messages are conversational content, not standalone articles
874 
875      **Testing Requirements:**
876      - Test with screen readers (NVDA, JAWS, VoiceOver)
877      - Verify keyboard navigation works completely
878      - Test focus management in popup windows
879      - Validate message reading order
880      - Test timeout notifications and extensions
881      - Verify responsive design on small screens
882      - Test with different notification preferences
883      - Validate ARIA live region announcements
884      - Test focus restoration when chat closes
885      - Verify contrast ratios meet WCAG requirements
886      - **Test focus trapping thoroughly:** Verify Tab and Shift+Tab navigation stays within chat window
887      - **Test focus escape scenarios:** Ensure focus cannot accidentally leave the chat window
888      - **Test focus restoration:** Verify focus returns to launcher when chat closes
889      - **Test all interactive elements:** Ensure all buttons, inputs, and focusable elements are included in focus trap
890 
891      **Common Mistakes to Avoid:**
892      - Chat messages in wrong DOM order
893      - Notifications relying only on sound
894      - Missing keyboard support for chat functions
895      - Poor focus management in popup windows
896      - Missing author identification in messages
897      - Chat windows not responsive to small screens
898      - Missing timeout warnings and extensions
899      - Auto-updating content without pause controls
900      - Focus becoming obscured behind chat windows
901      - Missing accessible names for chat controls
902      - Chat buttons without proper roles
903      - Missing expandable state management
904      - Insufficient contrast for message text
905      - Chat icons without alt text
906      - Missing status message roles
907      - Missing aria-haspopup="dialog" on chat launcher
908      - Missing focus trapping in chat popup windows
909      - Poor focus management when opening/closing chat
910      - **Incomplete focus trap implementation:** Focus trap that only works in one direction (Tab vs Shift+Tab)
911      - **Missing focusable elements:** Focus trap that doesn't include all interactive elements
912      - **Focus escape vulnerabilities:** Focus trap without safety checks to prevent focus from leaving chat window
913      - **Incorrect ARIA attributes for modal dialogs:** Using aria-controls or aria-expanded with modal dialog pattern
914      - **Missing notification context:** Not including unread message count in button's accessible name
915      - **Decorative images with alt text:** Including unnecessary alt text for decorative icons in buttons
916      - **Limited session extension:** Only extending chat session on sent messages instead of all user interactions
917      - **Missing user interaction monitoring:** Not monitoring clicks, key presses, scrolling, and focus events for session extension
918 
919metadata:
920  priority: high
921  version: 1.0
922</rule>
923description:
924globs:
925alwaysApply: false
926---
927