| name | tables |
| description | Load this skill whenever the project contains HTML data tables (<table> elements). Under no circumstances use tables for layout purposes. Absolutely always include <th> elements with appropriate scope attributes, a <caption> or aria-labelledby, and ensure complex tables have headers associated with data cells. Apply these rules to every data table without exception.
|
Tables Accessibility Skill
Canonical source: examples/TABLES_ACCESSIBILITY_BEST_PRACTICES.md in mgifford/ACCESSIBILITY.md
This skill is derived from that file. When in doubt, the example is authoritative.
Apply these rules when creating or reviewing HTML data tables.
Only load this skill if the project contains data tables.
Core Mandate
Tables communicate relationships between data. Sighted users scan rows and columns
visually; screen reader users navigate cell by cell and rely on header announcements
for context. Without proper markup, every cell is an orphaned data point.
Never use tables for layout. Use CSS (Grid, Flexbox) instead.
Layout tables that remain in a codebase must have role="presentation" and
must linearise without loss of meaning.
Severity Scale (this skill)
| Level | Meaning |
|---|
| Critical | Table data is completely uninterpretable by screen reader users |
| Serious | Headers missing or misassociated; complex table with no navigation aid |
| Moderate | <caption> missing; zebra stripes lost in forced-colours without fallback |
| Minor | <thead>/<tbody> absent; summary attribute used (deprecated) |
Assistive Technology Context
Tables are rendered differently across AT combinations. Test with:
| AT | Browser | Notes |
|---|
| NVDA | Chrome | Reads headers on cell entry; table navigation via T key |
| JAWS | Chrome | Similar to NVDA; Ctrl+Alt+Arrow navigates cells |
| VoiceOver | Safari (macOS) | VO+Arrow navigates; announces scope-based headers reliably |
| VoiceOver | Safari (iOS) | Swipe navigation; complex tables challenging |
| TalkBack | Chrome (Android) | Linear reading; simpler tables work better |
| Voice Control | Any | Navigation by table elements less common; focus on operability |
| Screen magnification | Any | Wide tables require horizontal scroll — use responsive patterns |
| Reader Mode | Firefox/Edge/Safari | Strips CSS; table structure must be semantically meaningful |
| Edge Read Aloud | Edge | Reads table content linearly; <caption> helps orientation |
Reader Mode note: Firefox, Safari, and Edge all have reader modes that
reformat page content. Tables survive reader mode best when <caption> is
present and structure is simple. Complex multi-level tables may be stripped
or reflowed unexpectedly — provide a text summary for high-complexity tables.
Critical: Every Data Table Must Have <th> with scope
A table with only <td> cells is Critical — screen readers announce raw
data with no context about what each cell means.
All <th> elements must have a scope attribute. While screen readers
may infer col or row from layout, explicit scope is unambiguous and
required for reliable AT support.
Simple table — one set of column headers
<table>
<caption>Monthly sales by region, Q1 2024</caption>
<thead>
<tr>
<th scope="col">Region</th>
<th scope="col">January</th>
<th scope="col">February</th>
<th scope="col">March</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">North</th>
<td>$12,400</td>
<td>$14,200</td>
<td>$16,800</td>
</tr>
<tr>
<th scope="row">South</th>
<td>$9,100</td>
<td>$10,300</td>
<td>$11,900</td>
</tr>
</tbody>
</table>
scope="col" on column headers; scope="row" on row headers.
When both are present, the screen reader announces both before the data cell.
Critical: <caption> on Every Data Table
A table without <caption> is Moderate in isolation but Serious when
multiple tables appear on one page — users cannot distinguish which table they
are in. Make <caption> a universal requirement.
<table>
<caption>2024 budget allocation by department</caption>
…
</table>
<caption> is the first child of <table> — before <thead>. It is
announced by screen readers when the user enters the table. It also helps
users in Reader Mode identify the table's purpose after CSS is stripped.
Serious: Spanned Headers — scope="colgroup" / scope="rowgroup"
When a header spans multiple columns or rows, use colgroup or rowgroup
scope values:
<table>
<caption>Quarterly revenue by product line (USD thousands)</caption>
<thead>
<tr>
<th scope="col" rowspan="2">Product</th>
<th scope="colgroup" colspan="2">H1</th>
<th scope="colgroup" colspan="2">H2</th>
</tr>
<tr>
<th scope="col">Q1</th>
<th scope="col">Q2</th>
<th scope="col">Q3</th>
<th scope="col">Q4</th>
</tr>
</thead>
<tbody>
<tr>
<th scope="row">Hardware</th>
<td>1,200</td>
<td>1,450</td>
<td>1,100</td>
<td>1,800</td>
</tr>
</tbody>
</table>
Test spanned tables with NVDA+Chrome and JAWS+Chrome — some screen readers
still handle complex spanned headers inconsistently. If testing reveals problems,
simplify the table structure before reaching for headers/id.
Serious: When to Use headers + id (Rarely)
The headers and id approach associates individual cells with specific
header cells by ID reference. Use it only for tables so complex that
scope causes headers to apply to the wrong cells.
<table>
<caption>Staff schedules by shift and department</caption>
<tr>
<th id="dept">Department</th>
<th id="am">AM shift</th>
<th id="pm">PM shift</th>
</tr>
<tr>
<th id="nursing">Nursing</th>
<td headers="nursing am">8</td>
<td headers="nursing pm">6</td>
</tr>
</table>
Caution: Even when headers/id is technically correct, a table complex
enough to need it may be functionally inaccessible — reading three or four
headers before each cell is confusing in practice. Prefer simplifying the table.
Per WebAIM: "If there are multiple levels of row and/or column headers being
read, it will not likely be functionally accessible or understandable to a
screen reader user."
Moderate: <thead>, <tbody>, <tfoot>
These semantic elements have no direct AT benefit on their own, but <thead>
enables display: table-header-group in print CSS, repeating column headers
on every printed page — important for multi-page tables.
<table>
<caption>…</caption>
<thead>
<tr><th scope="col">…</th></tr>
</thead>
<tbody>
<tr><td>…</td></tr>
</tbody>
<tfoot>
<tr><td colspan="4">Total: $45,600</td></tr>
</tfoot>
</table>
Moderate: Responsive Tables
Wide tables require horizontal scrolling for low-vision users who zoom.
Always wrap tables in a scrollable container — never clip overflow silently:
<div role="region"
aria-labelledby="table-caption-id"
tabindex="0"
style="overflow-x: auto;">
<table>
<caption id="table-caption-id">Monthly sales by region</caption>
…
</table>
</div>
tabindex="0" makes the scroll container keyboard-focusable so keyboard users
can scroll it. role="region" + aria-labelledby announces it as a landmark.
For small screens, consider a card-based alternative layout via CSS:
@media (max-width: 600px) {
table, thead, tbody, th, td, tr { display: block; }
thead tr { position: absolute; top: -9999px; left: -9999px; }
td::before {
content: attr(data-label) ": ";
font-weight: bold;
}
}
When using the card pattern, add data-label attributes to each <td>:
<td data-label="Region">North</td>
<td data-label="January">$12,400</td>
Moderate: Sortable Columns
Interactive sortable columns must be keyboard operable and announce state:
<th scope="col">
<button type="button"
aria-sort="ascending"
aria-label="Sort by Region, currently ascending">
Region
<svg aria-hidden="true" focusable="false"></svg>
</button>
</th>
aria-sort values: ascending, descending, none, other.
Place aria-sort on the <th>, not the <button> — or on both if needed
for maximum AT compatibility. Test with NVDA and JAWS; announcement varies.
Moderate: Colour in Tables
Zebra stripes (alternating row backgrounds) are a common pattern that vanishes
in forced-colours mode and when printing with backgrounds off:
@media print {
tbody tr { border-bottom: 1px solid #333; }
}
@media (forced-colors: active) {
tbody tr { border-bottom: 1px solid CanvasText; }
}
Never use background colour alone to convey meaning (e.g., red rows = overdue).
Always pair colour with a text label or icon.
Layout Tables — What to Do With Them
Layout tables in legacy codebases must be marked to remove them from table
navigation mode:
<table role="presentation">
</table>
role="presentation" removes table semantics from the AT tree. The content
must still linearise logically when read top-to-bottom, left-to-right.
Verify by disabling CSS and reading the page linearly.
CMS and Framework Notes
Drupal: The CKEditor rich text editor in Drupal includes a table plugin.
Configure it to require <caption> and scope attributes via editor configuration.
The Drupal Accessibility Coding Standards
require WCAG 2.1 AA compliance for contributed modules and themes — table
markup in contrib must follow these rules.
WordPress, other CMS: Block editors often generate tables without <caption>
or scope. Audit CMS-generated table markup and configure the editor or post-process
the output to add missing attributes.
Generated tables (charts/dashboards): When JS libraries generate tables
from data (e.g., DataTables.js, AG Grid), verify the library outputs <th scope="col">,
<caption>, and <thead>. Many do not by default — check configuration options.
Definition of Done Checklist
Key WCAG Criteria
- 1.3.1 Info and Relationships (A) — Critical if headers absent
- 1.3.2 Meaningful Sequence (A) — table must linearise logically
- 1.4.1 Use of Color (A) — colour not sole encoding in table cells
- 2.1.1 Keyboard (A) — sortable columns keyboard operable
References
Standards horizon: These rules target WCAG 2.2 AA. No significant changes
to table accessibility requirements are anticipated in WCAG 3.0.
Monitor: https://www.w3.org/TR/wcag-3.0/
