Finalize design for FL AutoSuggest interface

[davidmpickett]

User Story or Problem Statement

Last year we mapped out some key steps in the flow, but we may need to get more granular to unblock engineers now that we're getting ready to implement

List of services with associated fields

Design

Autosuggest page in Facility Locator Figma

Defined Behaviors

Search functionality

• Minimum number of characters to be entered before matches are displayed
  - Minimum number of characters is 2.
  - This matches community providers.
  - We can test behavior in usability testing.
• Maximum number of service suggestions to display
  - All suggestions that match what a users types in should display.
  - The USWDS combo box component doesn't have guidance on this.
• Sort order for matched suggestions
  - Only "starts with" for now.
  - We can test behavior in usability testing.
• Expected behavior when user enters additional letters after suggestions are displayed
  - Continue to winnow
• Maximum number of characters to display for each match
  - Show full "Name (Known As)" in search dropdown
  - Most results will be 1-2 lines, a couple of results will be 3 lines
• Text displayed when matching on data other than Term Name
  - Show "Name (Known As)"
  - We should not show words from description field in search results, but we should still search for them in the background. This should be fine now that the highlight isn't there anymore and looks to be how the 526EZ autosuggest is working.
• User enters keywords but the matches that are returned are not what they're looking for
  - When typing into search field: The "View all health services" solves for this and gives them an option.
  - When submitting search: For now, no changes. If this is a problem that comes up in usability testing then we can tailor the no results wording to have more specific next steps.
