USWDS - File input: Enhance screen reader error callout #6168

mahoneycm · 2024-10-31T19:21:56Z

Summary

Fixed a bug that prevented screen readers from announcing the invalid file type error message. Now, screen readers will consistently read out the invalid file state.

Breaking change

This is not a breaking change

Related issue

Closes #6157

Related pull requests

Change log →

Preview link

File input specific variant →

Problem statement

When entering an incorrect format in the file input, there's no indication to the screen reader that there's an error. Text present, but isn't not announced. This fails criteria 4.1.3, status message.

Solution

Bring error message into the aria-label to match SR instructions. This allows consistent callouts whenever the error message is present. It also avoids an issue where the focus doesn’t return to the browser if an SR user drags and drops a file, causing the error message alert to be skipped.

Alternative solution considered

I attempted Mandy’s recommendation of adding role="alert" to the error message. It seemed to have worked at first but then continued to be ignored by screen readers.

Major changes

Error messages are now added to aria-label
Visual error messages are now aria-hidden to avoid duplicate callouts
Default error message now contains Error:
Created data-errorMessage control in storybook preview

Testing and review

Visit the file input specific variant page
Activate screen reader
Using your keyboard, navigate to the file input button
Activate the button and select a file to upload that is not a .txt or .pdf file.
Listen for error state to be read alongside instructions
Drag and drop another incorrect file into the input
Return focus to the component and confirm error state is read.
Activate file input once more
Use storybook controls to set a custom error message (error_message string control)
Confirm correct error message is displayed and ready by screen reader
Close out of the file browser without uploading a file
Confirm the error message has cleared.

Tip

It’s my understanding that screen reader users generally navigate via keyboard, so it’s important to test keyboard only navigation with this work.

Testing checklist

Error state is consistently read by screen readers
aria-label approach is logical and follows USWDS patterns
Code matches USWDS standards
Accepted file message storybook control works as expected

amycole501

Used JAWS to listen to the error and was able to hear it. Also, it read "error" which is great so thanks for that wording update.

The weird user interaction situation is that in order to acheive the error I had to drag a file from a file folder and not use the keyboard to select a file. Most SR users won't be dragging anything so it's possible the error won't be found by the majority of screen reader users.

But like I said above, the error IS now announced so I'm approving this.

amyleadem

Thanks for your quick work on this, @mahoneycm. I was able to hear a the error message in VoiceOver in Firefox and Chrome, but did not hear it in Safari.

Testing difficulties

I wanted to flag for other reviewers that it was a little difficult to test with VoiceOver because using "drag and drop" required interacting with both the file finder panel and the browser, and it took some effort to keep VO focus on the file input. To successfully get VO to read out the error message, I had to do the following steps:

Put focus on the file input with the keyboard by pressing the tab key
Once focused, I moved my cursor to the open file finder and immediately dragged an invalid file type into the component.
1. Pausing will cause VoiceOver to focus on the finder window and read out the file name. In this scenario, it does not move focus back to the component when the file is dragged and dropped.

Thoughts

I am wondering if this interaction is an edge case since I would assume most screen reader users will not be using the mouse-driven drag and drop functionality. If the component is access via keyboard exclusively, the file panel disables invalid file types and prevents the user from focusing on them. Because of this, no error message would be needed.

@amycole501 and @alex-hull is it possible this is a "passes with exceptions" issue instead?

packages/usa-file-input/src/index.js

amycole501 · 2024-11-04T15:19:46Z

I agree I think the drag and drop is an edge case since the error prevention is in place by using the keyboard functionality. Passes with exceptions allows us to also indicate that some browsers may not announce the error. I heard it in Chrome and JAWS and that covers the vast majority of users.

mahoneycm · 2024-11-04T21:58:23Z

@amyleadem Re: Safari not reading the error message.

It seems like with Safari, it reads out the aria-label with error message after just about all of the other instructions. This doesn't seem as helpful or alerting as we'd hope a message like this to be.

Safari does seem to consistently read out the "SR only status" every time the button is focused, but the other browsers do not. The other browsers only read out this hidden span while navigating through item by item.

I'm curious if it would be beneficial to update both sr only label and instructions in an attempt to cover all the bases? It seems like it wouldn't be too verbose since the browsers handle them differently but we would need to test with each browser and screen reader.

mahoneycm · 2024-11-12T20:15:57Z

I created #6197 to test updating the sr-only instructions instead of the aria-label. With this approach, the screen reader only reads the error message when screen reader users navigate by item. (For me, that's ctrl + option + left/right

When the focus returns to the button after an incorrect file is chosen, or if a user tabs to the file input, this error message will not be read.

There might be a befit of including the sr only update in our final fix but I wouldn't rely on this alone to callout the error state to the user.

mahoneycm · 2024-11-13T17:19:23Z

I also created #6200 to test adding role="alert" to the error message like originally suggested. This did not cause the error message to be read out consistently.

mejiaj

Agree with @amyleadem's comment above that this is an edge case.

Both solutions presented worked for me. So far this has been the most reliable solution in VoiceOver across browsers (Chromium & Safari).

