In order to be accessible to visually impaired users, it is important that tables provides a description of its content before the data is accessed.


The simplest way to do it, and also the one https://www.w3.org/TR/WCAG20-TECHS/H39[recommended by WCAG2] is to add a ``++<caption>++`` element inside the ``++<table>++``.


Other technics this rule accepts are:

* adding a concise description via https://www.w3.org/TR/wai-aria/#aria-label[``++aria-label++``] or https://www.w3.org/TR/wai-aria/#aria-labelledby[``++aria-labelledby++``] attributes in the ``++<table>++``.
* referencing a description element with an https://www.w3.org/TR/wai-aria/#aria-describedby[``++aria-describedby++``] attribute in the ``++<table>++``.
* embedding the ``++<table>++`` inside a ``++<figure>++`` which also contains a ``++<figcaption>++``.
* adding a ``++summary++`` attribute to the ``++<table>++`` tag. However note that this attribute has been deprecated in HTML5.

See https://www.w3.org/WAI/tutorials/tables/tips/[W3C WAI Web Accessibility Tutorials] for more information.


This rule raises an issue when a ``++<table>++`` has neither of the previously mentioned description mechanisms.


== Noncompliant Code Example

[source,html]
----
<table> <!-- Noncompliant -->
  ...
<table>
----


== Compliant Solution

Adding a ``++<caption>++`` element.

[source,html]
----
<table>
  <caption>New York City Marathon Results 2013</caption>
  ...
</table>
----
Adding an ``++aria-describedby++`` attribute.

[source,html]
----
<p id="mydesc">New York City Marathon Results 2013</p>
<table aria-describedby="mydesc">
  ...
</table>
----
Embedding the table in a ``++<figure>++`` which also contains a ``++<figcaption>++``.

[source,html]
----
<figure>
  <figcaption>New York City Marathon Results 2013</figcaption>
  <table>
    ...
  </table>
</figure>
----
Adding a ``++summary++`` attribute. However note that this attribute has been deprecated in HTML5.

[source,html]
----
<table summary="New York City Marathon Results 2013">
  ...
</table>
----


== 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"++``. Note that using ``++<table>++`` for layout purpose is a bad practice.


No issue will be raised either on ``++<table>++`` containing an ``++aria-hidden++`` attribute set to ``++"true"++``.


== See

* 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/H39[WCAG2, H39] - Using caption elements to associate data table captions with data tables


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

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

include::message.adoc[]

'''
== Comments And Links
(visible only on this page)

include::comments-and-links.adoc[]
endif::env-github,rspecator-view[]