Table component documentation updates
The following is an update to the content and structure of the table component page in PJs.
The aim of the updated structure is to separate out the content required for guidance on component usage
vs guidance on component development
as discussed in this Slack thread:
I’m currently adding some documentation updates to Pajamas. A lot of the content in the component pages seems extraneous. My hypothesis is that the content is currently trying to serve 2 JTBDs:
- Guidance on component usage - When using components, I want to understand best practices and patterns, so that I know IF and HOW I should implement the component in my features.
- Guidance on component development - When building components, I want to understand what patterns should be embedded into the component programmatically, so that the component works in the way it was designed.
Both are important but I think we can streamline a lot of our component pages by separating the content out for both of these jobs. Maybe in our process, we could create 1. the component page content and 2. component development guidance (which isn’t displayed in PJs).
The updated content is from the work done off the back of the Code Review Analytics + Table Component: Design evaluation & usability testing research.
Tables display tabular data in a basic grid comprised of cells, columns, and rows. This format makes it easy for users to scan large amounts of data.
Usage
- Display structured content, where each entry has the same attributes.
- Display a data set that will continue to grow (e.g. issues, user & environments)
- Let users review, enter, edit or filter granular data sets.
- Display a list of continuous, vertical indexes of text or images. Use Lists instead.
- Display contained content and actions on a single topic. Use Cards instead.
- Display hierarchical structures. Use the Tree view instead.
Basic table
The basic table is the default option for this component, however, additional functionality below can be added to refine the table for any use case.
To Do: Add Figma/Image Example
Search & filter
Any filtering controls that manipulate the data set (including clickable charts) should be placed directly above the table with the option to clear all data. See filter guidelines
To Do: Add Figma/Image Example
Sorting
Tables use column sorting rather than list sorting. The default sort direction of a table can be up or down depending on the use case and is indicated in the table header using an arrow icon. See sorting guidelines
To Do: Add Figma/Image Example
Pagination, lazy load & infinite scroll
Tables displaying data sets with more than 20 items should use either pagination, lazy load or infinite scroll. Tables have embedded pagination controls which are located at the bottom of the table. See pagination guidelines
To Do: Add Figma/Image Example
Inline actions
Table rows can include inline actions located n their far-right column. Inline actions should be visible at all times rather than showing on-hover. If there are two or more actions in a table row, consider using a button group or a “more menu” button with a dropdown list option.
To Do: Add Figma/Image Example
Expandable rows
Use expandable rows to progressively reveal more information about an item in a dataset. Do not use expandable rows to display hierarchical structures. Use the Tree view instead.
To Do: Add Figma Example
Styles
Default
To Do: Add Figma/Image Example
Zebra stripes 🦓
Alternating grey and white stripes can be used to help differentiate rows.
To Do: Add Figma/Image Example
Content
Headers
Always use column and/or row headers unless the table content is self-descriptive. Headers should be short, descriptive, and relevant. Avoid headers that are too long for the content in the rows below, and use title-case.
Columns
Columns should be ordered by priority or in a way that tells a story with the data. Size columns according to the data they contain rather than making them all an even width.
Rows
Rows can have a mix of interactive, read-only and editable cells.
Text alignment
Left-align text content rather than justifying or centering it. Right-align numeric data with a consistent number of decimal places to improve scannability.
Null values
If the data for a cell is null, blank or unavailable, you can either:
- Keep the cell empty to reduce noise and help with legibility
- Use a dash ("-") to signify missing data
Truncation
You can truncate long text strings with an ellipsis (“…”). On hover, the truncated text should display a tooltip including the full text. See tooltips guidelines
Empty state
A table’s empty state displays when there is no data, yet. See empty states guidelines.
Responsiveness
Tables work across multiple screen sizes and conform to responsive guidelines. Prevent horizontal scrolling to ensure the table doesn’t break the layout.
To Do: Add Figma/Image Example
Accessibility
Use proper semantic markup, 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>
should not contain heading elements. -
<th>
should be descriptive and relevant. -
<th>
should have a definedscope
attribute to establish relationships between the table headings and rows/columns; for example,<th scope="col">
. -
<caption>
should be used to provide a title for a table. -
<caption>
should be an immediate child element of<table>
.
Design specifications
Color, spacing, dimension, and layout specific information about this component can be viewed using the following link: