Add section on linking to external sites on Component - Link and Content - Links

humancompanion-usds commented 1 year ago

Description

We need a sub-section on both Component - Link and Content - LInks (they already share content through a partial) for "Linking to external sites" that provides clear guidance.

Details

Josh provided the following feedback to a recent request on this matter:

There’s a couple ways of going about doing this, which may depend on y’alls context:

Including text within the link that indicates where they will go (e.g. Chronic B-cell leukemia on VA's public health site) But this might be a bit verbose for the context you’re handling if it’s repeated for every single link in the list

USWDS uses an external link icon (but gov uk debates its use here and removed it from their system due to the icon possibly causing confusion for sighted users)

Including text around those links that give the user a heads up that they will navigate to other websites, and consider using aria-describedby to connect them together

Use aria-label to create a screen reader only label that appends where they link out to

Provide a list of items that aren’t linked up, with one external link. For example:

List of Cancers

Learn more about these cancers on the VA public health website

I concur that the external link icon is more trouble than it is worth. The USWDS just says to use it consistently. It does not say that it has to be used. We don't use it in the footer today and I'm not inclined to start. I agree with the UK.gov folks that it adds noise and is a solution in search of a problem. That said, our position from the perspective of the Design System is unclear and we should provide guidance on this topic.

Tasks

[ ] Write guidance
[ ] Publish
[ ] Get a review from CAIA

Acceptance Criteria

[ ] Guidance on linking to external sites is provided on design.va.gov on the Component - Link and Content - Links pages.

humancompanion-usds commented 10 months ago

@megzehn - Danielle mentioned that you are working on updating the guidance in the content style guide on external links. Just wanted to point out that the guidance lives in this file and is shared across the content style guide and Link component guidance: https://github.com/department-of-veterans-affairs/vets-design-system-documentation/blob/main/src/_includes/content/links.md

Can you incorporate what Josh covers in this issue in the updates you are making?

megzehn commented 10 months ago

Yes, definitely! Thanks, Matt!

humancompanion-usds commented 10 months ago

I need to also add:

External links should have rel="noreferrer" added per USWDS guidance. They should open in a new window or tab.
The following sub-domains do open in a new tab:
- 'myhealth.va.gov',
- 'ebenefits.va.gov',
- 'www.accesstocare.va.gov',
- 'www.gibill.va.gov/wave',
- 'www.blogs.va.gov',
- 'www.data.va.gov',
- 'mobile.va.gov',
- 'www.accesstocare.va.gov',
- 'www.oit.va.gov'

laflannery commented 10 months ago

@humancompanion-usds we were chatting about this and it might be good to also include some sort of reasoning/explanation about why these particular subdomains are going against the standard link guidelines and opening in a new tab. That might help to avoid this same discussion with new folks coming across this in the future, they won't need to wonder why these decisions were made.

megzehn commented 2 months ago

When we wrote up this guidance, I assumed that we intended to have all external links open in a new tab since Drupal by default was opening all external links on static pages in a new tab.

But the consensus from IA and a11y is that we should not open external links in a new tab. @RLHecht is opening a ticket with CMS to change this.

Once we update the Drupal behavior, I'll create a PR to update our style guide.

CC @mnorthuis, @coforma-jamie, and @humancompanion-usds

coforma-jamie commented 2 months ago

To expand a bit on what @megzehn said:

Default to opening links in the same tab.

Open links in a new tab by when:

The user is signed into VA.gov, and opening the link will log the user out of their session.
Opening the link will take a user out of a form flow.
In both circumstances, consider whether the link is worth potentially taking the user away from where they are. Only add the link if its absolutely necessary.

mnorthuis commented 2 months ago

@coforma-jamie this bullet is challenging due to the injected header used in various VA.gov pages. User can lose their session going between modernized and legacy pages.

The user is signed into VA.gov, and opening the link will log the user out of their session.

coforma-jamie commented 2 months ago

@mnorthuis what's the current default behavior of those links in the injected header?

mnorthuis commented 2 months ago

The behavior of links in the header? The injected header links would behave the same as our header, however, there are other areas of the site that don't use our injected header, and instead have created their own version that looks almost exactly like ours. We do not know when that happens and can't control how they implement. So just moving around on VA.gov can create issues to someone's session and I don't believe we know which pages will.

coforma-jamie commented 2 months ago

I'm working on getting clarity on when exactly users get logged out from VA.gov (see Slack thread). That should better inform our rulemaking.

coforma-jamie commented 2 months ago

@mnorthuis, an update:

Users are automatically logged out after 30 minutes of inactivity (more info)
There are been instances where users are "randomly" logged out, for reasons unknown, that seem to have nothing to do with external links OR timeout
Eli and I tested a few scenarios involving external links opening in the same tab.
- After logging in on Staging as a test user, we tried the following on Mac+Chrome, Windows+Edge, and iOS+Safari:
  - Go to a legacy site (the “Fiduciary services” link at the bottom of the Disability landing page), then back to My VA
  - Go to a totally different page (the “YouTube” link in the footer), then back to My VA
  - Close out of the browser entirely, then reopen it and go to My VA
  - Shut down the computer completely, then turn it back on. re-open the logged-in browser and go to My VA
- Login was retained in all circumstances, except shutdown/startup on Windows+Edge.

Based on this information, I think it's safe to keep the recommendation to not open external links by default.

(Side note: We're already opening external links in the same tab - check out the "YouTube" link in the VA.gov footer! I tried logging in as a test user, going to the YouTube channel, then going back to My VA - the test user was still logged in.)

mnorthuis commented 2 months ago

Thank you for testing out those scenarios. I would also add that our identity providers are also technically external sites, and changing up how we present screens related to signing in, creating an account, or verifying your identity would likely introduce some issues as well.

Related to this, I'm also digging into whether we can eliminate the list of exceptions that we currently have for that rule.

coforma-jamie commented 2 months ago

Yes, we'd definitely want to test those scenarios as they come up.

mnorthuis commented 2 months ago

Final direction:

All links should default to opening in the same tab.
The only exception to this, is if the link is embedded in the content a form flow or task, and opening that link would cause the user to lose their place or data they've entered. This scenario should be avoided when possible. If the link does open in a new tab, the link label should clearly indicate that.
See the links section in the content style guide for information on link labels.

megzehn commented 1 month ago

Thanks, @mnorthuis! I made some initial changes on the content side and removed the list of subdomains and the guidance to open external links in a new window. This PR is ready for you or Danielle to review.

@humancompanion-usds, on the components page, I think we still need to tweak the "Behavior" section to replace what's there with Mikki's first 2 bullet items above. Do you want to make that adjustment, or should I add it to this PR?

humancompanion-usds commented 1 month ago

@megzehn - You can add the link behavior change to the PR you have. But I'm more concerned about making sure we actually update the code to behave as the guidance suggests. Those sub-domains are hard-coded to open in a new tab/window. That code needs to be altered to get the behavior you all want.

megzehn commented 2 weeks ago

Thank you for merging, Matthew!!

There are 2 open tickets to make sure that hard-coded features are updated to follow this guidance. I'll link those here and close this ticket.

department-of-veterans-affairs / vets-design-system-documentation