rspec/rules/S5256/html/rule.adoc

== Why is this an issue?

Table headers are essential to enhance the accessibility of a table's data, particularly for assistive technologies like screen readers.
These headers provide the necessary context to transform data into information.
Without headers, users get rapidly lost in the flow of data.

This rule raises an issue whenever a `<table>` does not contain any `<th>` elements.

=== Exceptions

No issue will be raised on `<table>` used for layout purpose, i.e. when it contains a `role` attribute set to `"presentation"` or `"none"`.
[source,html]
----
<table role="presentation">
  <tr>
    <td>Name</td>
    <td>Age</td>
  </tr>
  <tr>
    <td>John Doe</td>
    <td>42</td>
  </tr>
</table>
----
Note that https://www.w3schools.com/html/html_layout.asp[using <table> for layout purpose is a bad practice].

No issue will be raised on `<table>` containing an `aria-hidden` attribute set to `"true"`.
[source,html]
----
<table aria-hidden="true">
  <tr>
    <td>Name</td>
    <td>Age</td>
  </tr>
  <tr>
    <td>John Doe</td>
    <td>42</td>
  </tr>
</table>
----

== How to fix it

The first `<tr>` of the table should contain `<th>` elements, with the appropriate description of what the data in those columns represents.

=== Going the extra mile

Headers should be properly associated with the corresponding `<td>` cells by using either a `scope` attribute or `headers` and `id` attributes.
See https://www.w3.org/WAI/tutorials/tables/tips/[W3C WAI Web Accessibility Tutorials] for more information.

=== Code examples

==== Noncompliant code example

[source,html,diff-id=1,diff-type=noncompliant]
----
<table> <!-- Noncompliant -->
  <tr>
    <td>Name</td>
    <td>Age</td>
  </tr>
  <tr>
    <td>John Doe</td>
    <td>24</td>
  </tr>
  <tr>
    <td>Alice Doe</td>
    <td>54</td>
  </tr>
</table>
----


==== Compliant solution

[source,html,diff-id=1,diff-type=compliant]
----
<table>
  <tr>
    <th scope="col">Name</th>
    <th scope="col">Age</th>
  </tr>
  <tr>
    <td>John Doe</td>
    <td>24</td>
  </tr>
  <tr>
    <td>Alice Doe</td>
    <td>54</td>
  </tr>
</table>
----

== Resources

=== Documentation

* https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0#qr-content-structure-separation-programmatic[WCAG2, 1.3.1] - Info and Relationships
* https://www.w3.org/TR/WCAG20-TECHS/H51[WCAG2, H51] - Using table markup to present tabular information

ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

Add "<th>" headers to this "<table>"


=== Highlighting

The opening <table> tag, without its content.


endif::env-github,rspecator-view[]