• "View all health services" search
  - Show in field before user starts typing and always show in dropdown.
  - Usability test this and consider rewording to something like "View facilities in the area" (Michelle's comment) or changing the help text to "Filter search results by..." if it doesn't test well.
  - Current users are able to select "View all health services" from dropdown and search for everything. (Relevant ticket)

Design

• Placeholder text in field (similar to "like Chiropractor or Optometrist" for Community providers)
  - Remove placeholder and dropdown and add hint text.
  - Placeholder text is not great for accessibility because it goes away once they start typing.
  - When a user first clicks into the field, a dropdown appears that says "Search for an available service." This also isn't ideal because it's very inconsistent on if/when it's read by a screen reader.
  - Community providers and VA health will need different help text.
  - Community provider hint text: "Begin typing to search for a service, like Chiropractor or Optometrist."
  - VA health hint text: "Begin typing to search for a service, like vision or dental." (TBD)
• Search visual styling
  - Use the combo box component
  - This is a USWDS component that has been added to the component library. The DST is working on adding it to the DS in their upcoming sprint and expect it to be ready in February.
  - Jordan and Dave went to the Design office hours on 1/6/2025 to confirm that we can use the combo box.

Error states

• If user doesn't select a service type
  - On enter or clicking search button: If nothing is selected, "Start typing and select a service type." error is displayed.
  - Error message in Figma
• If no results are returned after search
  - No results message in Figma
• If user enters keywords but no services are returned
  - Show "No results found. Search for a different service." in dropdown
  - Error message in Figma

Miscellaneous

• Are popular searches MVP?
  - No.
  - Removed from mockups
• Updates to the 526EZ autosuggest field
  - The Contention Classification team own the 526EZ form
  - To test their autosuggest field, use this staging link to their prototype.
  - Since looking at this a year ago, they have updated designs in Figma and conducted a research study on the autosuggest input field

Tech feasibility questions

• What, if anything, can we do about misspellings/typos? Is there a "best bet" equivalent which can be used?
  - From Eli: Well, not really, because we're not doing fuzzy search. So the "best bet" is generally the pattern that Michelle and Michael came up with which is match in the name, if not secondary matches in the common conditions from the start of one of the conditions, if not match something that's in the description. If we wanted to do fuzzy search, we'd need to bring in a library for that where if someone typed "dyalisys" rather than "dialysis" it'd match that.
• How might we learn which keywords are searched and unmatched?
  - From Eli: We could definitely add analytics to show when no results come back from a search
• How much control do we have over the order of options in the suggested list? Will they be sorted alphabetically, or are they weighted by what field the string matches on?
• Given that we will be reducing the list of options based on user input, can we have an option that's always present? AKA no matter what a user types "All health services" remains in the list of options. Looks like the combo box guidance says we can use a default, but we want to check that it will always display in the dropdown.

Acceptance Criteria

• Review the 526 form to align where possible
• Show desired behavior in Figma file
• Add design and accessibility annotations
• Review with UX Lead, Accessibility, and Engineering

[jilladams]

Thread here asking if #19484 and #18960 are dupes or not: https://dsva.slack.com/archives/C06S9DADEUB/p1730932102417359

[thejordanwood]

Notes for myself whenever I start on this ticket:

• Sometimes the match is only in the description, which can be long. How does that show in the dropdown? Does it?
• What to do when the same word appears multiple times in different parts of the same service (i.e. "chest")
• User story: I type the word "eye" into the search field. What shows?
  • Look at data to determine this. Data wasn't used for term matching originally.
  • Current functionality has phrases like "diabetic eye loss" that is being handled as one word. Searching "eye" wouldn't show this.
• What if none of the suggestions are what they want? What message shows? How do we know when this happens?
  • Do we show the alphabetized list? (Figma link)

Example of data:
Service: Thoracic surgery
Plain language: Chest/lung surgery
Description: We perform chest surgery (also known as thoracic surgery) to treat conditions involving your chest, airway, and esophagus.

[mmiddaugh]

Error message needed for the following user stories:

• As a Veteran, I need to know what to do when I enter keywords but no services are returned.
• As a Veteran, I need to know what to do when I enter keywords but the matches that are returned are not what I am looking for.
  (this might need to include a suggestion to choose a different facility type)

Other questions to answer

• What is the maximum number of characters to display for each match?
• How might we learn which keywords are searched and unmatched?
• What, if anything, can we do about misspellings/typos? Is there a "best bet" equivalent which can be used?
• Will the field suggest the expected type of entry, similar to "like Chiropractor or Optometrist" for Community providers?

[jilladams]

@Agile6MSkinner re: ACs, need to add / update

@davidmpickett can we talk about this in UX sync to finish refining / points?

[eselkin]

What, if anything, can we do about misspellings/typos? Is there a "best bet" equivalent which can be used?

Well, not really, because we're not doing fuzzy search. So the "best bet" is generally the pattern that Michelle and Michael came up with which is match in the name, if not secondary matches in the common conditions from the start of one of the conditions, if not match something that's in the description.

If we wanted to do fuzzy search, we'd need to bring in a library for that where if someone typed "dyalisys" rather than "dialysis" it'd match that.

How might we learn which keywords are searched and unmatched?

We could definitely add analytics to show when no results come back from a search

[thejordanwood]

End of sprint update:

We discussed this in UX sync on 12/19, but were unable to get through every behavior recommendation outlined in the "Needs review" section. This will roll into next sprint to leave time for reviews and adding annotations.

[mmiddaugh]

What is the intended behavior when someone chooses "View all health services"? The label might be a misnomer unless the user is given a way to view all available services. If we actually intend to return a list of the facilities in the specified area, we may want to change the label to something more representative, such as "Find a local facility" or "View facilities in the area".

[thejordanwood]

We can use the combo box!

• Dave and I went to the Design office hours on 1/6/2025 to confirm that we can use the combo box.
• This is a USWDS component that has been added to the component library. The DST is working on adding it to the DS in their upcoming sprint and expect it to be ready in February.

cc: @davidmpickett @Agile6MSkinner

[Agile6MSkinner]

@thejordanwood Does this mean we are unblocked to start development?

[thejordanwood]

@Agile6MSkinner Not quite. I still need to update the Figma designs to show the combo box and there are a couple of open tech feasibility questions in the Figma comments. I believe this should be wrapped up by the end of the week.