docs(table): markup guidance (#1287)

* Adding accessible table markup to rh-table docs * Improvements to table's accessibility guidelines * docs: update elements/rh-table/docs/30-code.md * mend --------- Co-authored-by: Benny Powers - עם ישראל חי! <[email protected]> Co-authored-by: Brian Ferry <[email protected]>
RedHat-UX · Nov 27, 2023 · 858d737 · 858d737
1 parent 3a07782
commit 858d737
Show file tree

Hide file tree

Showing 2 changed files with 50 additions and 44 deletions.
diff --git a/elements/rh-table/docs/30-code.md b/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>

diff --git a/elements/rh-table/docs/40-accessibility.md b/elements/rh-table/docs/40-accessibility.md
@@ -8,12 +8,12 @@ Since tables are inherently complex HTML structures, they can create barriers fo
 
 - 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
 
-- Use `id` and `headers` attributes to associate data cells with their table headers
-- Add a `<caption>` element for brief descriptive text
-- Define sections with `thead` and `tbody` (and optionally `tfoot` for larger tables)
+- Define sections with `<thead>` and `<tbody>` (and optionally `<tfoot>` for larger tables)
 
 ### Example markup
 
@@ -66,40 +66,43 @@ 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>
@@ -134,6 +137,7 @@ Each cell includes enough spacing for selecting interactive elements.
 
 - No column title cells should be blank
 - 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' %}