mgifford/accessibility-skills/tables

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

Use tables for information whose meaning depends on relationships between rows and columns. Mark those relationships in HTML so users can identify the table, navigate its cells, and hear the relevant headers with each value. The complexity of the markup should match the complexity of the information — simplifying or splitting a table is often better than adding increasingly complicated header associations.

Never use tables for layout. Use CSS Grid/Flexbox instead. Do not turn a reading-oriented data table into an application-style grid (role="grid") unless users genuinely need spreadsheet-like keyboard interaction.

Severity Scale (this skill)

Choose the Correct Structure First

• A list — items that don't depend on column relationships
• A definition list — term/description pairs
• A data table — reading and comparing row-column data
• An ARIA grid/treegrid — only for an application-style composite widget

with cell navigation or editing

• CSS Grid/Flexbox — page layout

Do not use a table merely to align form fields, cards, images, or page regions.

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. Use <th> for cells that label a row, column, or group — never a bolded <td> as a visual substitute.

<table>
  <caption>Monthly sales by region, first quarter 2025</caption>
  <thead>
    <tr>
      <th scope="col">Region</th>
      <th scope="col">January</th>
      <th scope="col">February</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">North</th>
      <td>$12,400</td>
      <td>$14,200</td>
    </tr>
  </tbody>
</table>

For a small, unambiguous table with only one header row or column, browsers can sometimes infer header direction from <th> alone. Explicit scope="col"/scope="row" remains the dependable authoring convention, especially for large or similar-looking data. <thead>/<tbody>/<tfoot> support sticky headers, styling, scripting, and repeating headers in print — their presence does not by itself repair missing or incorrect header associations.

When a header row has an empty top-left corner cell (no header function), leave it as <td> — don't add filler text like "blank" just to occupy the cell.

Moderate: Captions and Table Names

<caption> is the native way to identify a table, especially with several tables on one page. WCAG does not require a caption in every case — an immediately associated heading or surrounding text can sometimes adequately identify a simple table. Treat <caption> as the preferred default, but don't force a duplicate name when another tested association already supplies one.

<table>
  <caption>2025 budget allocation by department</caption>
  <!-- header and data rows -->
</table>

The caption must be a direct child of <table> (before <thead>), concise and specific. For unusual structure, a short summary can explain row/column organization without repeating every value:

<caption>
  Availability of holiday accommodation
  <span class="table-summary">Locations form row groups. Property types form columns.</span>
</caption>

The obsolete HTML summary attribute on <table> should not be used — use visible caption content or a nearby description instead.

Serious: Spanned Headers — scope="colgroup" / scope="rowgroup"

Use colgroup/rowgroup scope values only when the corresponding group actually exists in the table structure (matching <colgroup> or <tbody> row group):

<table>
  <caption>Quarterly revenue by product line, CAD thousands</caption>
  <colgroup><col></colgroup>
  <colgroup span="2"></colgroup>
  <colgroup span="2"></colgroup>
  <thead>
    <tr>
      <th scope="col" rowspan="2">Product</th>
      <th scope="colgroup" colspan="2">First half</th>
      <th scope="colgroup" colspan="2">Second half</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>

For row groups spanning several rows, use scope="rowgroup" with rowspan on the group header. Test grouped headers with the project's actual AT combinations — if associations are difficult to understand, split into simpler tables rather than adding more complexity.

Serious: When to Use headers + id (Rarely)

Use only for tables so complex that scope causes headers to apply to the wrong cells:

<table>
  <caption>Accommodation availability</caption>
  <thead>
    <tr>
      <th id="location" scope="col">Location</th>
      <th id="studio" scope="col">Studio</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th id="paris" scope="row">Paris</th>
      <td headers="paris studio">11</td>
    </tr>
  </tbody>
</table>

Every ID must be unique in the document; every headers token must match a real header cell. Before reaching for `headers`/`id`, consider: splitting one table into several; transposing rows and columns; moving explanatory material outside the grid; reducing nested header levels; offering a filtered view. Even when technically correct, a table needing three or four headers read per cell may be functionally inaccessible in practice — per WebAIM, multiple levels of row/column headers are unlikely to be functionally understandable to a screen reader user. Validate headers/id associations after every schema or column change.

Serious: Empty, Missing, and Special Values

