docs(table): accessible markup guidelines (#1284)

Adding accessible table markup to rh-table docs

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/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
+
+### 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)
+
+### 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.
@@ -46,7 +104,7 @@ If a table is in a container that can receive keyboard focus (e.g., with a `tabi
     </tbody>
   </table>
 </rh-table>
-    
+
 <!-- | Key {style="width: 25%" } | Result                                                                            |
 | ------------------------- | --------------------------------------------------------------------------------- |
 | Up Arrow                  | Moves the table view up                                                           |
@@ -75,14 +133,14 @@ 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
 - 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' %}