diff --git a/documentation/specs/DisplayTable.md b/documentation/specs/DisplayTable.md
index 36359f2c8..3166bd4ef 100644
--- a/documentation/specs/DisplayTable.md
+++ b/documentation/specs/DisplayTable.md
@@ -8,24 +8,221 @@ A `DisplayTable` is used for presenting information displayed across columns and
## Design
-`DisplayTable` is only for presentational concerns. It doesn't support advanced capabilities such as selection, sorting, and row expansion. With that in mind, complexities are primarily shifted to surfacing a simple component API, structuring the table properly to support the style requirements, and ensuring that accessibility markup is applied correctly.
+`DisplayTable` is for presentational concerns only. It doesn't support interaction such as selection, sorting, and row expansion. For an interactive table accommodating advanced use cases, see `Table`.
-Even though `DisplayTable` doesn't do much in terms of functionality, because accessibility concerns can be non-trivial, we will use `useTable` from React Aria to ensure that we have our accessibility bases covered.
+Without interaction, complexities are shifted to surfacing a simple component API, structuring the table for style requirements, and ensuring appropriate application of accessibility markup.
+
+`DisplayTable` will use React Aria's `useTable` under the hood to reliably generate accessibility markup for the table.
### API
```ts
+type DisplayTableProps = AriaLabelingProps & {
+ /** Columns for the table. */
+ columns: Column[];
+
+ /**
+ * Horizontal alignment of data within their cells.
+ * @default start
+ */
+ dataAlignment?: "start" | "center" | "end";
+
+ /** Renders the first row cell as a row header. */
+ hasRowHeaders?: boolean;
+
+ /** Rows for the table. */
+ rows: Row[];
+};
+
+type Row = Cell[];
+
+type Cell =
+ | ReactNode
+ | {
+ /** Cell text. */
+ text?: ReactNode;
+
+ /** Cell icon. */
+ symbol?: IconSymbol;
+ /** Mark cell as highlighted. */
+ isHighlighted?: boolean;
+ };
+
+type Column =
+ | ReactNode
+ | {
+ /** Column heading. */
+ heading?: ReactNode;
+
+ /** Column subheading. */
+ subheading?: ReactNode;
+
+ /** Column heading icon or image. */
+ media?: ImgMedia | IconMedia;
+ };
+
+type IconMedia = {
+ symbol: IconSymbol;
+};
+
+type ImgMedia = {
+ src: string;
+ alt: string;
+};
```
### Example Usage
-_Simple_:
+_Basic usage_:
```tsx
-import { Modal } from "@easypost/easy-ui/Modal";
+import { DisplayTable } from "@easypost/easy-ui/DisplayTable";
-function PageWithModal() {
- return ;
+function CustomDisplayTable() {
+ return (
+
+ );
}
```
+
+_Advanced usage_:
+
+```tsx
+import { DisplayTable } from "@easypost/easy-ui/DisplayTable";
+
+function CustomDisplayTable() {
+ return (
+
+ );
+}
+```
+
+---
+
+## Behavior
+
+### Accessibility
+
+Tables are used to organize data with a logical relationship in grids. Accessible tables need HTML markup that indicates header cells and data cells and defines their relationship. Assistive technologies use this information to provide context to users.
+
+- Tables must have a thead, containing a th for each column.
+- Tables must have a tbody wrapping the table body of rows.
+- Tables should include row headers as the first cell in a row.
+- `DisplayTable` should contain static textual and numeric data rather than actionable components. For more advanced cases, see `Table`.
+
+Most accessibility concerns will be handled through React Aria.
+
+## Dependencies
+
+- `react-aria`—`useTable`
+- `@easypost/easy-ui`—`useIntersectionDetection` for the stuck styles