The enhancement to customize the error text is also nice, although users can't currently customize the instructions. Created issue #6206 for that.

System info

MacOS Sonoma 14.6.1
Chromium 131
Safari 17.6
VoiceOver

Tested

Dragging invalid file reads error message in VoiceOver (both Chrome & Safari)
Code quality

Potential enhancements

Component doesn't tell you the type of file that's invalid. For single required file types this is OK. For multiple files, this could be confusing as you don't know what was rejected.

This could be a follow-up if out of scope.

packages/usa-file-input/src/index.js

packages/usa-file-input/src/usa-file-input.twig

packages/usa-file-input/src/index.js

packages/usa-file-input/src/usa-file-input.twig

mandylloyd · 2024-12-04T17:17:03Z

I recall we chatted with Amy (last week maybe?) about starting the standard of following the same model of the character count component where there would be one visual error message that updates immediately and then a second usa-sr-only message that uses the debounce function after a 1000ms delay. It worked nicely for the mask input enhancements and allows the screen reader user to receive a more detailed custom instructional message if needed since it can be longer than the visual one. If that's doable for this component as well I think it'd be a good enhancement!

mahoneycm · 2024-12-05T16:55:00Z

@mlloydbixal for this component, I don't think the delay is necessary because the user won't be inputting text the way it does for character count or input mask. File input is likely a singular input of the file(s), which should let us immediately add the error message.

When testing, do you see any potential issues with how the message is read in this PR?

mandylloyd

On testing step number 4 I was unable to force an error. After triggering the select file window and only providing incorrect file types the screen reader lets me know there is no selection available. This is the behavior I would expect. In other steps where an error was possible, the screen reader and error message were triggered correctly.

alex-hull

Tested with both JAWS and NVDA and they sound good!

packages/usa-file-input/src/usa-file-input.stories.js

amyleadem

Thanks for this @mahoneycm. I am able to hear the invalid file type readout in most browsers. I have a couple of suggestions in the comments, but I think the code is looking good.

Some notes:

I was only able to trigger the invalid file type message by dragging and dropping. My OS prevented me from selecting an invalid file type from the file finder (Please let me know if there is a way around this)
I also still do not hear the readout in Safari when dragging an invalid file type into the component. However, I do not consider this to be a blocker for the following reasons:
- @mejiaj and @mahoneycm report being able to hear the error message in Safari/VoiceOver. After digging a bit deeper, I realized that I don’t hear the aria-label announced for any of the file inputs that also have an aria-describedby attribute, whether they are in an error state or not. This is happening on develop too, so I am counting this as a quirk on my local machine and looking into what is going on with local configuration.
- Combining drag and drop actions with a screen reader is likely an edge case for users. I don't think it is necessary to get 100% coverage to count this as a win.

I was able to complete the following tests:

Confirm that the VoiceOver readout includes the error message when an invalid file type is added
- Chromium
- Safari - I do not hear the error message in the Safari/VoiceOver readout. I do not consider this be a blocker because other testers on the team do hear it (more details in the note above).
- Firefox
Confirm custom error message (added via data-errorMessage) updates as expected for visual displays and screen reader readouts
Confirm the Storybook controls work as expected
- The controls work as expected, but the control names were confusing. Recommend we update it to improve interaction in the future (See more details in this comment).
Confirm unit tests are present and work as expected
Confirm the PR description is up-to-date and accurate
- Recommend we update the summary to “Fixed a bug that prevented screen readers from announcing the invalid file type error message.”
- Note (non-blocking): I was not able to follow the testing instructions as listed because I was only able to trigger the invalid file type message by dragging and dropping (The test says I should be able to select a file by activating the button). My OS prevented me from selecting an invalid file type from the file finder.

packages/usa-file-input/src/test/file-input-accepts.spec.js

amyleadem

LGTM!

I still do not hear the aria-label readout in VoiceOver in Safari, but this is a pre-existing issue with develop and one that seems to be specific to my machine. I am not considering this issue to be a blocker for this PR because there is a distinct improvement in Firefox and Chromium browsers.

Confirm that the VoiceOver readout includes the error message when an invalid file type is added
- Chromium
- Safari - I do not hear the error message in the Safari/VoiceOver readout. I do not consider this be a blocker because other testers on the team do hear it. I suspect it is a local issue for me.
- Firefox
Confirm custom error message (added via data-errorMessage) updates as expected for visual displays and screen reader readouts
Confirm the Storybook controls work as expected
Confirm unit tests are present and work as expected
Confirm the PR description is up-to-date and accurate

Note

Non-blocking issue with testing instructions: I am still not able to select an invalid file format with keyboard only, even after following specific instructions from @mahoneycm. I suspect this might be related to an OS update that I need to do. It ultimately does not impact this review because I was able to trigger the error message via drag and drop.

mahoneycm added 2 commits October 31, 2024 12:57

Add error message to aria-label to improve SR callouts

0089174

Run prettier

5826dec

mahoneycm mentioned this pull request Oct 31, 2024

