Skip to content

Commit

Permalink
[terra-html-table]Add A11y Guide (cerner#3698)
Browse files Browse the repository at this point in the history 
* Pilot

* Add Examples

* Changelog

* UX Suggestions

Co-authored-by: Supreeth <[email protected]>
  • Loading branch information
@saket2403 @supreethmr
saket2403 and supreethmr authored Dec 7, 2022
1 parent ea2eb7a commit 840f482
Show file tree
Hide file tree
Showing 4 changed files with 213 additions and 3 deletions.
1 change: 1 addition & 0 deletions packages/terra-core-docs/CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
* Added Accordion Examples for `terra-section-header`.
* Added accessibility guide for `terra-divider`.
* Added tests and example for adding row header to `terra-html-table`.
* Added accessibility guide for `terra-html-table`.
* Added an accessibility hooks example for `terra-form-field` and `terra-input`.

* Changed
Expand Down
209 changes: 209 additions & 0 deletions .../terra-core-docs/src/terra-dev-site/doc/html-table/AccessibilityGuide.2.doc.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,209 @@
import { Badge } from 'terra-html-table/package.json?dev-site-package';
import { Notice } from "@cerner/terra-docs";
import RowHeaderTable from './example/RowHeaderTable';

<Badge />

# Accessibility Guide for HTML-Table

## Why the accessibility of HTML Table is important?

Tables are a simple and intuitive way to display tabular information that is related. However, if tables are not made to be accessible, they may not provide the necessary context to understand that tabular data. Inaccessible tables can be confusing and severely cumbersome to understand for some users, especially screen reader users.

## Accessibility Considerations

### Content Considerations: What do content creators need to do?

- Consider using a heading before the table or adding a table caption to help users understand the purpose of the table.
- Always provide both a table row header and a column header when displaying tabular data.
- Provide engineers with text for each row and column header where applicable.
- Ensure all headings appropriately describe the content they represent.
- Row headers should be used to describe the content of a row.
- For example, in a patient list the patient’s name in the first column of the row should be the row header because it describes what the other content is referring to.
- In most instances, row headers should be the first column of the table but may be the second column if there are checkboxes in the first. Very rarely should the row header be in a column after the first or second column.
- Each column header must also describe the content within the column.
- It is appropriate to have a column header that describes the column filled with all the row headers. For example, the column with a patient name as row header would have a column header “Patient” or “Patient Name” – whatever would best describe the content and purpose of the column.
- Communicate to engineers which column should within a row if it is not the first column.
- It is best practice is to have the first or second column used to display row headers.
- Most tables at Cerner should use both row headers and column headers, though there may be a an extremely few instances where a table only requires headers on only one axis.
- Never use color as the only way to convey information within a table. Instead, use color combined with an icon or text to communicate any meaning.
- Ensure all content (text or graphics) added within a table meet the appropriate contrast rations against their background colors. See [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) and [1.4.10 Non-text Contrast](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html) for more information.
- Consider how content can resize or reflow within the table at smaller breakpoints and screen sizes.
- Communicate to engineers any guidance for content resizing or reflowing at different breakpoints.

### Code Considerations: What do engineers need to do?

- Do not override the role of any HTML Table, table header, column, row, cell, or other native HTML element that make up an HTML Table.
- Do not use Terra HTML-Table to display non-tabular content. For example, do not use tables to layout content for layout purposes only where there is no relationship of data between the columns and rows.
- Do not make a table cell, row, or column receive keyboard focus. Only actionable elements within a table should receive keyboard focus.
- Do NOT make any part of the HTML Table (rows, columns, cells, etc.) receive keyboard focus - only interactive content within the cells should receive focus.
- Engineers are responsible for ensuring all interactive elements within a table can receive keyboard focus, can be interacted with, and acted upon.
- Most tables at Cerner will require both column and row headers to ensure tabular relationships can be understood programmatically.

<Notice ariaLevel="4">

**Accessibility Guidance: Adding table with offset row header**

<div aria-label="Example Demo">
<RowHeaderTable />
</div>

```jsx
<Table paddingStyle="compact" disableStripes>
<caption>
Requested Quantities of Aspirin from the Last Six Months (table with row header cells in an offset column)
</caption>
<Header>
<HeaderCell key="ID"><abbr title="Identification Number">Patient ID</abbr></HeaderCell>
<HeaderCell key="NAME">Patient Name</HeaderCell>
<HeaderCell key="JUL">July</HeaderCell>
<HeaderCell key="AUG">August</HeaderCell>
<HeaderCell key="SEPT">September</HeaderCell>
<HeaderCell key="OCT">October</HeaderCell>
<HeaderCell key="NOV">November</HeaderCell>
<HeaderCell key="DEC">December</HeaderCell>
</Header>
<Body>
<Row>
<Cell key="ID">215</Cell>
<HeaderCell key="NAME">Abel</HeaderCell>
<Cell key="JUL">5</Cell>
<Cell key="AUG">2</Cell>
<Cell key="SEPT">0</Cell>
<Cell key="OCT">0</Cell>
<Cell key="NOV">0</Cell>
<Cell key="DEC">3</Cell>
</Row>
<Row>
<Cell key="ID">231</Cell>
<HeaderCell key="NAME">Annette </HeaderCell>
<Cell key="JUL">0</Cell>
<Cell key="AUG">5</Cell>
<Cell key="SEPT">3</Cell>
<Cell key="OCT">0</Cell>
<Cell key="NOV">0</Cell>
<Cell key="DEC">6</Cell>
</Row>
<Row>
<Cell key="ID">173</Cell>
<HeaderCell key="NAME">Bernard</HeaderCell>
<Cell key="JUL">2</Cell>
<Cell key="AUG">0</Cell>
<Cell key="SEPT">0</Cell>
<Cell key="OCT">5</Cell>
<Cell key="NOV">0</Cell>
<Cell key="DEC">0</Cell>
</Row>
<Row>
<Cell key="ID">141</Cell>
<HeaderCell key="NAME">Gerald</HeaderCell>
<Cell key="JUL">0</Cell>
<Cell key="AUG">10</Cell>
<Cell key="SEPT">0</Cell>
<Cell key="OCT">0</Cell>
<Cell key="NOV">0</Cell>
<Cell key="DEC">8</Cell>
</Row>
<Row>
<Cell key="ID">99</Cell>
<HeaderCell key="NAME">Michael</HeaderCell>
<Cell key="JUL">8</Cell>
<Cell key="AUG">8</Cell>
<Cell key="SEPT">8</Cell>
<Cell key="OCT">8</Cell>
<Cell key="NOV">0</Cell>
<Cell key="DEC">4</Cell>
</Row>
</Body>
</Table>
```

</Notice>

- By default, row headers should be the first column but may be the second column if the first column contains checkboxes to select a row.
- Work with content creators to understand placement of row headers should the need be different.
- Very rarely should row headers be assigned beyond the second column.
- Work with content creators to understand how, if any, resizing or reflow of content may happen at different breakpoints or screen sizes.
- Ensure content is coded in the user’s logical reading order of the page. Generally, this is top left to the right and down in a zig zag pattern.

## Usability Expectations

Users expect to understand the relationship of content by using column and row headers that describe cell content.

### Interaction Details

HTML Table itself is not interactive nor does it receive keyboard focus.

### Keyboard Expectations

Users do not have any keyboard expectations from Terra HTML Table because the table, rows, columns, and cells are not actionable. Users would, however, expect all actionable elements within the table to be keyboard accessible.

## Support Compliance

Terra is committed to ensuring its components provide maximum possible accessibility. Terra provides the ability to make accessibility products. However, using Terra components will not automatically make a product accessible.
Final responsibility lies with the consumers of Terra components — ensuring proper usage, programmatic context where needed, the words used to label elements, engineers following correct implementation patterns, and authors crafting content that follows best practice guidance — to make a product fully accessible.

### Primary Criteria

- [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html) – Supports
- Terra HTML tables provides the ability to set column and row headers to appropriately provide necessary context of data.
- Engineers must appropriately assign row headers and or column headers to ensure appropriate programmatic context can be conveyed to screen reader users so they may understand the relationships of the table data.
- Work with content creators to understand which columns and rows should be used for the column/row headers.
- Engineers must NOT use Terra Table to layout or display content other than tabular content. Tables should only be used with tabular data.
- Content creators must communicate to the engineers which content that should be used for column and row headers.

- [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) – Supports
- Terra HTML tables are created using the native HTML components that implicitly have roles defined and can have names assigned by the consuming team.
- Engineers must not override the role of any HTML Table, column, row, or other native HTML elements that make up HTML Table.
- Content creators must provide the appropriate names of column and row headers.


### Secondary Criteria

- [1.4.1 Use of Color](https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html) – Supports
- Terra HTML Table does not use color to convey information.
- Content creators must not use color as the only way to convey meaningful information to the user.

- [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) – Supports
- Terra text meets the appropriate color contrast requirements against default background colors.
- If the default text or background color is not used, content creators are responsible for ensuring all text colors meet the appropriate contrast ratio based upon the background the text appears on top of.

- [1.4.4 Resize text](https://www.w3.org/WAI/WCAG21/Understanding/resize-text) – Supports
- Terra HTML table does not restrict the resizing of text.
- Engineers must not artificially constrict content and prevent text from resizing. Work with the content creators to understand how content resizes and reflows at various breakpoints.
- Content creators must consider how the table and its content would resize and reflow if text is resized by the user up to 200%.

- [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html) – Supports
- Terra Tables nor their cells do not receive keyboard focus by default. This is the user’s expected behavior.
- Engineers are responsible for ensuring all interactive elements within a HTML table can receive keyboard focus, can be interacted with, and acted upon.
- Do NOT make HTML Table cells receive keyboard focus - only interactive content within the cells should receive focus.

- [2.4.3 Focus Order](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-focus-order.html) – Supports
- Terra Tables by default do not set the focus order.
- Engineers must ensure their code is created in the order of the users logical reading order.

- [3.1.2 Language of Parts](https://www.w3.org/TR/UNDERSTANDING-WCAG20/meaning-other-lang-id.html) – Does Not Support
- Terra HTML Table does not support cell content in a language different than that of the page being used.


### Supported Features and Technology

- Keyboard Interactions
- JAWS Support with Chrome (PC)
- NVDA tested (PC)
- VoiceOver Support with Chrome, Safari (MAC)

### Partial Support & Requiring Further Enhancement
- Mobile Touch Interactions with Screen Reader assistive technology
- Speech Input Interactions with assistive technology

- [Report a problem with this component on GitHub](https://github.com/cerner/terra-core/issues/new/choose)

### Linked References:

1. [W3C WAI Aria: Table](https://www.w3.org/WAI/tips/writing/#use-headings-to-convey-meaning-and-structure)
2. [WebAim.org: Creating Accessible Tables](https://webaim.org/techniques/tables/)




0 ...v-site/doc/html-table/ChangeLog.2.doc.mdx → ...v-site/doc/html-table/ChangeLog.3.doc.mdx
View file
File renamed without changes.
6 changes: 3 additions & 3 deletions packages/terra-core-docs/src/terra-dev-site/doc/html-table/example/RowHeaderTable.jsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,11 @@ import Table, {
const RowHeaderTable = () => (
<Table paddingStyle="compact" disableStripes>
<caption>
Requested Quantities from the Last Six Months (table with row header cells in an offset column)
Requested Quantities of Aspirin from the Last Six Months (table with row header cells in an offset column)
</caption>
<Header>
<HeaderCell key="ID"><abbr title="Identification Number">ID</abbr></HeaderCell>
<HeaderCell key="NAME">Name</HeaderCell>
<HeaderCell key="ID"><abbr title="Identification Number">Patient ID</abbr></HeaderCell>
<HeaderCell key="NAME">Patient Name</HeaderCell>
<HeaderCell key="JUL">July</HeaderCell>
<HeaderCell key="AUG">August</HeaderCell>
<HeaderCell key="SEPT">September</HeaderCell>
Expand Down

0 comments on commit 840f482

Please sign in to comment.