Component guidelines: Table (pajamas::create)
Problem
Discuss and expand the documentation of the Table component, including responsive views, and best practices for different use cases in different product areas.
- There are multiple table variations living in the product
- There are no clear guidelines to indicate which tables to use in different scenarios
- It is unclear when to use Tables vs. Cards vs. Lists
Proposed Tasks
This issue
-
Define Anatomy of a table -
Define table guidelines (sorting, states (active, hover, disabled, error, success), content alignment, empty state, headers) -
Define table component structure for: -
Simple Table - simple tabular data -
Complex Table - action items, sorting, selecting, pagination
-
-
Create Sketch visuals with tables variations -
Define responsive table views
-
-
Validate and define initial Accessibility best practices -
Add rules/usage and design pattern to the Tables documentation page in design system.
Follow up
-
Interface Inventory of tables across the product -
Define table semantics -
When to use <table>
-
When to use <div>
styled to look like tables
-
Solution
Initial thoughts on Tables documentation:
Tables are used to render tabular data in a basic grid in a way that is easy for people to scan it.
Usage
Use tables so that users can review, enter or edit uniform sets of data or options. Tables are used for structured content, where each entry has the same attributes.
When to use tables
- To display large volumes of data
- When the data set will grown
- To compare data in a set to make sure that they are distinguishable
- To search, filter, or sort by all parameters in a data set
When not to use tables
- To display a list of continuous, vertical indexes of text or images. Use Lists instead.
- To display independent and contained content and actions on a single topic. Use Cards instead.
- For hierarchical structures. Use Tree View instead.
Table anatomy
Layout
- Tables take up the full width of their container
- Don’t simply shrink the entire table to fit the viewport
- Don’t let the table break your layout by preventing horizontal scrolling
- Don’t compress content to the point it compromises legibility
- A cell’s width and height will change according to its content
- TODO: empty state
Headers
- Column headers should always be used
- Row headers are optional, depending on the data
- (Not implemented) Columns should be sortable by clicking on a directional arrow in the column header
Content alignment
- Left align content unless a different alignment helps with comprehension. For example, numeric data is easier to read when right aligned or is designed to a right-to-left audience. Always align column headers with column content.
Interaction
- When including triggers to manipulate the data, they should be placed directly above the table
- TODO: Describe the behaviour of the mouse hover for table rows
- TODO: Developer may choose to change a row’s background color to help scan through table content
Actions
- TODO
Pagination
- Tables can include pagination. Pagination works by presenting a set number of rows in a view, with the ability to navigate to another set.
Style
- The row style helps users scan data. Alternating rows (aka zebra stripes) help users keep their place when scanning long horizontal datasets. Line divisions help users keep their place.
- Reducing visual noise by removing row lines or zebra stripes works well for small datasets.
Responsiveness
- Table will render in a stacked, block pattern on responsive view
Accessibility
- Tables should be accessible to all users. Using proper semantic markup is a must so that users of screen readers can navigate through the table one cell at a time, hearing column and row headers spoken to them.
-
<th>
shouldn’t contain heading elements -
<th>
should be descriptive and relevant -
<th>
should have thescope
attribute defined to establish relationships between the table headings and rows/columns. e.g.,<th scope="col">
. - Table styles should meet WCAG 2 AA contrast guidelines (or even AAA depending on the level of compliance needed)
-
<caption>
should be used to provide a title for a table -
<caption>
should be an immediate child element of<table>
Example(s)
(One or more images showing the UX pattern. They don’t have to be in GitLab.)
Usage
(When do you use this pattern? And how?)
Dos and dont's
(Use this table to add images and text describing what’s ok and not ok.)
|
|
---|---|
Related patterns
(List any related or similar solutions. If none, write: No related patterns)
Links / references
Related Issues
External references
- Tables · Bootstrap
- Data tables - Material Design
- Tables | Components | Atlassian Design Guidelines
- Modern Enterprise UI design — Part 1: Tables – Pulsar – Medium
- Design better data tables – UX Collective
- Web Typography: Designing Tables to be Read, Not Looked At · An A List Apart Article
- Table | IntelliJ Platform UI Guidelines
- Reordering Datagrid columns (design spec) · Issue #1771 · vmware/clarity · GitHub
Pattern checklist
Make sure these are completed before closing the issue, with a link to the relevant commit, if applicable.
-
Read our contribution guidelines, especially the For GitLabbers section. -
Create a Sketch file in your progress folder just for this pattern and make sure that: -
You have not created a duplicate of an existing pattern, symbol, layer style, or text style. -
You have used the proper method for creating the pattern depending on the complexity. Atoms and molecules are symbols, organisms are groups. -
Typography uses text styles. When applicable, colors use shared styles.
-
-
Ask a UXer to review your Sketch file, linking them to your latest commit so they know where to find it. If they have the capacity, they should assign themselves to this issue. -
QA of your Sketch file by the reviewer. -
Add your changes to the pattern library. When copying things over, watch out for duplicated symbols, layer styles, and text styles. Some of our recommended plugins can help you find and remove duplicates. -
QA of pattern library by the reviewer. -
Create an issue in the Design System to add the pattern documentation. Mark it as related to this issue. -
Add an agenda item to the next UX weekly call to inform everyone (if it's a new pattern, not yet used in the application).