Cursor rule

1---
2description: Global scope accessibility standards per WCAG requirements for page language, viewport, title attributes, and skip links
3globs: *.vue, *.jsx, *.tsx, *.html, *.php, *.js, *.ts, *.liquid
4alwaysApply: true
5---
6 
7# Global Scope Accessibility Standards
8 
9Ensures global accessibility best practices are followed including page language, viewport meta tag, title attribute usage, and skip link implementation for WCAG compliance.
10 
11<rule>
12name: global_accessibility_standards
13description: Enforce global scope accessibility standards per WCAG requirements for page language, viewport, title attributes, and skip links
14filters:
15  - type: file_extension
16    pattern: "\\.(vue|jsx|tsx|html|liquid|php|js|ts)$"
17 
18actions:
19  - type: enforce
20    conditions:
21      # Missing lang attribute on html element
22      - pattern: "<html[^>]*>"
23        pattern_negate: "lang=\"[a-z]{2}(?:-[A-Z]{2})?\""
24        message: "HTML element must have lang attribute set to ensure proper pronunciation by assistive technology. Use lang=\"en\" for English or appropriate language code."
25 
26      # Invalid language code format
27      - pattern: "lang=\"[^a-z]{2}(?:-[^A-Z]{2})?\""
28        message: "Language code must follow ISO 639-1 format (e.g., lang=\"en\", lang=\"fr-CA\")."
29 
30      # Missing viewport meta tag
31      - pattern: "<head[^>]*>"
32        pattern_negate: "<meta[^>]*name=\"viewport\""
33        message: "Viewport meta tag is required for responsive design and accessibility. Include <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">."
34 
35      # Viewport meta tag preventing zoom
36      - pattern: "<meta[^>]*name=\"viewport\"[^>]*>"
37        pattern_negate: "(maximum-scale=1\\.0|user-scalable=no)"
38        message: "Viewport meta tag should not prevent zooming. Avoid maximum-scale=1.0 and user-scalable=no to maintain accessibility for low-vision users."
39 
40      # Problematic viewport attributes
41      - pattern: "(maximum-scale=1\\.0|user-scalable=no)"
42        message: "Viewport meta tag contains attributes that prevent zooming, which creates accessibility issues for low-vision users. Remove maximum-scale=1.0 and user-scalable=no."
43 
44      # Title attribute on non-iframe elements
45      - pattern: "(?i)<[^>]*title=\"[^\"]+\"[^>]*>"
46        pattern_negate: "(iframe|IFRAME)"
47        message: "Avoid using title attribute on non-iframe elements as it creates accessibility issues. Use visible text, aria-label, or custom tooltips instead."
48 
49      # Missing title on iframe elements
50      - pattern: "<iframe[^>]*>"
51        pattern_negate: "title=\"[^\"]+\""
52        message: "Iframe elements must have title attribute to provide context for screen reader users."
53 
54      # Empty or meaningless iframe title
55      - pattern: "<iframe[^>]*title=\"\\s*(?:iframe|frame|content|page)\\s*\"[^>]*>"
56        message: "Iframe title should be descriptive and meaningful, not generic terms like 'iframe' or 'content'."
57 
58      # Missing skip link
59      - pattern: "<body[^>]*>"
60        pattern_negate: "<a[^>]*href=\"#[^\"]*\"[^>]*(?:skip|main|content)"
61        message: "Skip link is required for keyboard navigation accessibility. Add a skip link at the top of the page to bypass repeated content."
62 
63      # Skip link not at top of page
64      - pattern: "<a[^>]*href=\"#[^\"]*\"[^>]*(?:skip|main|content)[^>]*>"
65        pattern_negate: "(<body|<header|<nav)"
66        message: "Skip link should be one of the first elements in the document, typically within the header or at the top of the body."
67 
68      # Skip link without proper target
69      - pattern: "<a[^>]*href=\"#[^\"]*\"[^>]*(?:skip|main|content)[^>]*>"
70        pattern_negate: "href=\"#(main|content|primary|skip-content)\""
71        message: "Skip link href should target main content area (e.g., href=\"#main\")."
72 
73      # Skip link target missing tabindex
74      - pattern: "<a[^>]*href=\"#(main|content|primary|skip-content)\"[^>]*>"
75        pattern_negate: "<(main|div|section)[^>]*id=\"(main|content|primary|skip-content)\"[^>]*tabindex=\"-1\""
76        message: "Skip link target element must have tabindex=\"-1\" to receive keyboard focus when skip link is activated."
77 
78      # Skip link without proper CSS classes
79      - pattern: "<a[^>]*href=\"#[^\"]*\"[^>]*(?:skip|main|content)[^>]*>"
80        pattern_negate: "(class=\"[^\"]*(?:visuallyhidden|sr-only|skip-link)[^\"]*\"|style=\"[^\"]*(?:position:\\s*absolute|clip:\\s*rect|overflow:\\s*hidden)[^\"]*\")"
81        message: "Skip link should have CSS classes or styles to hide it visually while keeping it accessible to screen readers and keyboard users."
82 
83      # Skip link not properly hidden
84      - pattern: "<a[^>]*href=\"#[^\"]*\"[^>]*(?:skip|main|content)[^>]*>"
85        pattern_negate: "(display:\\s*none|visibility:\\s*hidden)"
86        message: "Skip link should not use display:none or visibility:hidden as these hide it from screen readers. Use visuallyhidden or sr-only classes instead."
87 
88  - type: suggest
89    message: |
90      **Global Scope Accessibility Best Practices:**
91 
92      **1. Page Language (WCAG 3.1.1 Language of Page):**
93```html
94      <!-- Good: Proper language declaration -->
95      <!DOCTYPE html>
96      <html lang="en">
97        <head>
98          <title>Page Title</title>
99        </head>
100        <body>
101          <!-- Content in English -->
102        </body>
103      </html>
104 
105      <!-- Good: Language toggle with proper lang attributes -->
106      <nav>
107        <a href="/en" lang="en">English</a>
108        <a href="/fr" lang="fr">Français</a>
109      </nav>
110 
111      <!-- Good: Mixed language content -->
112      <p>Welcome to our site. <span lang="fr">Bienvenue sur notre site.</span></p>
113```
114 
115      **Language Code Requirements:**
116      - **Primary language:** Set on `<html>` element
117      - **Format:** ISO 639-1 (e.g., `lang="en"`, `lang="fr-CA"`)
118      - **Mixed content:** Use `lang` attribute on specific elements
119      - **Purpose:** Enables proper pronunciation by assistive technology
120 
121      **2. Viewport Meta Tag (WCAG 1.3.3 Sensory Characteristics):**
122```html
123      <!-- Good: Accessible viewport meta tag -->
124      <meta name="viewport" content="width=device-width, initial-scale=1.0">
125 
126      <!-- Good: With additional accessibility features -->
127      <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=0.5, maximum-scale=5.0">
128 
129      <!-- Bad: Prevents zooming (accessibility issue) -->
130      <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
131```
132 
133      **Viewport Requirements:**
134      - **Required:** Must be present for responsive design
135      - **Zoom support:** Must allow users to zoom content
136      - **Avoid:** `maximum-scale=1.0` and `user-scalable=no`
137      - **Purpose:** Enables low-vision users to zoom content
138 
139      **3. Title Attribute (General Avoidance):**
140```html
141      <!-- Bad: Title attribute on non-iframe elements -->
142      <button title="Click to submit form">Submit</button>
143      <a href="/help" title="Get help with your account">Help</a>
144 
145      <!-- Good: Visible text instead of title -->
146      <button>Submit form</button>
147      <a href="/help">Get help with your account</a>
148 
149      <!-- Good: Custom accessible tooltip -->
150      <button aria-describedby="submit-tooltip">Submit</button>
151      <div id="submit-tooltip" class="tooltip" role="tooltip">
152        Click to submit your form
153      </div>
154```
155 
156      **Title Attribute Guidelines:**
157      - **Avoid:** On interactive elements, links, buttons
158      - **Exception:** Required on iframe elements
159      - **Alternatives:** Visible text, aria-label, aria-describedby
160      - **Issues:** Mouse-only, screen reader redundancy, low-vision interference
161 
162      **4. Iframe Title Requirements:**
163```html
164      <!-- Good: Iframe with descriptive title -->
165      <iframe
166        src="https://example.com/embed"
167        title="Interactive map showing store locations across the city"
168        width="600"
169        height="400">
170      </iframe>
171 
172      <!-- Good: Iframe with meaningful title -->
173      <iframe
174        src="https://example.com/calendar"
175        title="Company event calendar for December 2024"
176        width="100%"
177        height="500">
178      </iframe>
179 
180      <!-- Bad: Generic or meaningless title -->
181      <iframe
182        src="https://example.com/embed"
183        title="iframe"
184        width="600"
185        height="400">
186      </iframe>
187```
188 
189      **Iframe Accessibility:**
190      - **Required:** Title attribute for context
191      - **Content:** Descriptive explanation of iframe purpose
192      - **Screen readers:** Need context before entering frame
193      - **Navigation:** Ctrl+Opt+Shift+Down to enter iframe (VoiceOver)
194 
195      **5. Skip Link Implementation (WCAG 2.4.1 Bypass Blocks):**
196```html
197      <!-- Good: Skip link at top of page -->
198      <body>
199        <a href="#main" class="skip-link visuallyhidden focusable">
200          Skip to main content
201        </a>
202 
203        <header>
204          <nav>
205            <!-- Navigation content -->
206          </nav>
207        </header>
208 
209        <main id="main" tabindex="-1">
210          <h1>Page Title</h1>
211          <!-- Main content -->
212        </main>
213      </body>
214```
215 
216      **Skip Link Requirements:**
217      - **Position:** First element in document (after body)
218      - **Target:** Main content area with matching ID
219      - **Focus:** Target element must have `tabindex="-1"`
220      - **Styling:** Hidden visually, visible on focus
221      - **Purpose:** Bypass repeated navigation content
222 
223      **6. Skip Link CSS Implementation:**
224```css
225      /* Visually hidden but accessible */
226      .visuallyhidden {
227        position: absolute;
228        width: 1px;
229        height: 1px;
230        padding: 0;
231        margin: -1px;
232        overflow: hidden;
233        clip: rect(0, 0, 0, 0);
234        white-space: nowrap;
235        border: 0;
236      }
237 
238      /* Show on focus for keyboard users */
239      .focusable:focus {
240        position: static;
241        width: auto;
242        height: auto;
243        padding: 8px 16px;
244        margin: 0;
245        overflow: visible;
246        clip: auto;
247        white-space: normal;
248        background: #000;
249        color: #fff;
250        text-decoration: none;
251        border-radius: 4px;
252        z-index: 1000;
253      }
254 
255      /* Alternative: Screen reader only class */
256      .sr-only {
257        position: absolute;
258        left: -10000px;
259        width: 1px;
260        height: 1px;
261        overflow: hidden;
262      }
263```
264 
265      **Skip Link Best Practices:**
266      - **Target elements:** `<main>`, `<h1>`, or main content container
267      - **Focus management:** Use `tabindex="-1"` on target
268      - **Visual feedback:** Show link when it receives focus
269      - **Positioning:** Place at very top of document
270      - **Text:** Clear and descriptive (e.g., "Skip to main content")
271 
272      **7. Complete Implementation Example:**
273```html
274      <!DOCTYPE html>
275      <html lang="en">
276        <head>
277          <meta charset="UTF-8">
278          <meta name="viewport" content="width=device-width, initial-scale=1.0">
279          <title>Accessible Web Page</title>
280          <style>
281            .skip-link {
282              position: absolute;
283              top: -40px;
284              left: 6px;
285              background: #000;
286              color: #fff;
287              padding: 8px;
288              text-decoration: none;
289              border-radius: 4px;
290              z-index: 1000;
291            }
292            .skip-link:focus {
293              top: 6px;
294            }
295          </style>
296        </head>
297        <body>
298          <!-- Skip link -->
299          <a href="#main" class="skip-link">Skip to main content</a>
300 
301          <!-- Header -->
302          <header role="banner">
303            <h1>Company Name</h1>
304            <nav role="navigation" aria-label="Primary">
305              <ul>
306                <li><a href="/">Home</a></li>
307                <li><a href="/about">About</a></li>
308                <li><a href="/contact">Contact</a></li>
309              </ul>
310            </nav>
311          </header>
312 
313          <!-- Main content -->
314          <main id="main" role="main" tabindex="-1">
315            <h2>Welcome to Our Site</h2>
316            <p>This is the main content area that the skip link targets.</p>
317 
318            <!-- Iframe example -->
319            <iframe
320              src="https://example.com/embed"
321              title="Interactive product demonstration video"
322              width="100%"
323              height="400">
324            </iframe>
325          </main>
326 
327          <!-- Footer -->
328          <footer role="contentinfo">
329            <p>&copy; 2024 Company Name</p>
330          </footer>
331        </body>
332      </html>
333```
334 
335      **Testing and Validation:**
336      - **Language:** Verify lang attribute is set correctly
337      - **Viewport:** Test zoom functionality on mobile devices
338      - **Title attributes:** Check for unnecessary usage on non-iframe elements
339      - **Iframe titles:** Verify descriptive titles for all iframes
340      - **Skip links:** Test keyboard navigation and focus management
341      - **Screen readers:** Verify skip link announces correctly
342      - **Focus order:** Ensure skip link target receives focus properly
343 
344      **Common Mistakes to Avoid:**
345      - Missing lang attribute on html element
346      - Viewport meta tag preventing zoom
347      - Using title attributes on interactive elements
348      - Missing or generic iframe titles
349      - Skip link not positioned at top of page
350      - Skip link target without tabindex="-1"
351      - Skip link hidden with display:none
352      - Skip link not visible on focus
353      - Generic skip link text
354      - Skip link targeting wrong element
355 
356metadata:
357  priority: high
358  version: 1.0
359</rule>
360