va-table: add caption summary and focus props by jamigibbs · Pull Request #1907 · department-of-veterans-affairs/component-library

jamigibbs · 2025-12-05T21:24:09Z

Chromatic

https://5099-table-focus--65a6e2ed2314f7b8f98609d8.chromatic.com

Description

This PR will add two new props to va-table:

The tableTitleSummary prop for adding additional context/summary to the caption.
- according to this W3C tutorial, summary text can be added to a caption element for more complex tables and this seems like a good place to put something like pagination summary information.
- Why not a slot instead of a prop? Because the caption element should only contain flow content (ie. no div, p, etc). By using a prop, we can enforce that requirement and also provide consist styling for the summary.
The setCaptionFocus prop for programmatically focusing the caption as needed.
- Because of the challenges with locating the caption element in the shadow dom along with the nature of the table component re-rending with pagination, we are hoping this will make it easier for teams to add focus to this element if it's needed.
- The specific use-case we are seeing is focusing the caption when pagination info is updated on the table.

Accessibility note

After discussion with @jeana-adhoc, we tested focusing on the table element instead of the caption element but VO + Firefox and JAWS + Edge were not reading out the title & summary at all.

Adding sr-only text to the caption with focus was the only way that we could reliably get the screenreaders to read that text across all browsers. The downside of this is that in some screenreader + browser combinations, the caption will be read twice but we thought that would be better than not reading it at all.

Screenshots

Caption with summary text and focused

Testing and review

Approvals

See the QA Checklists section below for suggested approvals. Use your best judgment if additional reviews are needed. When in doubt, request a review.

Approval groups

Add approval groups to the PR as needed:

Engineering: platform-design-system-fe
Accessibility: platform-design-system-a11y
Design: platform-design-system-designer

QA checklists

Use the QA checklists below as guides, not rules. Not all checklists will apply to every PR but there could be some overlap.

In all scenarios, changes should be fully tested by the author and verified by the reviewer(s); functionality, responsiveness, etc.

✨ New Component Added

🌱 New Component Variation Added

The PR has the minor label
The variation matches its Figma design.
Any new properties, custom events, or utility functions have e2e and/or unit tests
A new story has been added to the component's existing Storybook page
Any Chromatic UI snapshot changes have been accepted by a design reviewer
Tested in vets-website using Verdaccio
Engineering has approved the PR
Design has approved the PR

🐞 Component Fix

The PR has the patch label
Any new properties, custom events, or utility functions have e2e and/or unit tests
Any markup changes are evaluated for impact on vets-website.
- Will any vets-website tests fail from the change?
Any Chromatic UI snapshot changes have been reviewed and approved by a designer if necessary
Engineering has approved the PR

♿️ Component Fix - Accessibility

The PR has the patch label
Any new properties, custom events, or utility functions have e2e and/or unit tests
Any Chromatic UI snapshot changes have been reviewed and approved by a designer if necessary
Engineering has approved the PR
Accessibility has approved the PR

🚨 Component Fix - Breaking API Change

The PR has the major label
vets-website and content-build have been evaluated to determine the impact of the breaking change
Any new properties, custom events, or utility functions have e2e and/or unit tests
Any Chromatic UI snapshot changes have been reviewed and approved by a designer if necessary
Tested in vets-website using Verdaccio
Engineering has approved the PR

🔧 Component Update - Non-Breaking API Change

The PR has the minor label
Any new properties, custom events, or utility functions have e2e and/or unit tests
Any Chromatic UI snapshot changes have been reviewed and approved by a designer if necessary
Engineering has approved the PR

📖 Storybook Update

The PR has the ignore-for-release label
Any Chromatic UI snapshot changes have been reviewed and approved by a designer if necessary
Engineering has approved the PR

🎨 CSS-Library Update

The PR has the css-library label
vets-website and content-build have been checked to determine the impact of any breaking changes
Engineering has approved the PR

jamigibbs · 2025-12-10T14:40:03Z

+  outline: 2px solid var(--vads-color-action-focus-on-light);
+  outline-offset: 2px;
+  z-index: 2;
+}


note: I created this Sass mixin because the single stylesheet approach for focus style has become unwieldy. I am going to create a follow-up ticket for us to look at switching to using a direct mixin in the other places the original stylesheet is referencing.

jamigibbs · 2025-12-10T14:44:11Z

  margin-bottom: 0.75rem;
+  margin-top: 0.75rem;
+  margin-left: 0.25rem;
+  margin-right: 0.25rem;


