Cursor rule

1---
2description: Text and user interface color contrast compliance with WCAG 2.2 1.4.3 and 1.4.11
3globs: *.css, *.scss, *.sass, *.less, *.vue, *.jsx, *.tsx, *.html, *.php, *.js, *.ts
4alwaysApply: true
5---
6# Color Contrast Accessibility Standards
7 
8Ensures color contrast meets WCAG 2.2 1.4.3: Contrast (Minimum) and 1.4.11: Non-text Contrast requirements.
9 
10<rule>
11name: color_contrast_accessibility_standards
12description: Enforce color contrast accessibility standards per WCAG 2.2 1.4.3 and 1.4.11
13filters:
14  - type: file_extension
15    pattern: "\\.(css|scss|sass|less|vue|jsx|tsx|html|liquid|php|js|ts)$"
16 
17actions:
18  - type: enforce
19    conditions:
20      # Common low-contrast text color combinations
21      - pattern: "color:\\s*#[89abcdefABCDEF]{6}"
22        message: "Light text colors may not meet 4.5:1 contrast ratio requirement. Verify contrast against background."
23 
24      - pattern: "color:\\s*#[0-6]{6}"
25        message: "Very light text colors likely fail contrast requirements. Use darker colors for better accessibility."
26 
27      # Light gray text (common accessibility issue)
28      - pattern: "color:\\s*(#[cdefCDEF]{3,6}|lightgray|lightgrey|silver)"
29        message: "Light gray text often fails WCAG contrast requirements (4.5:1 minimum). Use darker colors."
30 
31      # Common problematic color combinations
32      - pattern: "background.*#fff.*color.*#[89abcdefABCDEF]"
33        message: "Light text on white background may not meet 4.5:1 contrast ratio requirement."
34 
35      - pattern: "background.*#f[0-9a-fA-F]{5}.*color.*#[89abcdefABCDEF]"
36        message: "Light text on light background may not meet contrast requirements."
37 
38      # UI component border/focus indicators
39      - pattern: "border.*#[cdefCDEF]{3,6}"
40        message: "Light borders may not meet 3:1 non-text contrast requirement for UI components."
41 
42      - pattern: "outline.*#[cdefCDEF]{3,6}"
43        message: "Light focus outlines may not meet 3:1 contrast requirement for UI component identification."
44 
45      # Button states with insufficient contrast
46      - pattern: "button.*background.*#[cdefCDEF]{3,6}"
47        message: "Light button backgrounds may not provide sufficient 3:1 contrast for UI component identification."
48 
49      # Form input borders
50      - pattern: "input.*border.*#[defDEF]{3,6}"
51        message: "Very light input borders may not meet 3:1 contrast requirement for form field identification."
52 
53      # SVG icon fill colors that may lack contrast
54      - pattern: "fill=\"#[cdefCDEF]{3,6}\""
55        message: "Light SVG fill colors may not meet 3:1 contrast requirement for icon identification."
56 
57      # SVG stroke colors for icon outlines
58      - pattern: "stroke=\"#[defDEF]{3,6}\""
59        message: "Very light SVG stroke colors may not provide sufficient contrast for icon visibility."
60 
61      # Missing prefers-contrast considerations
62      - pattern: "@media\\s*\\(prefers-contrast:\\s*more\\)"
63        pattern_negate: "color|background|border"
64        message: "prefers-contrast: more media query should include enhanced color/contrast properties."
65 
66  - type: suggest
67    message: |
68      **WCAG 2.2 Color Contrast Requirements:**
69 
70      **1.4.3: Text Contrast (Minimum) - Level AA:**
71      - **Normal Text:** Minimum 4.5:1 contrast ratio
72      - **Large Text:** Minimum 3:1 contrast ratio (18pt+ regular or 14pt+ bold)
73      - **Enhanced (Level AAA):** 7:1 for normal text, 4.5:1 for large text
74 
75      **1.4.11: Non-text Contrast - Level AA:**
76      - **UI Components:** Minimum 3:1 contrast ratio for component identification
77      - **Focus Indicators:** Minimum 3:1 contrast ratio for focus visibility
78      - **Graphical Objects:** Minimum 3:1 contrast ratio for content understanding
79 
80      **Exceptions (No Contrast Requirement):**
81      - Inactive/disabled UI components
82      - Pure decorative elements
83      - Text in logos or brand names
84      - Text that is not visible to users
85      - Graphics where specific presentation is essential
86 
87      **High Contrast Color Combinations:**
88 
89      **Dark Text on Light Backgrounds:**
90      - `#212529` on `#ffffff` - 16.6:1 ✅
91      - `#495057` on `#ffffff` - 8.3:1 ✅
92      - `#6c757d` on `#ffffff` - 5.4:1 ✅
93      - `#343a40` on `#f8f9fa` - 11.7:1 ✅
94 
95      **Light Text on Dark Backgrounds:**
96      - `#ffffff` on `#212529` - 16.6:1 ✅
97      - `#f8f9fa` on `#495057` - 7.0:1 ✅
98      - `#ffffff` on `#0056b3` - 7.7:1 ✅
99      - `#ffffff` on `#dc3545` - 5.8:1 ✅
100 
101      **UI Component Colors (3:1 minimum):**
102      - Focus outlines: `#0056b3`, `#dc3545`, `#198754`
103      - Border colors: `#ced4da`, `#adb5bd`, `#6c757d`
104      - Button states: `#0056b3`, `#157347`, `#b02a37`
105 
106      **Implementation Examples:**
107 
108      **CSS Text Contrast:**
109```css
110      /* Good: High contrast text */
111      .primary-text {
112        color: #212529;
113        background: #ffffff;
114      }
115 
116      .secondary-text {
117        color: #495057;
118        background: #ffffff;
119      }
120 
121      /* Good: Large text with 3:1 minimum */
122      .large-heading {
123        font-size: 18px;
124        font-weight: normal;
125        color: #6c757d;
126        background: #ffffff;
127      }
128```
129 
130      **CSS UI Component Contrast:**
131```css
132      /* Good: Form inputs with sufficient border contrast */
133      .form-control {
134        border: 2px solid #ced4da; /* 3:1+ contrast */
135        background: #ffffff;
136      }
137 
138      .form-control:focus {
139        border-color: #0056b3; /* High contrast focus */
140        outline: 3px solid #0056b3;
141        outline-offset: 2px;
142      }
143 
144      /* Good: Button states */
145      .btn-primary {
146        background: #0056b3;
147        color: #ffffff;
148        border: 1px solid #004085;
149      }
150```
151 
152      **Contrast Testing:**
153      - Use browser dev tools color picker for contrast ratios
154      - Test with tools like WebAIM Contrast Checker
155      - Verify with automated accessibility testing tools
156      - Test with actual users who have visual impairments
157 
158      **Common Problematic Combinations to Avoid:**
159      - Light gray text (#999999) on white backgrounds
160      - Yellow text (#ffff00) on white backgrounds
161      - Light blue links (#87ceeb) on white backgrounds
162      - Thin borders (#e0e0e0) for essential UI components
163      - Low contrast placeholder text
164      - Insufficient focus indicator contrast
165 
166      **Responsive Considerations:**
167      - Maintain contrast ratios across all screen sizes
168      - Consider dark mode color schemes
169      - Test contrast in different lighting conditions
170      - Ensure contrast is maintained with CSS filters/effects
171 
172      **CSS `prefers-contrast` Media Query:**
173      The `prefers-contrast` media query allows adaptation to user contrast preferences:
174 
175```css
176      /* Default styles */
177      .button {
178        background: #0056b3;
179        color: #ffffff;
180        border: 1px solid #004085;
181      }
182 
183      /* High contrast preference */
184      @media (prefers-contrast: more) {
185        .button {
186          background: #000000;
187          color: #ffffff;
188          border: 2px solid #ffffff;
189          font-weight: bold;
190        }
191 
192        .text-secondary {
193          color: #000000; /* Increase from gray to black */
194        }
195 
196        .form-control {
197          border: 3px solid #000000; /* Thicker, darker borders */
198        }
199      }
200 
201      /* Low contrast preference (rare) */
202      @media (prefers-contrast: less) {
203        .high-contrast-element {
204          /* Reduce contrast only where specifically needed */
205          /* Still maintain minimum WCAG requirements */
206        }
207      }
208 
209      /* Custom contrast preference */
210      @media (prefers-contrast: custom) {
211        /* Allow user-defined contrast settings */
212        /* Respect system/browser contrast customizations */
213      }
214```
215 
216      **Icon Accessibility & Contrast Requirements:**
217      Icons are UI components and must meet 3:1 contrast ratio for identification:
218 
219      **SVG Icon Examples:**
220```html
221      <!-- Good: High contrast icon -->
222      <svg width="24" height="24" viewBox="0 0 24 24"
223           aria-label="Close dialog" role="img">
224        <path fill="#212529"
225              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"/>
226      </svg>
227 
228      <!-- Good: Icon with sufficient background contrast -->
229      <button class="icon-button" aria-label="Save document">
230        <svg width="20" height="20" viewBox="0 0 24 24">
231          <path fill="#ffffff"
232                d="M17 3H5c-1.11 0-2 .9-2 2v14c0 1.1.89 2 2 2h14c1.11 0 2-.9 2-2V7l-4-4z"/>
233        </svg>
234      </button>
235 
236      /* CSS for icon button with 3:1 contrast */
237      .icon-button {
238        background: #0056b3; /* High contrast background */
239        border: 2px solid #004085; /* Visible border for component identification */
240        padding: 8px;
241        border-radius: 4px;
242      }
243 
244      .icon-button:focus {
245        outline: 3px solid #ffd700; /* High contrast focus indicator */
246        outline-offset: 2px;
247      }
248```
249 
250      **Icon Contrast Considerations:**
251      - **Informative Icons:** Must meet 3:1 contrast against background
252      - **Decorative Icons:** No contrast requirement (use `aria-hidden="true"`)
253      - **Icon Buttons:** Both icon and button background need sufficient contrast
254      - **State Icons:** Different states (active/inactive) need distinguishable contrast
255      - **Icon + Text:** Ensure both elements meet their respective requirements
256 
257      **Complex Icon Examples:**
258```css
259      /* Multi-state icon button */
260      .toggle-icon {
261        background: #f8f9fa;
262        border: 2px solid #6c757d; /* 3:1+ contrast for UI component */
263        color: #495057;
264      }
265 
266      .toggle-icon[aria-pressed="true"] {
267        background: #0056b3;
268        color: #ffffff;
269        border-color: #004085;
270      }
271 
272      /* Icon with adaptive contrast */
273      @media (prefers-contrast: more) {
274        .icon-subtle {
275          filter: contrast(150%); /* Increase icon contrast */
276        }
277 
278        .icon-button {
279          border-width: 3px; /* Thicker borders for better identification */
280        }
281      }
282```
283 
284      **Design System Approach:**
285      - Establish a palette of WCAG-compliant color combinations
286      - Document contrast ratios for all color pairs
287      - Create design tokens with built-in accessibility
288      - Implement automated contrast checking in build process
289      - Define icon contrast standards for different contexts
290      - Test icons across different contrast preferences
291 
292metadata:
293  priority: high
294  version: 1.0
295</rule>
296