Table mobile/stacked variants and responsive text sizing

[abbybowman]

Feature name

Table mobile/stacked variants and responsive text sizing

Feature area

Component patterns (cards, search, archive layouts, etc.)

Describe the idea

HDS Core ships desktop table styles but has not tested or styled the USWDS mobile layout variants. Two related gaps:

1. Stacked mobile layouts

USWDS provides .usa-table--stacked and .usa-table--stacked-header classes that reflow table rows into vertical card-like layouts on small viewports. These are untested with HDS Core overrides — header colors, sorted column tints, border tokens, caption typography, and sort icon replacements (CSS mask-image) may all break or look incorrect in stacked mode.

Known risk areas:

• Sort icon CSS masks are positioned for horizontal <th> cells — stacked headers may clip or misalign icons
• Sorted column background tints apply to <td> elements by column — stacked layout removes the column context
• Dark palette overrides target standard table structure — stacked markup may not match selectors
• Caption title/subtitle spacing assumes horizontal table top — may need adjustment above a stacked layout

2. Responsive text sizing

HDS Figma shows different text sizes for small viewports vs M-XL viewports in table cells. HDS Core currently uses a single size (14px) at all breakpoints. The Figma small-viewport values have not been extracted or compared against USWDS type tokens.

These two issues are bundled because they both involve responsive table behavior and would be tested together.

Use case / user story

As a developer building responsive pages with data tables, I want tables to reflow cleanly on mobile devices so that users on phones and small tablets can read tabular data without horizontal scrolling. The scrollable wrapper (.usa-table-container--scrollable) works as a fallback, but stacked layouts are a better mobile experience for tables with fewer columns.

Primary audience

Front-end developers

Is this already in the HDS Figma library?

🟡 Partially — some elements exist but not complete

Figma reference

HDS Figma Library → Components → Table → Small viewport variant (text sizing only — no stacked layout mockup)

Implementation maturity

🔍 Seen elsewhere — exists in another design system or library (not NASA)

Prior art details

USWDS provides two stacked variants out of the box:

• .usa-table--stacked — reflows rows into vertical blocks on small screens, hides column headers
• .usa-table--stacked-header — same reflow but repeats column headers as inline labels per cell

HDS Core v0.4.0 does not add or remove any stacked-related CSS. The USWDS stacked behavior loads automatically but renders with a mix of USWDS defaults and HDS overrides that has not been visually verified.

References:

• USWDS Table documentation: https://designsystem.digital.gov/components/table/
• _hds-components.scss §16: All current table overrides
• DESIGN.md § Table > Deferred to Phase 2

Relationship to USWDS

Extends USWDS with something it doesn't provide

Potential breaking change?

No — purely additive

Alternatives considered

1. Skip stacked variants entirely and recommend .usa-table-container--scrollable for all mobile tables — simpler but worse UX for narrow tables.
2. Implement only .usa-table--stacked-header (the more useful variant) and defer plain .usa-table--stacked — reduces scope but leaves a gap.
3. Build a custom HDS mobile table pattern (e.g., accordion-based rows) instead of fixing the USWDS stacked variants — higher effort, unclear if Figma supports this direction.

Additional context

Mobile/stacked variants were deliberately deferred from Phase 1 to ship desktop table styles on schedule. The responsive text sizing gap was noted at the same time — Figma specifies different type sizes at small breakpoints but the exact values haven't been extracted.

Testing plan for Phase 2:

1. Add .usa-table--stacked and .usa-table--stacked-header stories
2. Verify all HDS overrides (colors, sort icons, dark palette, caption) on both variants at mobile viewport
3. Extract Figma small-viewport text sizes and implement as responsive type rules
4. Test across all six palettes (stacked layout inherits the same fixed-surface model as desktop — see Discussion Table palette-aware backgrounds and colors #26)

Would you contribute to this?

Partially — I could help with design/research/testing