docs(table): markup guidance

docs/_includes/accessibility/1.3.1-A.md

@@ -0,0 +1 @@
+- [SC 1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html) (Level A)

elements/rh-table/docs/30-code.md

@@ -2,6 +2,8 @@
 
 ## Usage
 
+{% alert state="warning", title="Warning" %} Ensure that the table follows the recommendations on the [accessibility tab](../accessibility) so that the table works with assistive technology. {% endalert %}
+
 ### Title
 
 Specify the title of the table using a `caption` element.
@@ -54,9 +56,9 @@ To enable sorting on a column, add an `rh-sort-button` as the last child of the
     </colgroup>
     <thead>
       <tr>
-        <th scope="col" data-label="Date">Date</th>
-        <th scope="col" data-label="Event">Event<rh-sort-button></rh-sort-button></th>
-        <th scope="col" data-label="Venue">Venue<rh-sort-button></rh-sort-button></th>
+        <th id="concerts-date" scope="col" data-label="Date">Date</th>
+        <th id="concerts-event" scope="col" data-label="Event">Event<rh-sort-button></rh-sort-button></th>
+        <th id="concerts-venue" scope="col" data-label="Venue">Venue<rh-sort-button></rh-sort-button></th>
       </tr>
     </thead>
     <!-- ...table data sortable by Event and Venue -->
@@ -81,26 +83,26 @@ Additional information about the data in the table should be slotted into the `s
     </colgroup>
     <thead>
       <tr>
-        <th scope="col" data-label="Date">Date</th>
-        <th scope="col" data-label="Event">Event<rh-sort-button></rh-sort-button></th>
-        <th scope="col" data-label="Venue">Venue<rh-sort-button></rh-sort-button></th>
+        <th id="concerts-date" scope="col" data-label="Date">Date</th>
+        <th id="concerts-event" scope="col" data-label="Event">Event<rh-sort-button></rh-sort-button></th>
+        <th id="concerts-venue" scope="col" data-label="Venue">Venue<rh-sort-button></rh-sort-button></th>
       </tr>
     </thead>
     <tbody>
       <tr>
-        <td data-label="Date">12 February</td>
-        <td data-label="Event">Waltz with Strauss</td>
-        <td data-label="Venue">Main Hall</td>
+        <td headers="concerts-date" data-label="Date">12 February</td>
+        <td headers="concerts-event" data-label="Event">Waltz with Strauss</td>
+        <td headers="concerts-venue" data-label="Venue">Main Hall</td>
       </tr>
       <tr>
-        <td data-label="Date">24 March</td>
-        <td data-label="Event">The Obelisks</td>
-        <td data-label="Venue">West Wing</td>
+        <td headers="concerts-date" data-label="Date">24 March</td>
+        <td headers="concerts-event" data-label="Event">The Obelisks</td>
+        <td headers="concerts-venue" data-label="Venue">West Wing</td>
       </tr>
       <tr>
-        <td data-label="Date">14 April</td>
-        <td data-label="Event">The What</td>
-        <td data-label="Venue">Main Hall</td>
+        <td headers="concerts-date" data-label="Date">14 April</td>
+        <td headers="concerts-event" data-label="Event">The What</td>
+        <td headers="concerts-venue" data-label="Venue">Main Hall</td>
       </tr>
     </tbody>
   </table>
@@ -122,26 +124,26 @@ Additional information about the data in the table should be slotted into the `s
     </colgroup>
     <thead>
       <tr>
-        <th scope="col" data-label="Date">Date</th>
-        <th scope="col" data-label="Event">Event<rh-sort-button></rh-sort-button></th>
-        <th scope="col" data-label="Venue">Venue<rh-sort-button></rh-sort-button></th>
+        <th id="concerts-date" scope="col" data-label="Date">Date</th>
+        <th id="concerts-event" scope="col" data-label="Event">Event<rh-sort-button></rh-sort-button></th>
+        <th id="concerts-venue" scope="col" data-label="Venue">Venue<rh-sort-button></rh-sort-button></th>
       </tr>
     </thead>
     <tbody>
       <tr>
-        <td data-label="Date">12 February</td>
-        <td data-label="Event">Waltz with Strauss</td>
-        <td data-label="Venue">Main Hall</td>
+        <td headers="concerts-date" data-label="Date">12 February</td>
+        <td headers="concerts-event" data-label="Event">Waltz with Strauss</td>
+        <td headers="concerts-venue" data-label="Venue">Main Hall</td>
       </tr>
       <tr>
-        <td data-label="Date">24 March</td>
-        <td data-label="Event">The Obelisks</td>
-        <td data-label="Venue">West Wing</td>
+        <td headers="concerts-date" data-label="Date">24 March</td>
+        <td headers="concerts-event" data-label="Event">The Obelisks</td>
+        <td headers="concerts-venue" data-label="Venue">West Wing</td>
       </tr>
       <tr>
-        <td data-label="Date">14 April</td>
-        <td data-label="Event">The What</td>
-        <td data-label="Venue">Main Hall</td>
+        <td headers="concerts-date" data-label="Date">14 April</td>
+        <td headers="concerts-event" data-label="Event">The What</td>
+        <td headers="concerts-venue" data-label="Venue">Main Hall</td>
       </tr>
     </tbody>
   </table>

elements/rh-table/docs/40-accessibility.md

