Table

┌- table-wrapper --------------------------------------------------------┐
│  ┌- table-action-slot ---------------------------------------------┐   │
│  │  [left: filter-bar + filter-button]   [right: action-buttons]   │   │
│  └------------------------------------------------------------------┘   │
│  ┌- table-filter-bar ----------------------------------------------┐   │
│  │  [filter-tag] [filter-tag] [filter-tag] ...                      │   │
│  └------------------------------------------------------------------┘   │
│  ┌- table-container -----------------------------------------------┐   │
│  │  ┌- table-header ---------------------------------------------┐ │   │
│  │  │  [checkbox] [col A ▲] [col B] ... [fixed col] [actions]    │ │   │
│  │  └------------------------------------------------------------┘ │   │
│  │  ┌- table-row ------------------------------------------------┐ │   │
│  │  │  [checkbox] [cell] [cell] ...  [fixed-cell] [action-icons]  │ │   │
│  │  └------------------------------------------------------------┘ │   │
│  │  (repeat rows)                                                   │   │
│  └------------------------------------------------------------------┘   │
│  ┌- table-pagination ----------------------------------------------┐   │
│  │  [1–25 of 340]                    [< 1 2 3 ... 14 >] [25/page]  │   │
│  └------------------------------------------------------------------┘   │
└------------------------------------------------------------------------┘

Parts:

• table-wrapper -- outer flex column container
• table-action-slot -- bar above table: filter slot left, action buttons right
• table-filter-bar -- active filter chip row, shown when filters are applied
• table-filter-button -- opens advanced filter panel
• table-filter-tag -- individual applied filter with remove button
• table-container -- bordered table surface
• table-header -- sticky column headers with optional sort and resize handles
• table-column-fixed -- sticky left column(s) with shadow edge indicator
• table-row / table-cell -- data rows; three height variants (compact / standard / comfortable)
• table-row-action-cell -- fixed right column with per-row action icons
• table-pagination -- below-table page navigation and page size control
• table-preferences-button -- column visibility and sort preference panel trigger

When to use

• Displaying structured datasets where comparison across rows matters.
• When users need to sort, filter, or act on individual rows.
• When data has 3+ columns and a fixed header improves orientation during scroll.

When not to use

• Do not use a table for a simple list of items with one or two attributes -- use a card list or list component instead.
• Do not use a table inside a card that is itself inside a table row -- no nested tables.
• Do not use a table for navigation between pages -- use a list or sidebar nav.

Do

• Define column types upfront -- text, number, date, status, action. Apply the correct alignment: text left, numbers right, status centered.
• Always define an empty state for zero-row scenarios.
• Use Compact density when two or more tables appear in the same view.
• Keep the action column (table-row-action-cell) as the rightmost column, right-aligned.
• Show a maximum of 3 row action icons before collapsing to a more_horiz overflow menu.
• Truncate long text with ellipsis -- never wrap cell text in Standard or Compact density.

Don't

• Don't show more than 3 simple filters in the filter slot -- move to advanced filter panel if more are needed.
• Don't put primary actions inside the table -- use the action slot above the table.
• Don't resize the table container to less than 320px -- horizontal scroll is the correct response to narrow viewports.
• Don't use Comfortable density for tables with more than 8 columns.
• Don't fix more than 2 columns on the left.

• Column headers: Short nouns or noun phrases. Title case. No verbs. Maximum 2 words.
• Action labels: Verb only when in an overflow menu (e.g. "Edit", "Delete"). Icon-only with tooltip for inline action icons.
• Status labels: Use Lozenge component for status text values in cells. Use status icons for compact status indicators.
• Numbers: Right-align numeric columns. Use locale-aware number formatting.
• Dates: Use consistent format across all date columns within a table. Prefer relative dates ("2 days ago") for recency-focused data.
• Empty cells: Show a dash ("--") for null or missing values. Never leave a cell visually empty.

• ARIA role: role="grid" on the table element when rows are selectable or keyboard-navigable between cells. role="table" for display-only tables.
• Column headers: scope="col" on <th> elements. Sortable headers add aria-sort="ascending" / "descending" / "none".
• Row selection: aria-selected="true" on selected rows. Checkbox column has aria-label="Select row".
• Pagination: Wrap in <nav aria-label="Table pagination">. Current page button: aria-current="page".
• Screen reader: Sort state changes are announced via aria-live="polite" region. Filter changes announce updated row count.
• Contrast: Header text ({colors.muted}) achieves 4.5:1 against {colors.surface-table-header}. Row text ({colors.ink}) achieves 4.5:1 against white surface.

• Virtualized table scroll performance spec — implementation concern; no token gaps remain.
• Column reorder drag-and-drop animation — not yet specified with motion tokens.

• Filter / Form controls -- filter inputs used in the filter slot
• Popover -- dropdown and popover for advanced filter panel and row action menus
• Badge -- filter count badge on the advanced filter button
• Stepper -- pagination uses the same button-ghost/active pattern