An empty cell is ambiguous — it can mean zero, not applicable, unknown, not reported, or intentionally blank. Use explicit text where the distinction matters: 0 for a measured zero; Not applicable; No data; Not reported; Suppressed for intentionally withheld values. Define shortened symbols (N/A, em dash) in the caption or a nearby note; prefer full text when space permits. Do not use   to make an empty cell appear occupied. Explain estimated/rounded/preliminary/revised values — don't rely on colour or typographic style alone to identify them.

Serious: Totals, Subtotals, and Footers

Mark total labels as headers when they identify the row's values:

<tfoot>
  <tr><th scope="row">Total</th><td>$21,500</td><td>$24,500</td></tr>
</tfoot>

Do not communicate subtotals only through bold text, indentation, or background colour — include visible text ("Subtotal") and preserve header associations. If a total is calculated dynamically, expose update status appropriately and ensure the exported value uses the same calculation.

Moderate: Responsive Tables and Reflow

WCAG 1.4.10 allows two-dimensional scrolling for content that genuinely requires it, including data tables — the exception applies to the table itself, not the surrounding page.

<div class="table-scroll" role="region" aria-labelledby="sales-caption" tabindex="0">
  <table>
    <caption id="sales-caption">Monthly sales by region</caption>
  </table>
</div>

.table-scroll { max-inline-size: 100%; overflow: auto; }
.table-scroll:focus-visible { outline: 3px solid currentColor; outline-offset: 3px; }

Use a labelled region when separate discoverability genuinely helps — don't turn every table wrapper into a landmark. Use tabindex="0" to make overflow keyboard-scrollable, with a visible focus indicator.

Avoid responsive CSS that changes `table`/`thead`/`tbody`/`tr`/`th`/`td` to `display: block` — browser/AT behavior varies and duplicated data-label content can drift out of sync with the real headers. When a card presentation is genuinely better on small screens, render a real alternative list or definition-list view from the same data — expose one view at a time, preserve all values and controls, and test both presentations. Test at 200%/400% zoom, long translated strings, and narrow viewports.

Moderate: Sticky Headers and Columns

thead th {
  position: sticky;
  inset-block-start: 0;
  background: var(--table-header-background);
  z-index: 1;
}

Keep the original semantic <th> elements — do not create focusable cloned headers. If a visual clone is unavoidable, hide it from AT and remove any duplicate IDs. Ensure sticky content doesn't obscure focus, headings, or the first data row. Test at high zoom and with text-spacing overrides.

Moderate: Sortable Columns

Put a native button inside each sortable column header; put aria-sort on the currently-sorted <th> only (not the button, not both):

<th scope="col" aria-sort="ascending">
  <button type="button">
    Last name
    <span class="sort-icon" aria-hidden="true">▲</span>
  </button>
</th>

When sorting changes: sort the complete dataset, not only the visible page, unless clearly stated otherwise; move aria-sort to the newly sorted <th>; use ascending/descending/other accurately; update the visible direction indicator without depending on colour alone; keep keyboard focus on the activated button; preserve header/data-cell associations. Do not replace the button with a click handler on <th> itself.

Moderate: Filtering, Search, and Result Counts

<form id="employee-filters">
  <label for="department-filter">Department</label>
  <select id="department-filter" name="department">
    <option value="">All departments</option>
  </select>
  <button type="submit">Apply filters</button>
</form>
<p id="employee-results" role="status" aria-atomic="true">Showing 24 employees.</p>

Update the visible result count after filtering; use role="status" when it changes without moving focus; keep active filters visible and programmatically determinable; provide a clear way to remove filters; make "No results" visible and announced. Do not announce every changed cell through a live region. Keep the caption accurate when scope/date range changes.

Moderate: Pagination and Large Datasets

Pagination is often more robust than rendering or virtualizing thousands of rows.

<nav aria-label="Employees table pages">
  <a href="?page=1" aria-current="page">1</a>
  <a href="?page=2" rel="next">Next</a>
</nav>

Identify the current page with aria-current="page"; use links for URL-based navigation, buttons for in-place state changes; preserve sort/filter parameters; state the displayed range and total ("Rows 51 to 100 of 842"); move focus only when predictable and helpful. "Load more" controls need a clear name, a result update, and predictable focus.