@@ -1,3 +1,61 @@
+## Markup Guidance
+
+{% alert state="warning", title="Warning" %} Tables are strictly intended for tabular data, and should never be used for layout purposes. {% endalert %}
+
+Since tables are inherently complex HTML structures, they can create barriers for users and assistive technologies ([View WCAG guidelines](#web-content-accessibility-guidelines)) if their markup does not clearly define the relationships within the tabular data. Therefore, it is essential for tables to contain as much context as possible through the application of appropriate structural markup.
+
+### Minimum requirements
+
+- Column titles (or headers) must use `<th>` elements with `scope="col"` attributes
+- Row titles (or headers) must use `<th>` elements with `scope="row"` attributes
+- Use `id` and `headers` attributes to associate data cells with their table headers
+- Add a `<caption>` element to title a table and help users identify its purpose
+
+### Further guidance
+
+- Define sections with `<thead>` and `<tbody>` (and optionally `<tfoot>` for larger tables)
+
+### Example markup
+
+```html
+<rh-table>
+  <table>
+    <caption>
+      Concerts
+    </caption>
+    <colgroup>
+      <col>
+      <col>
+      <col>
+    </colgroup>
+    <thead>
+      <tr>
+        <th id="concerts-date" scope="col" data-label="Date">Date</th>
+        <th id="concerts-event" scope="col" data-label="Event">Event</th>
+        <th id="concerts-venue" scope="col" data-label="Venue">Venue</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td headers="concerts-date" data-label="Date">12 February</td>
+        <td headers="concerts-event" data-label="Event">Waltz with Strauss</td>
+        <td headers="concerts-venue" data-label="Venue">Main Hall</td>
+      </tr>
+      <tr>
+        <td headers="concerts-date" data-label="Date">24 March</td>
+        <td headers="concerts-event" data-label="Event">The Obelisks</td>
+        <td headers="concerts-venue" data-label="Venue">West Wing</td>
+      </tr>
+      <tr>
+        <td headers="concerts-date" data-label="Date">14 April</td>
+        <td headers="concerts-event" data-label="Event">The What</td>
+        <td headers="concerts-venue" data-label="Venue">Main Hall</td>
+      </tr>
+    </tbody>
+  </table>
+</rh-table>
+```
+
 ## Keyboard interactions
 
 If a table is in a container that can receive keyboard focus (e.g., with a `tabindex="0"` attribute), then a user can place focus on the container and scroll the table horizontally or vertically using the arrow keys.
@@ -8,45 +66,48 @@ If a table is in a container that can receive keyboard focus (e.g., with a `tabi
 
 <rh-table>
   <table>
+    <caption>
+      Keyboard interactions
+    </caption>
     <colgroup>
         <col style="width: 25%">
         <col />
     </colgroup>
     <thead>
       <tr>
-        <th data-label="Key" scope="col">Key</th>
-        <th data-label="Result" scope="col">Result</th>
+        <th id="keyboard-key" data-label="Key" scope="col">Key</th>
+        <th id="keyboard-result" data-label="Result" scope="col">Result</th>
       </tr>
     </thead>
     <tbody>
         <tr>
-            <td data-label="Key">Up Arrow</td>
-            <td data-label="Result">Moves the table view up</td>
+            <td headers="keyboard-key" data-label="Key">Up Arrow</td>
+            <td headers="keyboard-result" data-label="Result">Moves the table view up</td>
         </tr>
         <tr>
-            <td data-label="Key">Left Arrow</td>
-            <td data-label="Result">Moves the table view left</td>
+            <td headers="keyboard-key" data-label="Key">Left Arrow</td>
+            <td headers="keyboard-result" data-label="Result">Moves the table view left</td>
         </tr>
         <tr>
-            <td data-label="Key">Right Arrow</td>
-            <td data-label="Result">Moves the table view right</td>
+            <td headers="keyboard-key" data-label="Key">Right Arrow</td>
+            <td headers="keyboard-result" data-label="Result">Moves the table view right</td>
         </tr>
         <tr>
-            <td data-label="Key">Down Arrow</td>
-            <td data-label="Result">Moves the table view down</td>
+            <td headers="keyboard-key" data-label="Key">Down Arrow</td>
+            <td headers="keyboard-result" data-label="Result">Moves the table view down</td>
         </tr>
         <tr>
-            <td data-label="Key">Tab</td>
-            <td data-label="Result">Moves focus to next interactive element within a cell or outside of the table</td>
+            <td headers="keyboard-key" data-label="Key">Tab</td>
+            <td headers="keyboard-result" data-label="Result">Moves focus to next interactive element within a cell or outside of the table</td>
         </tr>
         <tr>
-            <td data-label="Key">Shift+Tab</td>
-            <td data-label="Result">Moves focus to previous interactive element within a cell or outside of the table</td>
+            <td headers="keyboard-key" data-label="Key">Shift+Tab</td>
+            <td headers="keyboard-result" data-label="Result">Moves focus to previous interactive element within a cell or outside of the table</td>
         </tr>
     </tbody>
   </table>
 </rh-table>
-    
+
 <!-- | Key {style="width: 25%" } | Result                                                                            |
 | ------------------------- | --------------------------------------------------------------------------------- |
 | Up Arrow                  | Moves the table view up                                                           |
@@ -75,14 +136,15 @@ Each cell includes enough spacing for selecting interactive elements.
 ## Additional guidelines
 
 - No column title cells should be blank
-- Column titles must use `<th>` elements with `scope="col"` attributes
 - Each cell should only have one piece of data
+- Avoid merged cells. When possible consider breaking a complex table into a series of simpler tables
 - Do not place multiple inactive elements in a single cell
 
 {% include 'accessibility/ariaguide.md' %}
 
 {% include 'accessibility/wcag.md' %}
+{% include 'accessibility/1.3.1-A.md' %}
 {% include 'accessibility/2.1.1-A.md' %}
 {% include 'accessibility/2.1.3-AAA.md' %}
 {% include 'accessibility/2.4.3-A.md' %}
-{% include 'accessibility/2.5.5-AAA.md' %}
+{% include 'accessibility/2.5.5-AAA.md' %}