SPIKE: CMS: Phone number validation and guidance

[jilladams]

User Story or Problem Statement

As a CMS Editor, I want to clearly understand how phone numbers should be entered in the CMS, so that consistent information is provided to Veterans.

Description or Additional Context

Right now Drupal does not enforce any validation on Phone numbers. Phone numbers are entered as strings, and for Facility content types, Lighthouse receives / delivers phone numbers as strings.

Phone numbers have complex use cases, so we need to consider the use cases before implementing validation. A not-comprehensive list that can be expanded on:

• 988 (Veterans Crisis line)
• extensions
• * options
• international numbers

VA Design system phone number guidance

https://design.va.gov/content-style-guide/dates-and-numbers#phone-numbers
As of 10/16/23:

Phone numbers

Using the Telephone component will apply the following formatting and accessibility guidance:

• Use hyphens between numbers, and don’t use parentheses to set off the area code: 212-123-1234.
• Use +1 only when the information is specifically addressing Veterans or people who are living outside the U.S.: +1-201-123-1234.
• For phone numbers with an extension, use ext. at the end: 202-123-1234, ext. 9.
• Always include days and hours of operation when listing a phone number.
• Use “select” to indicate the menu option after dialing a phone number.
• Use a verb ahead of the number. Use “call” or “call us at…” for phone numbers and “text” or “text us at” for text numbers.
• Hyperlink all phone numbers, including TTY numbers. It is not a requirement to link the “call” or “text” verb that precedes the number. We do however include “TTY” in the link and aria-label to make it clear that it’s specifically for TTY so that users who need the service see it and so those who do not do not unintentionally call a TTY number.
• Include an aria label using spaces between the digits and periods between sections in order to have screen readers read the phone number one digit at a time like a phone number, rather than as thousands or hundreds. For example:
  • 800-827-1000
• TTY: 711.
  If for some reason you cannot use the Telephone component, you are responsible for meeting the same formatting and accessibility guidance when creating links to phone numbers.

Don’t use vanity phone numbers in body copy

We don’t use vanity phone numbers in body copy, as it adds visual noise and is not helpful to screen readers. We use and hyperlink only the numeric phone number in body copy.

• Exception: In marketing or promotional messaging, such as the right rail promo component, we discourage but make an exception for vanity phone numbers. In marketing or promotional components, use the format: 877-222-VETS (8387) and hyperlink the complete number including the parenthetical.

Like this:
Call us toll free at 800-827-1000. We’re here Monday through Friday, 8:00 a.m. to 9:00 p.m. ET.

Affected content types / entities

• Facility Health services (VAMC, VBA, Vet Centers)
• VAMC
  • VAMC System Billing & Insurance
• Vet Center
• Regional Office
• Support Service

Steps for Implementation

Acceptance Criteria

• Design / Drupal eng have mutually agreed on a proposed treatment for validating phone numbers in CMS
• CMS collab cycle review (?)

[xiongjaneg]

per Michelle in Slack
since phone number validation is rather messy and since it doesn't present a risk to LH accepting the data, validation can be something for the CMS team to consider for the future

[jilladams]

@BerniXiongA6 @EWashb FYI: Facilities cut this ticket today, not high priority on our end but documenting the conversation we had about opportunity here. Both CMS and Facilities teams are tagged, as we (Fac) could pursue in future via CMS Collab Cycle, or y'all might opt to look into it.

[EWashb]

Thank you @jilladams! This may be related to some things that @laflannery was doing regarding an audit, etc. May want to check in with her as well.

[davidmpickett]

From @laflannery audit:

There is some existing validation on the Phone paragraph type fields.

• There is a max length of 12 in both the phone number field and the extension field.

  • This max length however is not indicated anywhere, even when the user bumps up against it they aren’t told what is happening, they just aren’t able to continue typing into the field.
  • This could potentially be an issue with International phone numbers, if folks attempt to add the +1 the entire number will not fit.

• If the format of the content in the Phone number field didn't match the help text exactly, the node wouldn’t save.

  • Examples I tried:
    • 1234567890
    • (123)4567890
  • Upon trying to save I was presented with a validation error:

• The Extension field on the other hand did not have validation that matched the help text

  • The help text said to enter only numbers, but the content could be successfully saved with non-numerical content (e.g. “ext. 123”)

[Agile6MSkinner]

@davidmpickett @jilladams @omahane @laflannery Supposedly this is blocking a ticket that is blocking VBA pilot rollout. Do we really not have an agreed path forward on phone numbers or can we close this and move on?

[davidmpickett]

This is an old ticket that can probably be retired. Laura's audit covered a lot of use cases.