Improve static map images

[aklausmeier]

[2024-11-27] Need a refinement / product judgment call on UX options for how to handle in this comment

Description

During an accessibility audit of the Vet Center product and during VBA Regional office staging review, accessibility and design improvements were identified for the static locations map image, link, and zoom link/icon, that is used across all facility types.

Areas identified for improvement

• Remove the expand icon because this is misleading
• Change the alt text to "Static map - Get directions on Google maps to {Facility name}"
• Keep the link but open in the same tab for new guidance

VBA

e.g https://www.va.gov/portland-va-regional-benefit-office/

Markup screenshot

Vet Center

https://www.va.gov/portland-or-vet-center/

Markup screenshot

VAMC

https://www.va.gov/minneapolis-health-care/locations/minneapolis-va-medical-center/

Markup screenshot

Engineering notes / background

Map image, alt text, and zoom icon are set here in a widget that's used across all facility types: https://github.com/department-of-veterans-affairs/vets-website/blob/main/src/applications/static-pages/facilities/FacilityMapWidget.jsx#L67

Testing

Changes are made in one place that applies across many page types, and should be sanity checked in all instances to verify:

• VBA Regional office
• Vet Center page
• Vet Center locations page
• VAMC
• VA Clinic

Acceptance Criteria

• Facility image and map image / link need are close to facility address data in the markup, and are read in order by screen readers
• Image alt text should be "Static map - Get directions on Google maps to {Facility name}"
• va-icon zoom_out_map is removed and does not appear in markup
• Map link should open in same tab (target="_blank" is removed)
• When verified, also close Staging Review finding: Icon on map image not actually a button, not focusable. va.gov-team#87426
• Accessibility review
• QA testing complete
• When verified, close the following Collab Cycle tickets:
  • Staging Review finding: Alt text for map doesn't describe link destination. va.gov-team#87425
  • Staging Review finding: Icon on map image not actually a button, not focusable. va.gov-team#87426
  • Staging Review finding: Image placement within document could be confusing for some users va.gov-team#87429

[aklausmeier]

Description

During an accessibility audit of the Vet Center product, accessibility and design improvements were identified and have an opportunity to be improved across all facility types.

Areas identified for improvement

• alt text should describe the map image not the purpose of the link
• map image link can stay, was considered for removal but no harm in keeping
• remove expand icon from static map image, this is not materially honest and not necessary

Acceptance Criteria

• Identify which templates these images are present on
• Consider if work can be done in one ticket or need to be broken up into products
• Accessibility review
• QA testing complete

[laflannery]

Just clarifying a couple of the bullets above:

• alt text should describe the map image not the purpose of the link
• map image link can stay, was considered for removal but no harm in keeping

IF the link on the map image remains, THEN the alt text must describe the purpose of that link. In which case it's going to be duplicative of the visible "Get directions" link already on the page.

• That was why I was recommending that we remove the link, because we don't really need this here since we already have a directions link

IF we remove then link from the map image, THEN the alt text should describe the map as that is now the purpose of the image on the page.

[laflannery]

@aklausmeier and I discussed and decided we should:

• Remove the expand icon because this is misleading
• Change the alt text to "Static map - Get directions on Google maps to {Facility name}"
• Keep the link but open in the same tab for new guidance

[jilladams]

There's an additional report from VBA staging review in department-of-veterans-affairs/va.gov-team#87429 that belongs in here, if we suss out how to address it.

Basically: the placement of the location and map images get disconnected from the address data depending on your zoom / screen size / if using a screen reader, because they're in a right column / floated right, and then get stacked. We need to find a way to keep them closer to address data in the markup.

Full description from 87429

Description

In the "Location and contact information" section, here's where the images of the facility and the map are placed:

• On desktop -- floated to the right, in close visual proximity to the facility address
• On mobile/at high zoom -- stacked above the "Address" H3, still in pretty close visual proximity
• Via a screen reader -- at the end of the "Location and contact information" after the "Office hours" section

This potentially impacts users in a couple of ways:

• For non-sighted screen reader users, they'll hear the alt text for the two images in a context that might be a little confusing, after all of the facility hours have been announced. I wouldn't expect most screen reader users to go searching for either image, but if they were to look for it, they wouldn't expect to find it under "Office hours."
• For partially-sighted screen reader users, you might listen to the page while tracking along visually (eg. some low-vision users might be able to perceive the section headings at high zoom but might rely on their screen reader for smaller text). As they track the flow of the text down the page, they track the flow of information down the page as it's announced, then get lost when the content being announced jumps up to the top of that section, then jumps down again to "Prepare for your visit."

The actual impact here is relatively minor --- the two images in the right-hand column aren't critical to understanding the page. But it's still a potential point of friction.

Link, screenshot or steps to recreate

The two-column layout is coded roughly as:

<h2 ...>
   Location and contact information
</h2>

<div ...>
   <div ...>
      [all of the text]
   </div>

   <div ...>
      [both images]
   </div>          
</div>

... with CSS stacking the second div on top of the first div for small viewports. Screen readers will read top to bottom regardless of CSS positioning.

Recommended action

Preferred option would be to explore some CSS layouts that keep the images in in the same chunk of content as the address and "Get directions on Google Maps" text. That's what they're most closely related to, that's where it makes sense for them to be.

Next-best option would be to flip the order:

<h2 ...>
   Location and contact information
</h2>

<div ...>
   <div ...>
      [both images]
   </div> 

   <div ...>
      [all of the text]
   </div>         
</div>

... with CSS to float the images to the right. It's not ideal but I think it would be an improvement overall. That would ensure the document order and screen reader experience would match the small viewport experience, and keep both of those images in pretty close proximity to their related content.

[laflannery]

Jut to clarify - the columns aren't floated. The columns display properly on all breakpoints <480 but on mobile (<481) the column containing the image and map is moved using the CSS order property which breaks accessibility because it moves this visually but the DOM remains the same.

The options are:

1. Remove the order property on mobile:

• PRO: This will make the image and map visually match the DOM order
• CON: The image and map will be even further away from the Address because it will be below the entire 1st column
  

2. Duplicate the image/map, add it into the proper place in the DOM and only show the correct one on desktop/tablet/mobile:

• PRO: The image and map can remain in the same place as it is on Desktop/tablet but mobile can have a different, correct display
• CON: Duplicate content is not ideal. When edits need to be made the duplicate can sometimes be forgotten and edits are only made on Desktop for example.
  

3. Think mobile first. Find a solution where the image and map are in the mobile DOM order and that also works with Desktop

• PRO: On all devices, the visual order and the DOM order will match
• PRO: No duplicate content
• CON: Will take additional effort to find a possible solution

[laflannery]

@Agile6MSkinner Another I would like to discuss tomorrow

[jilladams]

From planning: we'd like to get this done, but we need to review comments and determine the path forward. @Agile6MSkinner a candidate for refinement.