Cursor rule

1---
2description: Table element accessibility compliance
3globs: *.vue, *.jsx, *.tsx, *.html, *.php, *.js, *.ts, *.liquid
4alwaysApply: true
5---
6# Table Element Accessibility Standards
7 
8Ensures table elements follow WCAG compliance and provide proper structure for screen reader navigation and data relationships.
9 
10<rule>
11name: table_accessibility_standards
12description: Enforce table element accessibility standards per WCAG 1.3.1 Info and Relationships requirements
13filters:
14  - type: file_extension
15    pattern: "\\.(vue|jsx|tsx|html|liquid|php|js|ts)$"
16 
17actions:
18  - type: enforce
19    conditions:
20      # Table headers must use th elements
21      - pattern: "(?i)<table[^>]*>.*<td[^>]*>.*</td>.*<td[^>]*>.*</td>"
22        pattern_negate: "<th[^>]*>"
23        message: "Data tables must use th elements for headers. Use th for header cells and td for data cells."
24 
25      # Missing scope attribute on th elements
26      - pattern: "(?i)<th[^>]*>"
27        pattern_negate: "scope=\"(col|row|colgroup|rowgroup)\""
28        message: "Table header cells should have scope attribute set to 'col', 'row', 'colgroup', or 'rowgroup' for proper associations."
29 
30      # Data cells not associated with headers
31      - pattern: "(?i)<td[^>]*>"
32        pattern_negate: "(scope=\"(col|row)\"|headers=\"[^\"]+\"|<th[^>]*scope)"
33        message: "Table data cells must be associated with their corresponding header cells via scope or headers attributes."
34 
35      # Layout table with headers
36      - pattern: "(?i)<table[^>]*class=\"[^\"]*(?:layout|grid|position)[^\"]*\"[^>]*>"
37        pattern_negate: "(role=\"table\"|data-table)"
38        message: "Layout tables should not contain header elements. Use role='table' for data tables or remove headers from layout tables."
39 
40      # Missing caption or accessible name
41      - pattern: "(?i)<table[^>]*>"
42        pattern_negate: "(<caption|aria-label|aria-labelledby)"
43        message: "Data tables should have a caption element or aria-label/aria-labelledby for accessibility."
44 
45      # Empty caption
46      - pattern: "(?i)<caption[^>]*>\\s*</caption>"
47        message: "Table caption should contain meaningful text describing the table's purpose."
48 
49      # Generic caption text
50      - pattern: "(?i)<caption[^>]*>\\s*(table|data|information)\\s*</caption>"
51        message: "Table caption should be specific and descriptive, not generic."
52 
53      # Missing table structure elements
54      - pattern: "(?i)<table[^>]*>.*<tr[^>]*>.*<td[^>]*>"
55        pattern_negate: "(<thead|<tbody|<tfoot)"
56        message: "Complex tables should use thead, tbody, and tfoot elements for proper structure."
57 
58      # Incorrect role usage
59      - pattern: "(?i)role=\"(table|rowgroup|cell|columnheader|rowheader)\""
60        pattern_negate: "(<table|<tbody|<thead|<tfoot|<td|<th)"
61        message: "Table roles should only be used when native HTML table elements are not available."
62 
63      # Missing headers attribute for complex associations
64      - pattern: "(?i)<td[^>]*>"
65        pattern_negate: "(headers=\"[^\"]+\"|scope=\"(col|row)\")"
66        message: "Data cells in complex tables should have headers attribute referencing their associated header IDs."
67 
68      # Missing ID on header cells for headers attribute
69      - pattern: "(?i)<td[^>]*headers=\"[^\"]+\"[^>]*>"
70        pattern_negate: "<th[^>]*id=\"[^\"]+\"[^>]*>"
71        message: "Header cells referenced by headers attribute must have unique ID attributes."
72 
73      # Nested tables without proper isolation
74      - pattern: "(?i)<table[^>]*>.*<table[^>]*>"
75        pattern_negate: "(role=\"table\"|aria-label|aria-labelledby)"
76        message: "Nested tables should have proper accessible names and structure to avoid confusion."
77 
78      # Table without proper row structure
79      - pattern: "(?i)<table[^>]*>"
80        pattern_negate: "<tr[^>]*>"
81        message: "Tables must contain tr (table row) elements for proper structure."
82 
83      # Missing table role when using ARIA
84      - pattern: "(?i)role=\"(rowgroup|cell|columnheader|rowheader)\""
85        pattern_negate: "role=\"table\""
86        message: "When using table ARIA roles, the table element must have role='table'."
87 
88  - type: suggest
89    message: |
90      **WCAG 1.3.1 Table Accessibility Requirements:**
91 
92      **Table Headers:**
93      - **Header Tag:** Table headers MUST be designated with `th` elements
94      - **Meaningful Header:** Header text MUST accurately describe the category of corresponding data cells
95      - **Header Associations:** Data cells MUST be associated with their corresponding header cells
96      - **Scope Attribute:** Use `scope="col"` and `scope="row"` for simple tables
97      - **Complex Associations:** Use `headers` and `id` attributes for complex header relationships
98 
99      **Tabular Data:**
100      - **Tables:** Tabular data SHOULD be represented in a `table` element
101      - **Data Relationships:** WCAG 1.3.1 requires data to be associated with their labels
102 
103      **Caption Requirements:**
104      - **Caption:** Data tables SHOULD have a `caption` element or accessible name
105      - **Meaningful Caption:** Caption SHOULD describe the table's identity or purpose
106      - **Unique Caption:** Each table SHOULD have a unique caption within the page context
107 
108      **Layout Tables:**
109      - **Avoid Layout Tables:** Tables SHOULD NOT be used for purely visual layout
110      - **No Headers in Layout:** Layout tables MUST NOT contain header elements
111 
112      **HTML Markup Requirements:**
113      - **Native Elements:** Use semantic HTML `table`, `caption`, `tr`, `th`, `td`, `thead`, `tbody`, `tfoot`
114      - **ARIA Roles:** Only use table roles when native HTML is not available
115 
116      **Implementation Patterns:**
117 
118      **Basic Data Table:**
119```html
120      <table>
121        <caption>Monthly Sales Report - Q1 2024</caption>
122        <thead>
123          <tr>
124            <th scope="col">Month</th>
125            <th scope="col">Revenue</th>
126            <th scope="col">Units Sold</th>
127          </tr>
128        </thead>
129        <tbody>
130          <tr>
131            <td>January</td>
132            <td>$45,000</td>
133            <td>1,200</td>
134          </tr>
135          <tr>
136            <td>February</td>
137            <td>$52,000</td>
138            <td>1,350</td>
139          </tr>
140        </tbody>
141      </table>
142```
143 
144      **Complex Table with Multiple Headers:**
145```html
146      <table>
147        <caption>Product Performance by Region and Quarter</caption>
148        <thead>
149          <tr>
150            <th scope="col" rowspan="2">Product</th>
151            <th scope="colgroup" colspan="2">Q1 2024</th>
152            <th scope="colgroup" colspan="2">Q2 2024</th>
153          </tr>
154          <tr>
155            <th scope="col">North</th>
156            <th scope="col">South</th>
157            <th scope="col">North</th>
158            <th scope="col">South</th>
159          </tr>
160        </thead>
161        <tbody>
162          <tr>
163            <th scope="row">Widget A</th>
164            <td>150</td>
165            <td>200</td>
166            <td>175</td>
167            <td>225</td>
168          </tr>
169          <tr>
170            <th scope="row">Widget B</th>
171            <td>300</td>
172            <td>250</td>
173            <td>325</td>
174            <td>275</td>
175          </tr>
176        </tbody>
177      </table>
178```
179 
180      **Table with Headers Attribute:**
181```html
182      <table>
183        <caption>Employee Directory</caption>
184        <thead>
185          <tr>
186            <th id="name">Name</th>
187            <th id="department">Department</th>
188            <th id="email">Email</th>
189            <th id="phone">Phone</th>
190          </tr>
191        </thead>
192        <tbody>
193          <tr>
194            <td headers="name">John Smith</td>
195            <td headers="department">Engineering</td>
196            <td headers="email">john.smith@company.com</td>
197            <td headers="phone">555-0101</td>
198          </tr>
199          <tr>
200            <td headers="name">Jane Doe</td>
201            <td headers="department">Marketing</td>
202            <td headers="email">jane.doe@company.com</td>
203            <td headers="phone">555-0102</td>
204          </tr>
205        </tbody>
206      </table>
207```
208 
209      **ARIA Table (when native HTML not available):**
210```html
211      <div role="table" aria-label="Product Inventory">
212        <div role="rowgroup">
213          <div role="row">
214            <div role="columnheader" scope="col">Product</div>
215            <div role="columnheader" scope="col">Stock</div>
216            <div role="columnheader" scope="col">Price</div>
217          </div>
218        </div>
219        <div role="rowgroup">
220          <div role="row">
221            <div role="cell">Widget A</div>
222            <div role="cell">150</div>
223            <div role="cell">$25.00</div>
224          </div>
225          <div role="row">
226            <div role="cell">Widget B</div>
227            <div role="cell">200</div>
228            <div role="cell">$30.00</div>
229          </div>
230        </div>
231      </div>
232```
233 
234      **Table Structure Guidelines:**
235 
236      **Simple Tables:**
237      - Use `th` with `scope="col"` for column headers
238      - Use `th` with `scope="row"` for row headers
239      - Include meaningful `caption` element
240 
241      **Complex Tables:**
242      - Use `thead`, `tbody`, `tfoot` for structure
243      - Use `headers` and `id` attributes for complex associations
244      - Consider using `colgroup` and `rowgroup` for grouped headers
245 
246      **Layout Tables (Avoid):**
247```html
248      <!-- ❌ Bad: Using table for layout -->
249      <table>
250        <tr>
251          <td>Header</td>
252          <td>Content</td>
253        </tr>
254      </table>
255 
256      <!-- ✅ Good: Using CSS for layout -->
257      <div class="layout-container">
258        <header>Header</header>
259        <main>Content</main>
260      </div>
261```
262 
263      **Caption Best Practices:**
264```html
265      <!-- ✅ Good: Specific and descriptive -->
266      <table>
267        <caption>Monthly Sales Performance - Q1 2024</caption>
268        <!-- table content -->
269      </table>
270 
271      <!-- ❌ Bad: Generic caption -->
272      <table>
273        <caption>Data Table</caption>
274        <!-- table content -->
275      </table>
276```
277 
278      **Scope Attribute Usage:**
279```html
280      <!-- Column headers -->
281      <th scope="col">Product Name</th>
282      <th scope="col">Price</th>
283 
284      <!-- Row headers -->
285      <th scope="row">Widget A</th>
286      <th scope="row">Widget B</th>
287 
288      <!-- Group headers -->
289      <th scope="colgroup" colspan="2">Q1 2024</th>
290      <th scope="rowgroup" rowspan="3">Product Category</th>
291```
292 
293      **Testing and Validation:**
294      - Test with screen readers to verify header associations
295      - Verify table navigation works properly
296      - Check that captions are announced correctly
297      - Test keyboard navigation through table cells
298      - Validate scope attributes are used appropriately
299      - Ensure complex tables have proper header associations
300 
301      **Common Mistakes to Avoid:**
302      - Using `td` elements for headers instead of `th`
303      - Missing scope attributes on header cells
304      - Using tables for layout purposes
305      - Generic or meaningless captions
306      - Missing accessible names for tables
307      - Incorrect use of ARIA table roles
308      - Nested tables without proper isolation
309      - Missing header associations in complex tables
310      - Using layout tables with header elements
311 
312metadata:
313  priority: high
314  version: 1.0
315</rule>
316