Skip to content

Commit

Permalink
docs(website): add Table component documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
shelbyj1 authored Dec 12, 2024
1 parent d03f8e4 commit 37a4019
Showing 1 changed file with 31 additions and 21 deletions.
52 changes: 31 additions & 21 deletions website/docs/components/table.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -24,54 +24,64 @@ Use a table to organize and display long lists of data or content, or to help us
- Text - left align
- Numbers - right align
- Checkboxes or radio buttons - center align

- Columns should be in a logical order from left to right based on the content. The farthest left content column should meaningfully label the row. If bulk actions can be taken, a checkbox should be the first item in the column. If there are no bulk actions, the most important identifying information should be in the first column. For example, in a student set the first column should be the student’s name.
:::note Why
Placing the most important or identifying information in the leftmost columns allows users to quickly scan and understand the table or take an action quickly.
:::
:::note Why
Placing the most important or identifying information in the leftmost columns allows users to quickly scan and understand the table or take an action quickly.
:::


- Tables must have at least 2 columns. If a table has less than 2 columns, use a list or another format to present the data so it is easier to understand the information.


- Tables must have at least 2 columns.
- Accessibility Reccomendation: If a table has only one or two columns, it might be more appropriate to use a list or another format to present the data
- Column titles in the header row should be as short as possible, allowing wrapping to two lines if necessary, while table content should ideally fit on one line but can wrap to multiple lines when needed.
:::note Why
Short titles help to minimize visual clutter, making it easier for users to find and understand the information they need. Wrapping content ensures that important information is not truncated, which can be critical for understanding the data presented.
:::
:::note Why
Short titles help to minimize visual clutter, making it easier for users to find and understand the information they need. Wrapping content ensures that important information is not truncated, which can be critical for understanding the data presented.
:::


- All content within a column is the same level of hierarchy as all other content within that column. A table shouldn’t be used to communicate hierarchy.

- If a table has no content, it should display an empty state or not display the table at all.

- Column titles should accurately label the data within the column, and include units of measurement in the column title if possible.
:::note Why
Including the unit of measurement inside each data cell (e.g., 95%) complicates exporting and importing data into another system, and may require users to manually remove all the percentage signs from each cell.
:::
:::note Why
Including the unit of measurement inside each data cell (e.g., 95%) complicates exporting and importing data into another system, and may require users to manually remove all the percentage signs from each cell.
:::



### Search & Filter

Search and filters can be used in conjunction with tables to help users find information
Search and filters can be used in conjunction with tables to help users find information.

- If columns are sortable, the sort symbols are always visible.
- Introducing more functionality within a table will create more complexity and can lead to users having difficulty interpreting.
:::note Why
Splitting complex tables into simpler, focused tables enhances clarity and usability, allowing users to understand each sub-topic more effectively.
:::

- Introducing more functionality within a table will create more complexity and can lead to users having difficulty interpreting the information presented in the table.
:::note Why
Tables are already complex. Splitting complex tables into simpler, focused tables enhances clarity and usability, allowing users to understand each sub-topic more effectively.
:::



:::danger Don't
Don’t use a table purely for layout purposes.
**Why:** Tables are meant for tabular data, providing a clear, semantic structure. Using tables for layout purposes misrepresents the content and structure of the page, which can confuse screen readers and other assistive technologies.

**Why:** Tables are meant for tabular data, providing a clear, semantic structure. Using tables for layout purposes misrepresents the content and structure of the page, which can confuse screen readers and other assistive technologies.
:::


### Accessibility Notes

This section expands on the design decisions and considerations made to ensure an inclusive and accessible experience for all users.
### Accessibility Notes

The following list outlines key recommendations for ensuring proper and accessible usage of the `Table` component in your React projects. These guidelines aim to align with best practices for accessibility, focusing on creating a seamless experience for all users, including those relying on assistive technologies.
This section expands on the design decisions and considerations made to ensure an inclusive and accessible experience for all users. The following list outlines key recommendations for ensuring proper and accessible usage of the `Table` component in your React projects.

- **Focus and Navigation:** ensure focus indicators and keyboard navigation for all actionable elements.
- **Keyboard-Only Usability:** Ensure all features are fully operable via keyboard.
- **Focus Management:** Test focus behavior rigorously across all breakpoints.
- **Descriptive Labels:** Provide accessible labels for tables. Consider using captions describing their purpose.
- **Avoid Color-Only Indicators:** Do not rely solely on color to convey sorting or status, as this affects accessibility for colorblind users.
- **Custom Components:** When using non-native HTML elements or third-party components for table interactions, ensure they adhere to accessibility standards (e.g., visible focus indicators, keyboard accessibility, sufficient color contrast). We highly recommend Using components from this library (NDS) for better accessibility compliance.
- **Custom Components:** When using non-native HTML elements or third-party components for table interactions, ensure they adhere to accessibility standards (e.g., visible focus indicators, keyboard accessibility, sufficient color contrast).
- **Responsive Design:** Ensure table elements scale effectively with zoom and high-contrast modes.
- **Dynamic Styling:** Avoid hardcoding focus styles; they should adapt to high-contrast and reduced-motion preferences.
- **ARIA Live Regions:** Use ARIA live regions for real-time critical updates to enhance dynamic content accessibility.
Expand Down

0 comments on commit 37a4019

Please sign in to comment.