USWDS - Bug: Fix invalid aria role in validator list items #4914

amyleadem · 2022-08-08T18:52:28Z

Summary

Updated the validation component so that users of assistive technologies can receive status updates about the completion of each validation requirement. This was done by adding a script that generates appropriate ARIA attributes.

Details

Added a script that generates an aria-label for each checklist item. This allows assistive technologies users to navigate to each checklist item and receive the current status of each validation requirement.

Added a script that generates a new span to house the summary of the validation status updates. This span has aria-live and aria-atomic attributes so that users of assistive technologies will be notified of status changes.

Removed the aria-checked attribute from list items in the validation component. This attribute is no longer needed now that a text element informs the user if the requirement is complete or incomplete.

Added data-validation-complete and data-validation-incomplete attributes so that users can customize copy for status complete and status incomplete messages.

Related issue

Closes: #4905

Related PRs: This PR incorporates the changes originally merged in #4719 that were later reverted in #4906. This PR includes the original update from #4719 and resolves the errors that caused the reversion.

Preview link

Preview link: Validation component

Problem statement

Including the aria-checked attribute generates errors

Adding the aria-checked attribute to a <li> item results in the following a11y error:

Errors in http://localhost:4000/components/validation/:

 • Elements must only use allowed ARIA attributes
   (https://dequeuniversity.com/rules/axe/3.5/aria-allowed-attr?application=axeAPI)

   (#validate-code > li:nth-child(1))

   <li class="usa-checklist__item" data-validator="uppercase"
   aria-checked="false"> Use at least one u...</li>

 • Elements must only use allowed ARIA attributes
   (https://dequeuniversity.com/rules/axe/3.5/aria-allowed-attr?application=axeAPI)

   (#validate-code > li:nth-child(2))

   <li class="usa-checklist__item" data-validator="numerical"
   aria-checked="false"> Use at least one n...</li>

These errors reveal that items with the aria-checked attribute also need an appropriate role. Reference: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-checked#associated_roles

However, adding role="checkbox" to the <li> item also returns an error:

Detected the following accessibility violations!
       
       1. aria-allowed-role (ARIA role should be appropriate for the element)
       
          For more info, visit https://dequeuniversity.com/rules/axe/4.3/aria-allowed-role?application=axeAPI.
       
          Check these nodes:
       
          - html: <li class="usa-checklist__item" data-validator="uppercase" role="checkbox" aria-checked="true">Use at least one uppercase character</li>
            summary: Fix any of the following:
                       ARIA role checkbox is not allowed for given element

VoiceOver produces a confusing readout

Additionally, VoiceOver generates undesirable and inconsistent readouts. Items can be read twice or only partially.

Solution

aria-checked

The data-checklist-label element now informs the keyboard user if the validation requirements are complete or incomplete. There is no longer a need to use an attribute like aria-checked to communicate complete or incomplete to the user.

Confusing readout

Changing the following items generated a more consistent readout in VoiceOver:

Generated an aria-label for each checklist item that includes the original text content plus the item's current status
Generated a new sr-only span with aria-live and aria-atomic attributes that houses the summary of all checklist items plus their individual statuses.

Tasks completed in this PR:

Integrated changes created in cm-validation-a11y branch 0684b17
Removed the aria-checked attribute from the list item f077275
Added tabindex="0" to make the items in the validation checklist items easier to navigate via tab 29c2b61
Created a new sr-only span element with aria-live and aria-atomic attributes that houses a status summary 07ad7de
Added optional data-validation-complete and data-validation-incomplete attributes eeb2e18

Testing and review

Using the screen readers you have available,

Confirm that validation status is discoverable via keyboard navigation .
Confirm that the validation status is read out in a way that makes sense.
Confirm that the validation component passes a11y tests.
Add the following data attributes with custom values to .usa-input and confirm that the status message in data-checklist-label updates accordingly:
- data-validation-complete
- data-validation-incomplete

Tested on:

VoiceOver on Firefox, Safari, Edge for MacOs
VoiceOver Gestures on iOS

Before opening this PR, make sure you’ve done whichever of these applies to you:

Run git pull origin [base branch] to pull in the most recent updates from your base and check for merge conflicts. (Often, the base branch is develop).
Run npm test and confirm that all tests pass.

amyleadem · 2022-08-11T21:34:39Z

@mejiaj I wasn't sure how best to work with the previously merged PR, so I simply brought in the changes from that PR into this branch. Please let me know if there is a cleaner path.

mejiaj

Based on our testing, let's try using an aria label on the list items to improve how it gets announced via screenreader.

amyleadem · 2022-09-22T00:11:32Z

@mejiaj I made some updates to improve the readout in VoiceOver. Surprisingly, an <i> element generated a more reliable readout than the <span> (at least in VO). Will you check this on your screen readers and let me know your thoughts?

mejiaj · 2022-09-22T16:58:12Z

@amyleadem it does read better in voiceover! The only thing I've noticed is that the list item doesn't read out the updated status when I tab to it. Instead, it will just read the requirements without the current status.

The only way I can get the status to be read is to focus out and back in to the input element.

amyleadem · 2022-09-22T22:40:32Z

@mejiaj Switched it up a bit and generated an aria-label for the checklist items instead of generating a new text element. Will you let me know what you think?

mejiaj

Works well, on VoiceOver I was able to verify functionality has improved:

Elements read correctly
Validation requirements update and read properly

Component also still works when inserting dynamically.

I've added some suggestions for improving code and some questions about aria attributes on the input element.

packages/usa-validation/src/index.js

amyleadem · 2022-09-27T16:38:41Z

@mejiaj
Thanks for the helpful review. I wanted to show you one more possible approach that has gotten the cleanest readout so far and would not interfere with with the aria-label on the input. This option generates a span that is a peer to the input and checklist elements, has the aria-live and aria-atomic attributes, and gathers the status updates for all checklist items into a single element for readout.

The current proposed solution also generates an aria-label for each checklist item that includes the item's current status, so users can still get check the status of each individual element.

The only concern I have is that creating a fully new text element might be too clumsy and cause some unexpected problems. It would be great to hear your thoughts.

Additionally, I created an enhanceValidation() function, but I am not sure I fully understand how best to do this. Will you take a look and let me know if this is doing what you hoped?

mejiaj

@amyleadem it does read better. Added some thoughts below.

Overall, if we want the new status element we would have to link it to the input (which seems to be performing the same function as the list with aria-live="polite").

I do see the potential of this improving the experience, especially after seeing GovUKs character count recommendations in #4714. If we want to go that route we'd probably need to:

Link the input to this new status via a unique ID and aria-describedby
Set a delay on the status so it can finish reading user input and then give status

packages/usa-validation/src/index.js

amyleadem · 2022-10-06T18:55:13Z

@mejiaj
Thanks a ton for the helpful review. I believe I have addressed all the comments above. Please let me know if you see anything else!

Tasks completed:

Moved enhanceValidation to init in a57aff1
Added aria-describedby to input in a57aff1
Split out the functions in 853fb7d
Added a delay for the screen reader readout in 9162036
Updated handleChange() to be more explicit in aa38ecb

mejiaj

Looks good, the experience has improved for users on screen readers with the delayed announcement.

Added some suggestions we could use to improve code readability.

mejiaj · 2022-10-07T19:44:36Z

packages/uswds-core/src/js/utils/validate-input.js

+      let statusComplete = "status complete";
+      let statusIncomplete = "status incomplete";
+      let checkboxContent = `${validatorCheckbox.textContent} `;
+
+      if (el.hasAttribute("data-validation-complete")) {
+        statusComplete = el.getAttribute("data-validation-complete");
+      }
+
+      if (el.hasAttribute("data-validation-incomplete")) {
+        statusIncomplete = el.getAttribute("data-validation-incomplete");
+      }
+


We could simplify this by having these labels as a backup in case the dataset comes back null or undefined.

Suggested change

let statusComplete = "status complete";

let statusIncomplete = "status incomplete";

let checkboxContent = `${validatorCheckbox.textContent} `;

if (el.hasAttribute("data-validation-complete")) {

statusComplete = el.getAttribute("data-validation-complete");

}

if (el.hasAttribute("data-validation-incomplete")) {

statusIncomplete = el.getAttribute("data-validation-incomplete");

}

const statusComplete = el.dataset.validationComplete || "status complete";

const statusIncomplete = el.dataset.validationIncomplete || "status incomplete";

Clean! Updated in aea87ce

mejiaj · 2022-10-07T19:51:18Z

packages/uswds-core/src/js/utils/validate-input.js

+      ((debounce(() => {
+        statusSummaryContainer.textContent = statusSummary;
+      }, 1000)))();


Optional because we have the comment, but we can increase readability by extracting it to it's own updateSRSummary() and just calling it here.

I like that it could make it more consistent with the new character count setup. Updated in bfbfd52

(If I misunderstood your request, feel free to fix while I am out!)

mejiaj

Works well, tested for regressions and VoiceOver. Has a debounce function that was introduced in PR #4976.

thisisdano

Nice discussion and nice work!

Amy Leadem added 3 commits August 8, 2022 11:49

Pull in changes from cm-validation-a11y

0684b17

Remove aria-checked attribute

f077275

Add tabindex to usa-checklist

0a19319

amyleadem changed the base branch from develop to cm-validation-a11y August 11, 2022 16:28

amyleadem changed the base branch from cm-validation-a11y to develop August 11, 2022 16:28

Amy Leadem added 2 commits August 11, 2022 12:42

Remove tabindex from template

14f06bc

Add tabindex to validation list items

29c2b61

amyleadem marked this pull request as ready for review August 11, 2022 21:31

amyleadem requested a review from mejiaj August 11, 2022 21:31

mejiaj suggested changes Sep 14, 2022

View reviewed changes

Amy Leadem added 6 commits September 20, 2022 13:16

Add aria-label to input element

07ad7de

Change span to i

8b0bff8

Remove comma

abc6fb4

Add aria label on init

45cdf3d

Clean up code

511d666

Change innerText to textContent

6e89868

amyleadem requested a review from mejiaj September 22, 2022 00:11

Replace generated span with aria-label

2a56879

mejiaj reviewed Sep 23, 2022

View reviewed changes

Amy Leadem added 5 commits September 26, 2022 07:26

Create container for status summary; add status updates

8be3392

Replace 'item' with 'input'

34c5be9

Create data-validation-complete and data-validation-incomplete

eeb2e18

Create enhanceValidation function

7b53b94

Rename data-checklist-label to data-validation-status

c284450

amyleadem requested a review from mejiaj September 27, 2022 16:38

mejiaj suggested changes Oct 5, 2022

View reviewed changes

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

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

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

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

Amy Leadem added 10 commits October 5, 2022 14:55

Update package-lock

36a1de6

Add unique id to summary element

393d235

Rename change to handleChange

fb807ba

Remove input aria-describedby from twig

73b954f

Move selectOrMatches to init

a57aff1

Separate functions into createStatusElement and createInitialStatus

853fb7d

Add debounce

9162036

Update handleChange

aa38ecb

Pull in develop

545a7d9

Update statusSummaryID

ab76749

amyleadem requested a review from mejiaj October 6, 2022 18:55

mejiaj suggested changes Oct 7, 2022

View reviewed changes

Amy Leadem added 2 commits October 7, 2022 13:13

Simplify statusComplete and statusIncomplete data check

aea87ce

Add readability with srUpdateStatus()

bfbfd52

amyleadem requested a review from mejiaj October 7, 2022 20:35

James Mejia added 2 commits October 9, 2022 15:04

Consolidate handleChange function

e41d2fe

Run prettier

ef0c9db

mejiaj approved these changes Oct 9, 2022

View reviewed changes

thisisdano approved these changes Oct 11, 2022

View reviewed changes

thisisdano merged commit 5463f3a into develop Oct 11, 2022

thisisdano deleted the al-validation-aria branch October 11, 2022 20:25

This was referenced Oct 19, 2022

USWDS 3.2.0 #4997

Closed

USWDS 3.2.0 #4998

Merged

kleinschmidtj mentioned this pull request Jul 21, 2023

[fix] Improve screen reader experience of Validation trussworks/react-uswds#2510

Open

mejiaj mentioned this pull request Nov 24, 2023

USWDS - Validation: Allow textareas to use validation (Enhancement) #5233

Merged

mahoneycm mentioned this pull request Mar 11, 2024

USWDS - Bug: Remove focus on text in validation component #5760

Closed

2 tasks

mahoneycm mentioned this pull request Mar 25, 2024

USWDS - Validation: Remove ability to focus checklist items #5835

Merged

3 tasks

USWDS - Bug: Fix invalid aria role in validator list items #4914

USWDS - Bug: Fix invalid aria role in validator list items #4914

Uh oh!

Conversation

amyleadem commented Aug 8, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Details

Related issue

Preview link

Problem statement

Including the aria-checked attribute generates errors

VoiceOver produces a confusing readout

Solution

aria-checked

Confusing readout

Tasks completed in this PR:

Testing and review

Uh oh!

amyleadem commented Aug 11, 2022

Uh oh!

mejiaj left a comment

Choose a reason for hiding this comment

Uh oh!

amyleadem commented Sep 22, 2022

Uh oh!

mejiaj commented Sep 22, 2022

Uh oh!

amyleadem commented Sep 22, 2022

Uh oh!

mejiaj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

amyleadem commented Sep 27, 2022

Uh oh!

mejiaj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

amyleadem commented Oct 6, 2022

Uh oh!

mejiaj left a comment

Choose a reason for hiding this comment

Uh oh!

mejiaj Oct 7, 2022

Choose a reason for hiding this comment

Uh oh!

amyleadem Oct 7, 2022

Choose a reason for hiding this comment

Uh oh!

mejiaj Oct 7, 2022

Choose a reason for hiding this comment

Uh oh!

amyleadem Oct 7, 2022

Choose a reason for hiding this comment

Uh oh!

mejiaj left a comment

Choose a reason for hiding this comment

Uh oh!

thisisdano left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

amyleadem commented Aug 8, 2022 •

edited

Loading