USWDS-Site - Changelog: Enhance file input error callouts[#6168] uswds/uswds-site#2933

Merged

mahoneycm marked this pull request as ready for review October 31, 2024 19:44

mahoneycm requested review from mejiaj, amyleadem, amycole501, mandylloyd, alex-hull, CTGM-Bixal and cathybaptista October 31, 2024 19:45

amycole501 previously approved these changes Oct 31, 2024

View reviewed changes

amyleadem suggested changes Nov 1, 2024

View reviewed changes

packages/usa-file-input/src/index.js Outdated Show resolved Hide resolved

mahoneycm added 3 commits November 4, 2024 17:17

Add storybook control for data-errorMessage

39e5ffb

Update error aria-label to use custom error messages if present

d2eca47

Run prettier

653e863

mahoneycm mentioned this pull request Nov 12, 2024

USWDS - File input: Update sr-only status with error message [TEST] #6197

Draft

mahoneycm mentioned this pull request Nov 13, 2024

USWDS - File input: Add role="alert" to error message [TEST] #6200

Draft

mahoneycm dismissed amycole501’s stale review via 653e863 November 13, 2024 19:48

mejiaj reviewed Nov 15, 2024

View reviewed changes

mahoneycm added 5 commits November 15, 2024 13:34

Move error message definition for consistency

6ea64ef

Name error message control

a8b49cf

Create accepted file message control; name error message control

655adc3

Remove redundant template if statement

8ee7a0f

Add spaces to prevent attributes from colliding

26a8814

mahoneycm requested a review from a team as a code owner November 15, 2024 19:16

mahoneycm added 4 commits November 27, 2024 16:32

Unit test: Rename errorMessage to visibleErrorMessage

5feb026

Unit test: Update default error state test description

6bd5173

Unit test: Update custom error message test description

b37225d

Remove whitespace from twig file

39e16e6

mahoneycm dismissed mandylloyd’s stale review via 39e16e6 November 27, 2024 22:10

Run prettier

b1c2b84

mahoneycm requested a review from mejiaj December 2, 2024 20:10

mejiaj previously approved these changes Dec 4, 2024

View reviewed changes

mandylloyd self-requested a review December 4, 2024 17:17

mandylloyd previously approved these changes Dec 6, 2024

View reviewed changes

alex-hull previously approved these changes Dec 10, 2024

View reviewed changes

amyleadem reviewed Dec 10, 2024

View reviewed changes

packages/usa-file-input/src/usa-file-input.stories.js Outdated Show resolved Hide resolved

amyleadem suggested changes Dec 11, 2024

View reviewed changes

packages/usa-file-input/src/test/file-input-accepts.spec.js Outdated Show resolved Hide resolved

packages/usa-file-input/src/test/file-input-accepts.spec.js Outdated Show resolved Hide resolved

Update storybook error control names and JSON content

7f80788

mahoneycm dismissed stale reviews from alex-hull, mandylloyd, and mejiaj via 7f80788 December 11, 2024 18:34

Improve test description clarity

f7a06e4

mahoneycm requested a review from amyleadem December 11, 2024 18:48

amyleadem approved these changes Dec 11, 2024

View reviewed changes

This was referenced Dec 11, 2024

USWDS-Site: Documentation updates for 3.11.0 uswds/uswds-site#2991

Merged

USWDS: Draft 3.11.0 release notes #6221

Closed

mahoneycm requested review from heymatthenry and thisisdano December 11, 2024 19:54

thisisdano approved these changes Dec 16, 2024

View reviewed changes

thisisdano merged commit 73ed3a9 into develop Dec 16, 2024
5 checks passed

thisisdano deleted the cm-file-input-sr-error branch December 16, 2024 22:30

thisisdano mentioned this pull request Dec 18, 2024

USWDS 3.11.0 #6264

Merged

USWDS - File input: Enhance screen reader error callout #6168

USWDS - File input: Enhance screen reader error callout #6168

Uh oh!

Conversation

mahoneycm commented Oct 31, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking change

Related issue

Related pull requests

Preview link

Problem statement

Solution

Alternative solution considered

Major changes

Testing and review

Testing checklist

Uh oh!

amycole501 left a comment

Choose a reason for hiding this comment

Uh oh!

amyleadem left a comment

Choose a reason for hiding this comment

Testing difficulties

Thoughts

Uh oh!

Uh oh!

amycole501 commented Nov 4, 2024

Uh oh!

mahoneycm commented Nov 4, 2024

Uh oh!

mahoneycm commented Nov 12, 2024

Uh oh!

mahoneycm commented Nov 13, 2024

Uh oh!

mejiaj left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

System info

Tested

Potential enhancements

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mandylloyd commented Dec 4, 2024

Uh oh!

mahoneycm commented Dec 5, 2024

Uh oh!

mandylloyd left a comment

Choose a reason for hiding this comment

Uh oh!

alex-hull left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

amyleadem left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

amyleadem left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mahoneycm commented Oct 31, 2024 •

edited

Loading

mejiaj left a comment •

edited

Loading