Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(table): markup guidance #1287

Merged
merged 8 commits into from
Nov 27, 2023
Prev Previous commit
Next Next commit
Improvements to table's accessibility guidelines
markcaron committed Oct 20, 2023
commit 1755fa4a70c21c8d46a55a564b480c80d584de3d
56 changes: 29 additions & 27 deletions elements/rh-table/docs/30-code.md
Original file line number Diff line number Diff line change
@@ -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 %}
bennypowers marked this conversation as resolved.
Show resolved Hide resolved
bennypowers marked this conversation as resolved.
Show resolved Hide resolved

### 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>
38 changes: 21 additions & 17 deletions elements/rh-table/docs/40-accessibility.md
Original file line number Diff line number Diff line change
@@ -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' %}