Hello @department-of-veterans-affairs/platform-design-system-designers reviewer! 👋🏼 I made a very small adjustment to the margin of the caption (the table title) so that the focus border would not get cut off. Without doing this, the border is not continuous.

Before

After

jamigibbs · 2025-12-10T14:45:37Z

+  margin-right: 0.25rem;
+  span {
+    display: block;
+    font-weight: normal;


Hi again, @department-of-veterans-affairs/platform-design-system-designers reviewer! 👋🏼

We have an opportunity here to style caption summary however we'd like. This is my best guess. Let me know if you would prefer something else.

@jamigibbs I think the styling is good. I'm not sure if that's the best placement for the results text though? Should it be closer to the pagination controls? 🤔 That might complicat focus order though. This is just a hunch, but I can do some research if necessary. Before doing that, I wonder if this be more of an accessibility question though. @amyleadem @jeana-adhoc Your thoughts?

Here's a quick mock up moving the results total to be near the pagination controls:
(It will need a little more space if we go this direction.)

I think @jamigibbs initial placement makes sense. It's similar to how we manage search results.

After triggering a pagination change, we need to announce that change and send focus somewhere, and we wouldn't want to focus directly above the pagination.

@amyleadem Would be curious if you have other thoughts about this.

jamigibbs · 2025-12-10T14:56:38Z

+    setTimeout(() => {
+      const main = tableRef.current;
+      const vaTable = main?.querySelector('va-table');
+      vaTable?.setAttribute('set-caption-focus', 'true');


Howdy @department-of-veterans-affairs/platform-design-system-a11y reviewer! 👋🏼 I added a prop for focusing the caption element as-needed and it appears to be functioning as intended but my VO testing resulted in some duplicate readouts when I integrated it with this pagination example in Storybook.

Is it possible that this isn't the correct a11y approach for using pagination with va-table?

I'll take a look - I heard it duplicated in VO too (but sometimes that just.. happens). I'm going to listen in NVDA & JAWS too, then come back and see if this might just be a VO quirk.

Thanks @jeana-adhoc! Based on our convo, I've updated the description of the PR with a11y notes to explain our approach. Feel free to edit or add if you'd like!

RyanMunsch · 2025-12-11T15:04:51Z

-          {tableTitle && <caption>{tableTitle}</caption>}
+          {tableTitle && <caption ref={(el) => this.captionRef = el}>
+            {tableTitle}
+            {tableTitleSummary && <span>{tableTitleSummary}</span>}


The dev looks good here in general but it does look like the nested span element in this caption element leads to some browsers not announcing the text content of the span on screen readers. Note that this behavior has been observed elsewhere (i.e. department-of-veterans-affairs/vets-design-system-documentation#5101).

I tested on MacOS VoiceOver on Chrome, Safari, and Edge and found that the announcement was working as expected on all but Firefox, where only the immediate child text of the caption is being read (the tableTitle value). I pulled the branch down locally and removed the nested span so that the tableTitleSummary value was a direct child of the caption element and it was being announced as expected.

I'll let the @department-of-veterans-affairs/platform-design-system-a11y reviewer advise on how to move forward with this, but just wanted to get it on the radar here.

@RyanMunsch Thanks for catching this! I'm going to update it with sr-only text and combine it with the nested elements using aria-hidden so we don't have a double readout. Like this:

<caption ref={(el) => this.captionRef = el}> {tableTitle}{tableTitleSummary ? ` ${tableTitleSummary}` : ''} {tableTitle} {tableTitleSummary && {tableTitleSummary}} </caption>

That seems to fix it in Firefox, etc. but curious to hear your thoughts from an engineering perspective. The only other solution that I think might work is adding aria-label on the caption element but I feel like we generally try to avoid using that if possible.

No problem, @jamigibbs. That solution looks like it should work! That's the same approach that I used in this PR and that behaved as expected across browsers, operating systems, and different screen readers according to Jeana's testing.

danbrady

@jamigibbs I noticed that there's a bit more top margin with this update. Is that intentional?

Original

Updated

jamigibbs · 2025-12-15T19:45:26Z

Hello participants of this PR! After some discussion with @jeana-adhoc, I'm going to push an update that changes focus from the caption to the table element. We want to do some testing with that approach. Thank you for all the feedback so far though! 🙇🏼

This reverts commit 3ef80a8.

jamigibbs · 2025-12-17T16:37:19Z

-  text-align: left;
-  padding: 0 0 0.313rem;
-  font-weight: 700;
-  font-size: 1.25rem;


Most of these styles are carry overs from the v1 (non-USWDS) version of the component so they are now unnecessary. The caption is now styled directly from the USWDS table class .usa-table caption:

jamigibbs · 2025-12-17T16:44:57Z

@jamigibbs I noticed that there's a bit more top margin with this update. Is that intentional?

Original
## Updated

@danbrady Thanks for noticing that! I cleaned up some old caption styles and simplified the margin CSS and it looks like that resolved this issue.

RMunschie92

LGTM!

jamigibbs · 2026-01-06T20:33:50Z

We are going to split out these two features into separate PRs (title summary & title focus). I'm going to convert this PR to a draft for now and here is the new PR for just the title summary prop:

va-table: add title summary prop #1937

jamigibbs added 2 commits December 5, 2025 15:15

add table title summary prop

a310f67

add pagination summary to the pagiation story

59df18e

jamigibbs added minor For a minor Semantic Version change run chromatic workflow Allows a PR to run the chromatic workflow to deploy Chromatic without "ready for review" status. labels Dec 5, 2025

add prop condition

3571b77

jamigibbs removed the run chromatic workflow Allows a PR to run the chromatic workflow to deploy Chromatic without "ready for review" status. label Dec 5, 2025

jamigibbs mentioned this pull request Dec 5, 2025

[Accessibility]: VaTable needs focusable caption element from table-title prop department-of-veterans-affairs/vets-design-system-documentation#5099

Closed

18 tasks

remove non-breaking space

77547e2

jamigibbs added the run chromatic workflow Allows a PR to run the chromatic workflow to deploy Chromatic without "ready for review" status. label Dec 5, 2025

add set-caption-focus-prop

c761906

jamigibbs removed the run chromatic workflow Allows a PR to run the chromatic workflow to deploy Chromatic without "ready for review" status. label Dec 9, 2025

Merge branch 'main' into 5099-table-focus

6225984

jamigibbs changed the title ~~va-table: add table title summary prop~~ va-table: add table title summary and focus props Dec 9, 2025

jamigibbs changed the title ~~va-table: add table title summary and focus props~~ va-table: add caption summary and caption focus props Dec 9, 2025

Merge branch 'main' into 5099-table-focus

c56bcfc

jamigibbs requested review from a team December 10, 2025 14:37

jamigibbs commented Dec 10, 2025

View reviewed changes

jamigibbs marked this pull request as ready for review December 10, 2025 14:57

jamigibbs requested a review from a team as a code owner December 10, 2025 14:57

RyanMunsch reviewed Dec 11, 2025

View reviewed changes

danbrady reviewed Dec 15, 2025

View reviewed changes

jamigibbs added 2 commits December 15, 2025 12:43

Update caption with sr-only text

8dc40f6

add id to caption summary for styling

81a8664

add focus to table element instead of caption

3ef80a8

jamigibbs changed the title ~~va-table: add caption summary and caption focus props~~ va-table: add caption summary and focus props Dec 15, 2025

jamigibbs added 2 commits December 17, 2025 10:09

Revert "add focus to table element instead of caption"

286d923

This reverts commit 3ef80a8.

simplify caption margin styles

ed8257c

jamigibbs commented Dec 17, 2025

View reviewed changes

Merge branch 'main' into 5099-table-focus

8654215

jamigibbs requested review from RyanMunsch, danbrady and jeana-adhoc December 18, 2025 17:18

danbrady approved these changes Dec 18, 2025

View reviewed changes

Merge branch 'main' into 5099-table-focus

0045eec

RMunschie92 approved these changes Dec 22, 2025

View reviewed changes

Merge branch 'main' into 5099-table-focus

66f7bbe

jamigibbs marked this pull request as draft January 6, 2026 20:34

OptionSelect mentioned this pull request Jan 7, 2026

Pagination: Focus issue on Transaction History Table (MCP) department-of-veterans-affairs/va.gov-team#125076

Closed

8 tasks

Conversation

jamigibbs commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Chromatic

Description

Accessibility note

Related tickets and links

Screenshots

Testing and review

Approvals

QA checklists

Uh oh!

jamigibbs Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jamigibbs Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RyanMunsch Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

danbrady left a comment

Choose a reason for hiding this comment

Original

Updated

Uh oh!

jamigibbs commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jamigibbs commented Dec 17, 2025

Original

Uh oh!

RMunschie92 left a comment

Choose a reason for hiding this comment

Uh oh!

jamigibbs commented Jan 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jamigibbs commented Dec 5, 2025 •

edited

Loading

jamigibbs Dec 10, 2025 •

edited

Loading

jamigibbs Dec 10, 2025 •

edited

Loading

RyanMunsch Dec 11, 2025 •

edited

Loading

jamigibbs commented Dec 15, 2025 •

edited

Loading