Cursor rule

1---
2description: Enforce product media gallery component accessibility standards and proper landmark structure for media galleries
3globs: *.vue, *.jsx, *.tsx, *.html, *.php, *.js, *.ts, *.liquid
4alwaysApply: false
5---
6 
7# Product Media Gallery Component Accessibility Standards
8 
9Ensures product media gallery components follow WCAG compliance and provide proper accessibility for image, video, and 3D model galleries with screen reader support and keyboard navigation.
10 
11<rule>
12name: product_media_gallery_accessibility_standards
13description: Enforce product media gallery component accessibility standards and proper landmark structure for media galleries
14filters:
15  - type: file_extension
16    pattern: "\\.(vue|jsx|tsx|html|liquid|php|js|ts)$"
17 
18actions:
19  - type: enforce
20    conditions:
21      # Missing gallery container landmark role
22      - pattern: "(?i)<(div|section)[^>]*(?:gallery|media.*gallery|product.*gallery)[^>]*>"
23        pattern_negate: "role=\"region\""
24        message: "Product media gallery containers must have role='region' to provide proper landmark structure."
25 
26      # Missing gallery landmark aria-labelledby
27      - pattern: "(?i)<[^>]*role=\"region\"[^>]*(?:gallery|media.*gallery|product.*gallery)[^>]*>"
28        pattern_negate: "aria-labelledby=\"[^\"]+\""
29        message: "Gallery region must have aria-labelledby referencing a heading element for proper screen reader identification."
30 
31      # Missing gallery landmark heading
32      - pattern: "(?i)<[^>]*role=\"region\"[^>]*(?:gallery|media.*gallery|product.*gallery)[^>]*>"
33        pattern_negate: "<h[1-6][^>]*id=\"[^\"]+\"[^>]*>"
34        message: "Gallery region must contain a heading element with unique ID for aria-labelledby reference."
35 
36      # Missing gallery viewer container
37      - pattern: "(?i)<[^>]*role=\"region\"[^>]*(?:gallery|media.*gallery|product.*gallery)[^>]*>"
38        pattern_negate: "<(div|section)[^>]*(?:viewer|display|main.*image)[^>]*>"
39        message: "Gallery region must contain a gallery viewer container for displaying selected media."
40 
41      # Gallery viewer missing proper image alt text
42      - pattern: "(?i)<img[^>]*(?:gallery|viewer|main.*image)[^>]*>"
43        pattern_negate: "alt=\"[^\"]+\""
44        message: "Gallery viewer images must have descriptive alt text via alt attribute for screen reader accessibility."
45 
46      # Hidden media not properly hidden from assistive technology
47      - pattern: "(?i)<(img|video|iframe)[^>]*(?:gallery|media)[^>]*>"
48        pattern_negate: "(hidden|aria-hidden=\"true\"|display.*none|visibility.*hidden)"
49        message: "Hidden media items must use hidden attribute to remove them from both visual and assistive technology access."
50 
51      # Thumbnail buttons missing button element structure
52      - pattern: "(?i)<(div|span)[^>]*(?:thumbnail|thumb)[^>]*>"
53        pattern_negate: "(<button|role=\"button\")"
54        message: "Thumbnail media selectors must use button elements or have role='button' for proper keyboard accessibility."
55 
56      # Thumbnail buttons missing descriptive aria-label
57      - pattern: "(?i)<button[^>]*(?:thumbnail|thumb)[^>]*>"
58        pattern_negate: "aria-label=\"[^\"]*[Ll]oad[^\"]*[Mm]edia[^\"]*[Gg]allery[^\"]*[Vv]iewer[^\"]*\""
59        message: "Thumbnail buttons must have descriptive aria-label like 'Load media 1 into gallery viewer' for screen reader context."
60 
61      # Missing aria-current on active thumbnail
62      - pattern: "(?i)<button[^>]*(?:thumbnail|thumb)[^>]*>"
63        pattern_negate: "aria-current=\"(true|false)\""
64        message: "Thumbnail buttons must have aria-current attribute to indicate which media is currently loaded in the viewer."
65 
66      # Missing aria-describedby on thumbnail buttons
67      - pattern: "(?i)<button[^>]*(?:thumbnail|thumb)[^>]*>"
68        pattern_negate: "aria-describedby=\"[^\"]+\""
69        message: "Thumbnail buttons must have aria-describedby referencing the underlying media ID for alt text context."
70 
71      # Missing aria-controls on thumbnail buttons
72      - pattern: "(?i)<button[^>]*(?:thumbnail|thumb)[^>]*>"
73        pattern_negate: "aria-controls=\"[^\"]+\""
74        message: "Thumbnail buttons must have aria-controls referencing the gallery viewer container ID."
75 
76      # Missing live region for media loading announcements
77      - pattern: "(?i)<(div|section)[^>]*(?:gallery|media.*gallery|product.*gallery)[^>]*>"
78        pattern_negate: "role=\"status\""
79        message: "Gallery must include a live region with role='status' for announcing media loading completion to screen readers."
80 
81      # Live region with unnecessary aria-hidden attribute
82      - pattern: "(?i)<[^>]*role=\"status\"[^>]*(?:gallery|media)[^>]*aria-hidden=\"true\"[^>]*>"
83        message: "Gallery live region should not use aria-hidden='true' when content is dynamically managed through JavaScript."
84 
85      # Live region with redundant aria-live attribute
86      - pattern: "(?i)<[^>]*role=\"status\"[^>]*aria-live=\"[^\"]*\"[^>]*>"
87        message: "Live regions with role='status' should not include aria-live attribute as it's redundant and unnecessary."
88 
89      # Live region with unnecessary aria-hidden attribute
90      - pattern: "(?i)<[^>]*role=\"status\"[^>]*aria-hidden=\"true\"[^>]*>"
91        message: "Live regions with role='status' should not use aria-hidden='true' when content is dynamically managed through JavaScript."
92 
93      # Missing list structure for thumbnail grid layout
94      - pattern: "(?i)<(div|section)[^>]*(?:thumbnail|thumb)[^>]*>"
95        pattern_negate: "(<ul|<ol|<li)"
96        message: "Desktop thumbnail layouts should use list structure (ul/ol/li) to convey the number of available media items."
97 
98      # Mobile slider missing navigation controls
99      - pattern: "(?i)<(div|section)[^>]*(?:mobile.*slider|slider.*mobile|thumbnail.*slider)[^>]*>"
100        pattern_negate: "(previous|next|arrow|navigation)"
101        message: "Mobile thumbnail sliders must include previous/next navigation controls for accessing hidden thumbnails."
102 
103      # Mobile slider missing proper hiding of off-screen content
104      - pattern: "(?i)<(div|section)[^>]*(?:mobile.*slider|slider.*mobile|thumbnail.*slider)[^>]*>"
105        pattern_negate: "(hidden|aria-hidden=\"true\"|display.*none)"
106        message: "Mobile slider content not currently visible must be hidden from both visual and assistive technology access."
107 
108      # Zoom button missing proper labeling
109      - pattern: "(?i)<button[^>]*(?:zoom|expand|enlarge)[^>]*(?:gallery|viewer)[^>]*>"
110        pattern_negate: "aria-label=\"[^\"]*[Zz]oom[^\"]*[Ii]mage[^\"]*\""
111        message: "Gallery zoom buttons must have aria-label='Zoom image' for proper screen reader identification."
112 
113      # Zoom button missing modal functionality
114      - pattern: "(?i)<button[^>]*(?:zoom|expand|enlarge)[^>]*(?:gallery|viewer)[^>]*>"
115        pattern_negate: "(onClick|onclick|@click|v-on:click|role=\"button\")"
116        message: "Gallery zoom buttons must have proper click handlers to launch modal windows for expanded viewing."
117 
118      # Zoom button missing aria-haspopup
119      - pattern: "(?i)<button[^>]*(?:zoom|expand|enlarge)[^>]*(?:gallery|viewer)[^>]*>"
120        pattern_negate: "aria-haspopup=\"dialog\""
121        message: "Gallery zoom buttons must have aria-haspopup='dialog' to indicate they open a dialog popup."
122 
123      # Missing focus management for media changes
124      - pattern: "(?i)<button[^>]*(?:thumbnail|thumb)[^>]*>"
125        pattern_negate: "(onClick|onclick|@click|v-on:click)"
126        message: "Thumbnail buttons must have click handlers to load media into the gallery viewer and manage focus appropriately."
127 
128      # Missing focus restoration on modal close
129      - pattern: "(?i)<button[^>]*(?:close|dismiss)[^>]*(?:modal|dialog)[^>]*>"
130        pattern_negate: "(onClick|onclick|@click|v-on:click)"
131        message: "Modal close buttons should have proper click handlers to close the dialog and restore focus to the activator."
132 
133      # Gallery viewer missing proper ID for aria-controls reference
134      - pattern: "(?i)<(div|section)[^>]*(?:viewer|display|main.*image)[^>]*>"
135        pattern_negate: "id=\"[^\"]+\""
136        message: "Gallery viewer container must have unique ID for aria-controls reference from thumbnail buttons."
137 
138      # Thumbnail media missing proper ID for aria-describedby reference
139      - pattern: "(?i)<(img|video|iframe)[^>]*(?:thumbnail|thumb)[^>]*>"
140        pattern_negate: "id=\"[^\"]+\""
141        message: "Thumbnail media items must have unique IDs for aria-describedby reference from thumbnail buttons."
142 
143  - type: suggest
144    message: |
145      **Product Media Gallery Component Accessibility Best Practices:**
146 
147      **1. Gallery Container Structure:**
148```html
149      <!-- Gallery region landmark -->
150      <div role="region" aria-labelledby="gallery-heading" class="product-gallery">
151        <h2 id="gallery-heading" class="visually-hidden">Gallery Viewer</h2>
152        <!-- Gallery viewer for main media display -->
153        <div id="gallery-viewer" class="gallery-viewer">
154          <img src="product-1.jpg"
155               alt="Product front view showing design details"
156               class="main-image">
157 
158          <!-- Optional zoom button -->
159          <button type="button"
160                  class="zoom-button"
161                  aria-label="Zoom image"
162                  aria-haspopup="dialog"
163                  onclick="openImageModal()">
164            <svg aria-hidden="true" width="24" height="24">
165              <!-- Zoom icon -->
166            </svg>
167          </button>
168        </div>
169 
170        <!-- Thumbnail navigation -->
171        <div class="thumbnail-section">
172          <ul class="thumbnail-list">
173            <li>
174              <button type="button"
175                      class="thumbnail-button"
176                      aria-label="Load media 1 into gallery viewer"
177                      aria-current="true"
178                      aria-describedby="media-1"
179                      aria-controls="gallery-viewer"
180                      onclick="loadMedia(1)">
181                <img src="product-1-thumb.jpg"
182                     id="media-1"
183                     alt="Product front view thumbnail"
184                     class="thumbnail-image">
185              </button>
186            </li>
187            <li>
188              <button type="button"
189                      class="thumbnail-button"
190                      aria-label="Load media 2 into gallery viewer"
191                      aria-current="false"
192                      aria-describedby="media-2"
193                      aria-controls="gallery-viewer"
194                      onclick="loadMedia(2)">
195                <img src="product-2-thumb.jpg"
196                     id="media-2"
197                     alt="Product side view thumbnail"
198                     class="thumbnail-image">
199              </button>
200            </li>
201          </ul>
202        </div>
203 
204        <!-- Live region for announcements -->
205        <div class="visually-hidden"
206             role="status"
207             id="gallery-announcement">
208        </div>
209      </div>
210```
211 
212      **2. JavaScript Media Loading Function:**
213```javascript
214      function loadMedia(mediaIndex) {
215        const galleryViewer = document.getElementById('gallery-viewer');
216        const thumbnailButtons = document.querySelectorAll('.thumbnail-button');
217        const announcement = document.getElementById('gallery-announcement');
218 
219        // Update aria-current states
220        thumbnailButtons.forEach((button, index) => {
221          button.setAttribute('aria-current', index === mediaIndex - 1 ? 'true' : 'false');
222        });
223 
224        // Load new media into viewer
225        const newMedia = getMediaByIndex(mediaIndex);
226        galleryViewer.innerHTML = `
227          <img src="${newMedia.src}"
228               alt="${newMedia.alt}"
229               class="main-image">
230          <button type="button"
231                  class="zoom-button"
232                  aria-label="Zoom image"
233                  onclick="openImageModal()">
234            <svg aria-hidden="true" width="24" height="24">
235              <!-- Zoom icon -->
236            </svg>
237          </button>
238        `;
239 
240        // Announce media change
241        announcement.textContent = `Media ${mediaIndex} is now available in gallery view`;
242 
243        // Hide announcement after 3 seconds
244        setTimeout(() => {
245          announcement.textContent = '';
246        }, 3000);
247 
248        // Maintain focus on thumbnail button
249        event.target.focus();
250      }
251```
252 
253      **3. Unified Thumbnail System Implementation:**
254```html
255      <!-- Single thumbnail list for both desktop and mobile -->
256      <div class="thumbnail-container">
257        <button type="button"
258                class="slider-nav prev"
259                aria-label="Previous thumbnails"
260                onclick="slideThumbnails('prev')">
261          <svg aria-hidden="true" viewBox="0 0 24 24">
262            <path d="M15.41 7.41L14 6l-6 6 6 6 1.41-1.41L10.83 12z"/>
263          </svg>
264        </button>
265 
266        <ul class="thumbnail-list" id="thumbnails">
267          <li>
268            <button type="button"
269                    class="thumbnail-button"
270                    aria-label="Load media 1 into gallery viewer"
271                    aria-current="true"
272                    aria-describedby="media-1"
273                    aria-controls="gallery-viewer"
274                    onclick="loadMedia(1)">
275              <img src="product-1-thumb.jpg"
276                   id="media-1"
277                   alt="Product front view thumbnail"
278                   class="thumbnail-image">
279            </button>
280          </li>
281          <li>
282            <button type="button"
283                    class="thumbnail-button"
284                    aria-label="Load media 2 into gallery viewer"
285                    aria-current="false"
286                    aria-describedby="media-2"
287                    aria-controls="gallery-viewer"
288                    onclick="loadMedia(2)">
289              <img src="product-2-thumb.jpg"
290                   id="media-2"
291                   alt="Product side view thumbnail"
292                   class="thumbnail-image">
293            </button>
294          </li>
295          <!-- Additional thumbnails as needed -->
296        </ul>
297 
298        <button type="button"
299                class="slider-nav next"
300                aria-label="Next thumbnails"
301                onclick="slideThumbnails('next')">
302          <svg aria-hidden="true" viewBox="0 0 24 24">
303            <path d="M15.41 7.41L14 6l-6 6 6 6 1.41-1.41L10.83 12z"/>
304          </svg>
305        </button>
306      </div>
307```
308 
309      **4. CSS for Unified Thumbnail System:**
310```css
311      /* Thumbnail container with navigation */
312      .thumbnail-container {
313        position: relative;
314        display: flex;
315        align-items: center;
316        justify-content: center;
317        gap: 1rem;
318        max-width: 100%;
319      }
320 
321      /* Desktop grid layout */
322      .thumbnail-list {
323        display: grid;
324        grid-template-columns: repeat(auto-fit, minmax(80px, 1fr));
325        gap: 12px;
326        list-style: none;
327        margin: 0 auto;
328        padding: 0;
329        flex-wrap: wrap;
330        transition: transform 0.3s ease-in-out;
331        text-align: center;
332      }
333 
334      /* Mobile slider layout */
335      @media screen and (max-width: 749px) {
336        .thumbnail-container {
337          overflow: hidden;
338          padding: 0 50px;
339          display: flex;
340          align-items: center;
341          justify-content: center;
342        }
343 
344        .thumbnail-list {
345          flex-wrap: nowrap;
346          justify-content: center;
347          gap: 8px;
348          min-width: max-content;
349          transform: translateX(0);
350          position: relative;
351          left: 50%;
352          margin-left: -50%;
353        }
354 
355        .slider-nav {
356          display: block;
357          position: absolute;
358          top: 50%;
359          transform: translateY(-50%);
360          z-index: 2;
361        }
362 
363        .slider-nav.prev {
364          left: 0;
365        }
366 
367        .slider-nav.next {
368          right: 0;
369        }
370      }
371 
372      /* Hide navigation on desktop */
373      @media screen and (min-width: 750px) {
374        .slider-nav {
375          display: none;
376        }
377      }
378```
379 
380      **5. Modal Window Integration:**
381```javascript
382      function openImageModal() {
383        const galleryViewer = document.getElementById('gallery-viewer');
384        const currentImage = galleryViewer.querySelector('.main-image');
385        const zoomButton = document.querySelector('.zoom-button');
386 
387        // Create modal with current image
388        const modal = document.createElement('div');
389        modal.setAttribute('role', 'dialog');
390        modal.setAttribute('aria-modal', 'true');
391        modal.setAttribute('aria-labelledby', 'modal-title');
392        modal.className = 'image-modal';
393 
394        modal.innerHTML = `
395          <div class="modal-content">
396            <button type="button"
397                    class="close-button"
398                    aria-label="Close modal"
399                    onclick="closeImageModal()">
400              &times;
401            </button>
402            <h2 id="modal-title" class="visually-hidden">Product Image</h2>
403            <img src="${currentImage.src}"
404                 alt="${currentImage.alt}"
405                 class="modal-image">
406          </div>
407        `;
408 
409        document.body.appendChild(modal);
410 
411        // Focus management
412        const closeButton = modal.querySelector('.close-button');
413        closeButton.focus();
414 
415        // Trap focus within modal
416        trapFocus(modal);
417      }
418 
419      function closeImageModal() {
420        const modal = document.querySelector('.image-modal');
421        if (modal) {
422          // Restore focus to the zoom button
423          const zoomButton = document.querySelector('.zoom-button');
424          if (zoomButton) {
425            zoomButton.focus();
426          }
427          modal.remove();
428        }
429      }
430 
431      // Infinite loop thumbnail navigation
432      function slideThumbnails(direction) {
433        const thumbnailList = document.querySelector('#thumbnails');
434        const thumbnails = thumbnailList.querySelectorAll('li');
435        const visibleCount = 3; // Number of visible thumbnails on mobile
436        const thumbnailWidth = 68; // 60px width + 8px gap
437        const currentTransform = getComputedStyle(thumbnailList).transform;
438        const currentX = currentTransform === 'none' ? 0 : parseInt(currentTransform.split(',')[4]) || 0;
439 
440        let newX = currentX;
441 
442        if (direction === 'next') {
443          newX = currentX - (visibleCount * thumbnailWidth);
444        } else if (direction === 'prev') {
445          newX = currentX + (visibleCount * thumbnailWidth);
446        }
447 
448        // Infinite loop - wrap around when reaching the end
449        const totalWidth = thumbnails.length * thumbnailWidth;
450        if (newX <= -totalWidth) {
451          newX = 0;
452        } else if (newX > 0) {
453          newX = -totalWidth + (visibleCount * thumbnailWidth);
454        }
455 
456        thumbnailList.style.transform = `translateX(${newX}px)`;
457      }
458```
459 
460      **6. Accessibility Testing Checklist:**
461```javascript
462      function testGalleryAccessibility() {
463        const issues = [];
464 
465        // Check landmark structure
466        const galleryRegion = document.querySelector('[role="region"][aria-label*="Gallery"]');
467        if (!galleryRegion) {
468          issues.push('Missing gallery region landmark');
469        }
470 
471        // Check thumbnail button accessibility
472        const thumbnailButtons = document.querySelectorAll('.thumbnail-button');
473        thumbnailButtons.forEach((button, index) => {
474          if (!button.getAttribute('aria-label')) {
475            issues.push(`Thumbnail button ${index + 1} missing aria-label`);
476          }
477          if (!button.getAttribute('aria-describedby')) {
478            issues.push(`Thumbnail button ${index + 1} missing aria-describedby`);
479          }
480          if (!button.getAttribute('aria-controls')) {
481            issues.push(`Thumbnail button ${index + 1} missing aria-controls`);
482          }
483        });
484 
485        // Check live region
486        const liveRegion = document.querySelector('[role="status"]');
487        if (!liveRegion) {
488          issues.push('Missing live region for announcements');
489        }
490 
491        // Check image alt text
492        const images = document.querySelectorAll('img');
493        images.forEach((img, index) => {
494          if (!img.alt) {
495            issues.push(`Image ${index + 1} missing alt text`);
496          }
497        });
498 
499        return issues;
500      }
501```
502 
503      **Gallery Structure Requirements:**
504 
505      **Landmark Structure:**
506      - **role="region"**: On gallery container
507      - **aria-labelledby**: References heading ID for gallery identification
508      - **Heading element**: h2-h6 with unique ID for semantic structure
509      - **Proper heading hierarchy**: Use h2-h6 for gallery sections
510 
511      **Gallery Viewer:**
512      - **Unique ID**: For aria-controls reference
513      - **Alt text**: Descriptive alt text on main images
514      - **Zoom button**: Properly labeled with aria-label and aria-haspopup="dialog"
515      - **Focus management**: Maintain focus during media changes
516      - **Modal focus restoration**: Return focus to zoom button when modal closes
517 
518      **Thumbnail Navigation:**
519      - **Button elements**: Use native button or role="button"
520      - **Descriptive labels**: aria-label with "Load media X into gallery viewer"
521      - **State indication**: aria-current="true" for active media
522      - **Context information**: aria-describedby for media alt text
523      - **Control reference**: aria-controls for gallery viewer
524 
525      **Live Announcements:**
526      - **role="status"**: For live region functionality (no aria-live needed)
527      - **Dynamic content management**: JavaScript inserts/removes text content
528      - **No aria-hidden**: Content managed through JavaScript, not ARIA attributes
529      - **Timing control**: 3-second display before hiding
530 
531      **Mobile Responsiveness:**
532      - **Unified system**: Single thumbnail list for both desktop and mobile
533      - **Infinite loop navigation**: Previous/next controls with seamless wrapping
534      - **Smooth animations**: CSS transitions for thumbnail sliding
535      - **Responsive layout**: Grid on desktop, horizontal slider on mobile
536      - **Touch accessibility**: Proper touch targets and gestures
537 
538      **Modal Integration:**
539      - **Zoom functionality**: Button overlaid on gallery viewer
540      - **Modal compliance**: Follow modal accessibility standards
541      - **Focus management**: Proper focus trapping and restoration
542      - **Close controls**: Accessible close button with proper labeling
543 
544      **Testing and Validation:**
545      - Test with screen readers (NVDA, JAWS, VoiceOver)
546      - Verify landmark navigation works correctly
547      - Check thumbnail button announcements
548      - Test unified thumbnail system on both desktop and mobile
549      - Validate infinite loop navigation functionality
550      - Test smooth thumbnail sliding animations
551      - Validate modal window accessibility
552      - Ensure focus management works properly
553      - Test with keyboard-only navigation
554      - Verify responsive design across different screen sizes
555      - Test thumbnail center alignment on all devices
556 
557      **Common Mistakes to Avoid:**
558      - Missing role="region" on gallery container
559      - Incomplete aria-labelledby on gallery region
560      - Missing heading element with unique ID for aria-labelledby
561      - Missing alt text on gallery images
562      - Thumbnail buttons without proper button semantics
563      - Missing aria-current state management
564      - Incomplete aria-describedby references
565      - Missing aria-controls on thumbnail buttons
566      - Live region not properly managed
567      - Separate thumbnail systems for desktop and mobile (use unified system)
568      - Mobile slider without infinite loop navigation
569      - Zoom button without modal functionality
570      - Missing focus management during media changes
571      - Missing aria-haspopup="dialog" on zoom button
572      - Missing focus restoration when modal closes
573      - Redundant aria-live attribute on role="status" elements
574      - Unnecessary aria-hidden on dynamically managed live regions
575      - Missing smooth animations for thumbnail navigation
576      - Incomplete responsive design implementation
577 
578metadata:
579  priority: high
580  version: 1.0
581</rule>
582description:
583globs:
584alwaysApply: false
585---
586