Cursor rule

1---
2description: Image alternative text accessibility compliance and WCAG 2.2 requirements
3globs: *.vue, *.jsx, *.tsx, *.html, *.php, *.js, *.ts, *.liquid, *.css, *.scss, *.sass, *.less
4alwaysApply: true
5---
6# Image Alt Text Accessibility Standards
7 
8Ensures images have appropriate alternative text following WCAG 2.2 requirements for informative, decorative, and functional images.
9 
10<rule>
11name: image_alt_text_accessibility_standards
12description: Enforce image alternative text accessibility standards per WCAG 2.2 requirements
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      # Missing alt attribute on img elements
21      - pattern: "<img[^>]*>"
22        pattern_negate: "alt=\"[^\"]*\""
23        message: "All img elements must have an alt attribute. Use alt=\"\" for decorative images or provide meaningful description for informative images."
24 
25      # Empty alt on informative images (likely missing description)
26      - pattern: "<img[^>]*alt=\"\"[^>]*>"
27        pattern_negate: "(aria-hidden=\"true\"|role=\"presentation\"|decorative|background)"
28        message: "Empty alt attributes should only be used for decorative images. Provide meaningful alt text for informative images."
29 
30      # SVG img missing alt attribute
31      - pattern: "<img[^>]*\\.svg[^>]*>"
32        pattern_negate: "alt=\"[^\"]+\""
33        message: "SVG images using img element must have alt attribute and role=\"img\"."
34 
35      # SVG img missing role attribute
36      - pattern: "<img[^>]*\\.svg[^>]*>"
37        pattern_negate: "role=\"img\""
38        message: "SVG images using img element must have role=\"img\" attribute."
39 
40      # Inline SVG missing text alternative
41      - pattern: "<svg[^>]*>"
42        pattern_negate: "(aria-label=\"[^\"]+\"|aria-labelledby=\"[^\"]+\"|<title>|<desc>)"
43        message: "Inline SVG elements must have text alternative via aria-label, aria-labelledby, or title/desc elements."
44 
45      # Decorative SVG missing aria-hidden
46      - pattern: "<svg[^>]*>"
47        pattern_negate: "(aria-hidden=\"true\"|aria-label|aria-labelledby|<title>|<desc>)"
48        message: "Decorative SVG elements must have aria-hidden=\"true\" to hide from assistive technology."
49 
50      # Informative SVG missing role and accessible name
51      - pattern: "<svg[^>]*>"
52        pattern_negate: "(role=\"img\"|aria-hidden=\"true\")"
53        message: "Informative SVG elements must have role=\"img\" and accessible name via aria-label, aria-labelledby, or title/desc elements."
54 
55      # SVG with role=\"img\" but missing accessible name
56      - pattern: "<svg[^>]*role=\"img\"[^>]*>"
57        pattern_negate: "(aria-label=\"[^\"]+\"|aria-labelledby=\"[^\"]+\"|<title>|<desc>)"
58        message: "SVG elements with role=\"img\" must have accessible name via aria-label, aria-labelledby, or title/desc elements."
59 
60      # Image links missing descriptive alt text
61      - pattern: "<a[^>]*>\\s*<img[^>]*>"
62        pattern_negate: "alt=\"[^\"]{10,}\""
63        message: "Image links should have descriptive alt text that describes the link destination."
64 
65      # Button/control images missing purpose description
66      - pattern: "<(button|input)[^>]*>\\s*<img[^>]*>"
67        pattern_negate: "alt=\"[^\"]{5,}\""
68        message: "Button/control images should have alt text describing the purpose or resulting action."
69 
70      # Background images with information missing alternative
71      - pattern: "background.*url.*\\.(jpg|jpeg|png|gif|svg|webp)"
72        pattern_negate: "(aria-label|role=\"img\"|alt=|title=)"
73        message: "Background images conveying information must have alternative text via visible text, aria-label, or role=\"img\"."
74 
75      # Active background images missing accessible name
76      - pattern: "<(a|button)[^>]*>\\s*<[^>]*background.*url"
77        pattern_negate: "(aria-label|aria-labelledby|title=)"
78        message: "Active elements with background images must have accessible name via aria-label or similar."
79 
80      # Images of text without justification
81      - pattern: "<img[^>]*alt=\"[^\"]*[A-Za-z]{10,}[^\"]*\"[^>]*>"
82        pattern_negate: "(logo|essential|font.*customizable|size.*customizable)"
83        message: "Images containing text should use real text unless essential (like logos) or font/size/color are customizable."
84 
85      # Alt text too long (over 250 characters)
86      - pattern: "alt=\"[^\"]{250,}\""
87        message: "Alternative text should be concise (no more than 250 characters). Consider using aria-describedby for longer descriptions."
88 
89      # Alt text includes unnecessary image identification
90      - pattern: "alt=\"[^\"]*(?:image of|picture of|graphic of|photo of|icon of)[^\"]*\""
91        message: "Avoid phrases like 'image of' or 'graphic of' in alt text. Screen readers already announce the element type."
92 
93      # Complex images missing extended description
94      - pattern: "<img[^>]*alt=\"[^\"]{50,}\"[^>]*>"
95        pattern_negate: "(aria-describedby|longdesc=)"
96        message: "Complex images with long alt text should have extended description via aria-describedby or longdesc."
97 
98      # Decorative images with unnecessary alt text
99      - pattern: "<img[^>]*alt=\"[^\"]+\"[^>]*>"
100        pattern_negate: "(informative|functional|link|button)"
101        message: "Consider using alt=\"\" for purely decorative images to avoid screen reader announcement."
102 
103  - type: suggest
104    message: |
105      **WCAG 2.2 Image Alt Text Requirements:**
106 
107      **Informative Images and Active Images (Links, Buttons, Controls):**
108      - **Required:** All images MUST have alternative text
109      - **Meaningful:** Alt text MUST accurately convey the image's purpose and author's intent
110      - **Concise:** Alt text SHOULD be no more than 250 characters
111      - **Avoid Redundancy:** Don't include words like "image of," "graphic of," etc.
112 
113      **Image Types and Requirements:**
114 
115      **1. Standard Images (<img>):**
116```html
117      <!-- Informative image -->
118      <img src="chart.png" alt="Sales increased 25% in Q3 compared to Q2">
119 
120      <!-- Decorative image -->
121      <img src="decorative-border.png" alt="" role="presentation">
122 
123      <!-- Image link -->
124      <a href="/products">
125        <img src="product-catalog.png" alt="Browse our complete product catalog">
126      </a>
127```
128 
129      **2. SVG Images:**
130```html
131      <!-- SVG as img -->
132      <img src="icon.svg" alt="Close dialog" role="img">
133 
134      <!-- Informative inline SVG -->
135      <svg role="img" aria-label="Settings icon" viewBox="0 0 24 24">
136        <path d="M12 15.5A3.5 3.5 0 0 1 8.5 12A3.5 3.5 0 0 1 12 8.5A3.5 3.5 0 0 1 15.5 12A3.5 3.5 0 0 1 12 15.5M19.43 12.97C19.47 12.65 19.5 12.33 19.5 12C19.5 11.67 19.47 11.34 19.43 11L21.54 9.37C21.73 9.22 21.78 8.95 21.66 8.73L19.66 5.27C19.54 5.05 19.27 4.96 19.05 5.05L16.56 6.05C16.04 5.66 15.5 5.32 14.87 5.07L14.5 2.42C14.46 2.18 14.25 2 14 2H10C9.75 2 9.54 2.18 9.5 2.42L9.13 5.07C8.5 5.32 7.96 5.66 7.44 6.05L4.95 5.05C4.73 4.96 4.46 5.05 4.34 5.27L2.34 8.73C2.22 8.95 2.27 9.22 2.46 9.37L4.57 11C4.53 11.34 4.5 11.67 4.5 12C4.5 12.33 4.53 12.65 4.57 12.97L2.46 14.63C2.27 14.78 2.22 15.05 2.34 15.27L4.34 18.73C4.46 18.95 4.73 19.03 4.95 18.95L7.44 17.94C7.96 18.34 8.5 18.68 9.13 18.93L9.5 21.58C9.54 21.82 9.75 22 10 22H14C14.25 22 14.46 21.82 14.5 21.58L14.87 18.93C15.5 18.68 16.04 18.34 16.56 17.94L19.05 18.95C19.27 19.03 19.54 18.95 19.66 18.73L21.66 15.27C21.78 15.05 21.73 14.78 21.54 14.63L19.43 12.97Z"/>
137      </svg>
138 
139      <!-- Decorative inline SVG -->
140      <svg aria-hidden="true" viewBox="0 0 24 24">
141        <path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-2 15l-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8l-9 9z"/>
142      </svg>
143 
144      <!-- SVG with title and desc -->
145      <svg role="img" aria-labelledby="chart-title chart-desc" viewBox="0 0 400 300">
146        <title id="chart-title">Monthly Sales Chart</title>
147        <desc id="chart-desc">Bar chart showing sales data for January through December 2023</desc>
148        <!-- SVG content -->
149      </svg>
150```
151 
152      **SVG Accessibility Requirements:**
153      SVGs must be properly categorized and labeled for accessibility:
154 
155      **1. Decorative SVGs:**
156      - Use `aria-hidden="true"` to hide from assistive technology
157      - No role or accessible name needed
158      - Examples: background patterns, visual dividers, purely aesthetic elements
159 
160      **2. Informative SVGs:**
161      - Use `role="img"` to identify as image
162      - Provide accessible name via `aria-label`, `aria-labelledby`, or `<title>`/`<desc>` elements
163      - Examples: icons with meaning, charts, diagrams, functional graphics
164 
165      **3. SVG Implementation Options:**
166```html
167      <!-- Option 1: aria-label (preferred for simple descriptions) -->
168      <svg role="img" aria-label="Close dialog" viewBox="0 0 24 24">
169        <path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/>
170      </svg>
171 
172      <!-- Option 2: title and desc elements (for complex descriptions) -->
173      <svg role="img" aria-labelledby="chart-title chart-desc" viewBox="0 0 400 300">
174        <title id="chart-title">Monthly Sales Chart</title>
175        <desc id="chart-desc">Bar chart showing sales data for January through December 2023</desc>
176        <!-- SVG content -->
177      </svg>
178 
179      <!-- Option 3: Decorative SVG -->
180      <svg aria-hidden="true" viewBox="0 0 24 24">
181        <path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-2 15l-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8l-9 9z"/>
182      </svg>
183```
184 
185      **3. Background Images:**
186```html
187      <!-- Informative background with visible text -->
188      <div class="hero-section" style="background-image: url('hero-bg.jpg')">
189        <h1>Welcome to Our Store</h1>
190        <p>Discover amazing products</p>
191      </div>
192 
193      <!-- Active background image -->
194      <button class="icon-button"
195              style="background-image: url('close-icon.svg')"
196              aria-label="Close dialog">
197      </button>
198 
199      <!-- Decorative background -->
200      <div class="decorative-bg" style="background-image: url('pattern.png')">
201        <!-- Content without alt text needed -->
202      </div>
203```
204 
205      **4. Complex Images with Extended Descriptions:**
206```html
207      <!-- Complex chart with extended description -->
208      <img src="complex-chart.png"
209           alt="Sales performance chart for 2023"
210           aria-describedby="chart-description">
211      <div id="chart-description" class="sr-only">
212        Detailed description: The chart shows quarterly sales data with Q1 at $2.3M,
213        Q2 at $2.8M, Q3 at $3.1M, and Q4 at $3.5M. The trend shows consistent
214        growth throughout the year with the highest growth in Q4.
215      </div>
216```
217 
218      **5. Button and Control Images:**
219```html
220      <!-- Button with image -->
221      <button aria-label="Add item to cart">
222        <img src="cart-icon.svg" alt="" role="presentation">
223      </button>
224 
225      <!-- Image button -->
226      <input type="image"
227             src="submit-button.png"
228             alt="Submit order"
229             aria-label="Submit your order">
230```
231 
232      **Alt Text Guidelines:**
233 
234      **Good Examples:**
235      - `alt="Company logo"` (for logos)
236      - `alt="Close dialog"` (for close buttons)
237      - `alt="Submit form"` (for submit buttons)
238      - `alt="Sales increased 25% in Q3"` (for charts)
239      - `alt="Product image: Red wireless headphones"` (for products)
240      - `alt="Team photo: 5 employees in office"` (for photos)
241 
242      **Avoid These:**
243      - `alt="Image of a chart"` (redundant)
244      - `alt="Click here"` (not descriptive)
245      - `alt="Picture of a button"` (unnecessary)
246      - `alt="Graphic showing data"` (too vague)
247 
248      **Decorative Images:**
249```html
250      <!-- Use empty alt for decorative images -->
251      <img src="decorative-border.png" alt="" role="presentation">
252 
253      <!-- Or use aria-hidden -->
254      <img src="background-pattern.png" alt="" aria-hidden="true">
255```
256 
257      **Images of Text:**
258```html
259      <!-- Avoid unless essential -->
260      <img src="company-slogan.png" alt="Innovation through excellence"
261           aria-label="Company slogan">
262 
263      <!-- Better: Use real text -->
264      <h2>Innovation through excellence</h2>
265```
266 
267      **CSS Considerations:**
268```css
269      /* Screen reader only class */
270      .sr-only {
271        position: absolute;
272        width: 1px;
273        height: 1px;
274        padding: 0;
275        margin: -1px;
276        overflow: hidden;
277        clip: rect(0, 0, 0, 0);
278        white-space: nowrap;
279        border: 0;
280      }
281 
282      /* Background image with fallback */
283      .hero-section {
284        background-image: url('hero-bg.jpg');
285        background-size: cover;
286        background-position: center;
287      }
288 
289      /* Ensure text over background images has sufficient contrast */
290      .hero-section h1 {
291        color: #ffffff;
292        text-shadow: 2px 2px 4px rgba(0, 0, 0, 0.7);
293      }
294```
295 
296      **Testing and Validation:**
297      - Test with screen readers (NVDA, JAWS, VoiceOver)
298      - Use browser dev tools to inspect alt attributes
299      - Validate with automated accessibility tools
300      - Test keyboard navigation for image links/buttons
301      - Verify contrast ratios for text over background images
302      - Check that decorative images don't announce to screen readers
303      - Test SVG accessibility with screen readers
304      - Verify decorative SVGs are hidden with aria-hidden="true"
305      - Check informative SVGs announce their accessible names
306      - Validate SVG role="img" and accessible name combinations
307 
308      **Common Mistakes to Avoid:**
309      - Missing alt attributes on informative images
310      - Using "image of" or "picture of" in alt text
311      - Providing alt text for decorative images
312      - Using images of text when real text would work
313      - Missing accessible names on image buttons
314      - Insufficient contrast for text over background images
315      - Not providing extended descriptions for complex images
316      - Missing aria-hidden="true" on decorative SVGs
317      - Missing role="img" on informative SVGs
318      - SVGs without accessible names or aria-hidden
319      - Using decorative SVGs without hiding from assistive technology
320 
321metadata:
322  priority: high
323  version: 1.0
324</rule>
325