Improve demo form error messages

[taylorkaren]

Context

From Ticket #557 (accessibility audit finding on the demo burial form reported by Tiffany Pender: The errors are vague. They all say something like "Please provide a response". This could be because this is a demo form, and if that's the case, no problem. However, if this is a default setting for the components, we should rethink that. Let teams define that on their own using our content guidelines.

Task Description

• Please review error messages associated with the demo burial form to determine if error messaging is a default setting for components. -- If yes, write a ticket for DST to remove those default settings. -- If no, compile a list of error messages and conditions that trigger their display on the demo burial form, reach out to Tiffany for content guidelines for error message text, and revise the error message text based on those guidelines.

Acceptance Criteria

• [x] Ensure that the default inline error messages utilize the input field's label so that the error is specific
• [x] Create documentation on how our library creates the default error messages and guidance on how to write them

[TiffanyPender]

@obliviga I've included below some sample content recommendations for error message text related to the Forms Library Core demo form.

For the error messages related to missing required field input, I suggest including text that lets users know what field(s) the error is related to.

• Scenario: Deceased Veteran Date of Birth field missing input
  • Error text: "Please provide a response for the Deceased Veteran's Date of Birth".
• Scenario: Deceased Veteran Date of Birth, Day field is missing input;
  • Error text: "Please select a Day for the Deceased Veteran's Date of Birth".

For the error messages related to invalid input, there seem to be a few different circumstances that could apply here:

• Scenario - Date of Burial entered as a date before the Date of Death
  • Error text - The Deceased Veteran's Date of Burial must be on or after the Deceased Veteran's Date of Death
• Scenario - Date of Burial missing the Month
  • Error text - Please select a Month for the Deceased Veteran's Date of Burial

[taylorkaren]

As of standup time today, Tiffany is reviewing changes that Anish has made.

[TiffanyPender]

After meeting with @obliviga to discuss, and some additional diving into the code, it sounds like the proposed format of “Please provide a response for [label]“ will work well as an error message in most cases. Teams will be able to customize instances where you may end up with and error message that may sound repetitive and need adjustment. For example - “Please provide a response for please specify claimant’s relationship to the deceased veteran”. The format of "Please provide a response for [label]“ does not work in this instance, and would need to be adjusted and customized by the individual team using the component. An assumption is that these types of instances are rare and for most cases the updated format will be fine.

[obliviga]

Thank you for providing that summary of what we discussed yesterday, @TiffanyPender. After meeting with you again today, and discussing this issue with my team, I think the only feasible resolution for this issue is to leave it up to the teams using our components to ensure that error messages are specific, much like how they already ensure that input labels are.

Appending the input label as screen reader text is an option, but we have reservations in doing that, as it would provide a difference experience to screen reader users. If error messages are specific to begin with, then all users would have the same accessible experience.

In my opinion, there are too many edge cases and side effects of appending the input label text to a default error message. It's best to leave the default error messaging vague, as that ensures flexibility to be compatible with all types of input field labels. Ideally, designers should be mindful that error messages should be specific for accessibility, so that engineers will follow the design and include that custom error messaging in our components they may use.

I'm going to close this issue, but please don't hesitate to reach out if you would like to discuss this further!

[obliviga]

@TiffanyPender, thank you for addressing your concern with me in Slack.

Next steps: Talk to Danielle Thierry or Beth Potts tomorrow for guidance on whether we refactor our default error messages.

[obliviga]

I reached out to Danielle Thierry for guidance on this, hoping to get an answer soon so this ticket can be wrapped up!

[obliviga]

After speaking with the content specialist and accessibility folk, we determined that the default error messaging template should be "{{ input label }} is required".

[obliviga]

I've asked the accessibility team how to handle error messages when the input label is a question, like "Did the Veteran serve under another name?".

[obliviga]

Received guidance from the content specialist on the above and am unblocked.

[va-vsp-bot]

:tada: This issue has been resolved in version 1.6.2 :tada:

The release is available on GitHub release

Your semantic-release bot :package::rocket:

[obliviga]

Here's the associated documentation: https://vfs.atlassian.net/wiki/spaces/FLT/pages/2354840100/Default+Inline+Error+Messaging+for+Input+Fields

[obliviga]

Verified this has been deployed to the main branch.