Documentation/Tables need captions

Tables need captions

ZMD008

ZemDomu reports a supported <table> without a <caption>. Add a concise caption as the table's first child so readers can identify the table's purpose before navigating its data.

What this rule catches

  • Static <table> elements that do not contain a supported <caption> child.
  • Tables whose analyzed source omits the semantic caption element.

What static analysis cannot prove

  • Static analysis cannot judge whether a caption accurately summarizes the table or distinguish a layout table from a data table by intent.
  • It does not prove that headers, scope relationships, reading order, or complex table associations are correct.

Standards classification and detection confidence

Classification
advisory — A caption is a strong way to identify a data table, but WCAG does not require every table to use a caption element.
Detection confidence
high — The presence of a resolved caption child is deterministic. The rule cannot judge caption quality or whether the element represents a data table.

Applicable WCAG 2.2 criteria

Criterion 1.3.1 is relevant to programmatic table relationships; caption is one documented technique, not the only conformance path.

Normative means the rule checks a machine-testable part of a cited standards requirement. Advisory means it enforces a documented authoring convention or supporting technique. Neither classification makes a ZemDomu result proof of WCAG conformance.

Examples

✅ Good

<table>
  <caption>List of team members</caption>
  <tr><td>Jane</td><td>Doe</td></tr>
</table>

❌ Bad

<table>
  <tr><td>Jane</td><td>Doe</td></tr>
</table>

Quick summary

When: A <table> element lacks a <caption> child

Warning: <table> missing <caption>

Solution: Include a <caption> describing the table

Why it matters

Accessibility: Tables without captions provide no context for screen-reader users and break data navigation.

SEO: Omitting captions removes valuable descriptive keywords that aid search engine indexing of table data.

Rule details

In brief

  • Goal: Provide a programmatic title for data tables.
  • What to do: Include a <caption> as the first child of every <table>.
  • Why: Captions act like headings for tables, enabling screen-reader users to identify table purpose quickly.

Intent

Ensure data tables are self-describing, improving accessibility and maintenance.

Benefits

  • Screen-reader users can navigate directly to table captions and understand context.
  • Visual users see a clear title for complex tables, enhancing comprehension.
  • Search engines index caption text, boosting table visibility in search results.

Techniques

  • H39: Using caption elements to associate data table captions programmatically.
  • ARIA table: For non-standard tables, use role="table" and aria-labelledby referencing a caption element.

HTML Semantics

The HTML `<caption>` element defines a title for a table; it must be the first child of `<table>` to remain linked semantically.

References

Tips & edge cases

  • Keep captions short—treat them like table titles rather than descriptions of every cell.
  • Ensure each caption is unique on a page to prevent confusion among multiple tables.
  • When nesting tables in <figure>, consider <figcaption> instead of <caption> for authoring flexibility.

See also

Related guides

Last verified: