[DESIGN] Test and validate language for SSN input

[kalasgarov]

We need to ensure that the Social Security Number (SSN) input field validates according to a specific set of requirements. This includes clear communication of error and hint messages to the user. Our objectives are to:

• Confirm the language used for validation requirements.
• Determine how error messages and hints will be displayed to users.

Requirements:

• Validation Requirements: Ensure the SSN follows the format and rules specified (e.g., must be exactly 9 digits, cannot start with certain prefixes, etc.).
• Error Messages: Clearly communicate what is wrong with the input when validation fails.

Related links:
https://www.ssa.gov/kc/SSAFactSheet--IssuingSSNs.pdf
https://designsystem.digital.gov/patterns/create-a-user-profile/social-security-number/

[JennyRichards-Flexion]

Add a link or screenshot from Storybook to this ticket.

[kalasgarov]

Current SSN Error messages:

[nichole-aquino]

@kalasgarov Here is my WIP (Figma) – I will finalize these after design review tomorrow and update the ticket once ready. Essentially, the error messages aim to describe what went wrong, and where, in plain language. The error UI also is updated to reflect USWDS styles.

Error type: Invalid set of digits in all locations.
Error message: Social Security Number must have a valid set of digits at the beginning (not 9, 666, or 000), a valid set of digits in the middle (not 00), and a valid set of digits at the end (not 0000).

Error type: Invalid set of digits at the beginning.
Error message: Social Security Number must have a valid set of digits at the beginning (not 9, 666, or 000).

Error type: Invalid set of digits in the middle.
Error message: Social Security Number must have a valid set of digits in the middle (not 00).

Error type: Invalid set of digits at the end.
Error message: Social Security Number must have a valid set of digits at the end (not 0000).

Error type: Invalid set of digits in the middle and end.
Error message: Social Security Number must have a valid set of digits in the middle (not 00), and a valid set of digits at the end (not 0000).

Error type: Invalid amount of digits.
Error message: Social Security Number must have exactly 9 digits.

[nichole-aquino]

hi @kalasgarov , after much thought, our design recommendation is to just provide a general error message "Enter a valid Social Security number" for all client-side validation. Here is our rationale:

• If there are multiple errors, the error message would get quite long and outweigh the benefit of identifying where exactly an error occurred (in a likely instance, someone may have just entered a typo or was mistaken about what the SSN is). A long message, for example, would be:

Social Security Number must have a valid set of digits at the beginning (not 9, 666, or 000), a valid set of digits in the middle (not 00), and a valid set of digits at the end (not 0000).

• There isn't any existing documentation on error state variants for SSN, so this would warrant further research to understand the use case better and test, if needed, the most appropriate copy.

Do let me know if you have any questions.

[kalasgarov]

Hi @nichole-aquino, thank you for following up on this! I agree that sometimes error messages can become too lengthy. I see the value in providing only short and generic error messages for SSNs. The detailed guidelines are more relevant for SSN issuers rather than SSN holders. SSN holders should simply enter their number as printed on their SSN cards.

Could you please include this change to the follow up engineering ticket on error states update.

[nichole-aquino]

@kalasgarov No problem, the ticket should be up to date but let me know if you need further details (#461)