Links

Considerations

• We use links to connect Veterans and other visitors with related information that may be helpful to them.
• We also use links to help us centralize information, rather than repeating content in multiple places. This helps us update content more efficiently and keep content accurate.
• We put links on their own line to help make the page easier to scan and the intention of the link as clear as possible. Too many embedded links can be distracting or overwhelming to people with traumatic brain injuries or other cognitive impairments.
• We tell people where links are taking them and why. External links can be disorienting for all people, but especially people who use screen readers.
• For issues not covered in this style guide, refer to the U.S. Web Design System (USWDS) on links.
  Review link guidance on the USWDS website

Link text

• Use natural and descriptive language
• Describe the purpose of the linked page
• If the link takes the reader outside of VA.gov, name the external website in the link text
• Balance link text length to provide the needed descriptions without having the relevant words get lost in the length
• Use “Select” instead of “Click here,” since not all people are physically clicking links
• Avoid generic link text like “Learn more” and “Read more” by themselves
• Avoid using words that assume certain abilities, like “See,” “Hear,” and “Watch”

Review more guidance for neutral language

Note: If a link needs to open in a new tab, add “(opens in a new tab)” to notify the person. Don’t use the new window icon unless there are space constraints.

Review guidance on when to open links in a new tab in the Components section

Formatting

• Don’t punctuate link text. Exception: Question marks and colons are OK if they’re part of the link copy.
• Create space between different links. Clustering links together can make it hard for users to select the intended link, especially on a touch screen device, like a smartphone.
• In general, put a link on a separate line to help it stand out. Have a case where you think an inline link might be necessary due to space limitations? Contact the centralized content team for help with your content.

Linking to the main VA website

When linking to a page, tool, or online form on VA.gov, always link to the canonical URL of the page. The canonical URL—which can be suggested and influenced by us, but is ultimately determined by search engines—is what appears in search results.

For form flows, the canonical URL excludes the reference to a specific page in the flow or initial page displayed in the flow.

Example:

• Don’t use a URL to a specific page: va.gov/health-care/apply-form-1010ez/introduction
• Do use the canonical URL: va.gov/health-care/apply-form-1010ez/

In addition, on modernized VA.gov, many pages—particularly static unauthenticated pages—often end in a trailing slash. To find out if you should use a trailing slash, check the live URL that is displayed for the page after you open it in a browser.

Example:

• Don’t use the URL without the trailing slash: va.gov/health-care
• Do use the URL with a trailing slash: va.gov/health-care/

When we use the canonical URL in links, it reduces the risk of links breaking when sub-URLs in a form or flow change. It also helps tell search engines our preferred URL for search indexing. This can add search value to the canonical URL by eliminating the split of search value between multiple pages.

Linking to forms

For VA forms stored in the forms database, link to the form’s About page rather than directly to the PDF version of the form. This ensures we’re always linking to the most current version of the form. This guidance applies to links in all content except for the form’s About page.

On a form’s About page, include a direct download link to the PDF of that form.

For forms that aren’t part of the VA forms database, you may need to use a direct download link to the PDF version of the form. This is a rare situation. Contact the centralized content and information architecture (IA) team for guidance.

You may also need a direct download link if the person filling out the form is downloading and generating their own completed copy. Contact the centralized content and IA team for guidance.

Linking to documents and other file sources

• Avoid linking to PDFs as much as possible.
• If a link opens a calendar, YouTube video, XLS, or other file format, add the relevant icon from the Components section in the Design System. This does not apply to pages housed within Drupal.
  Review examples of link variations in the Components section
• Include the file format (ex. PDF, HTML, or XML) in the link label. Place the file format at the end of the link label in parentheses. For example, “Download the Continuity of Care document (PDF).”
• If you have a list of links to the same document with different file formats, consider rewording the link text to include the file format earlier. Contact the centralized content and IA team for help with your link text.

Linking to external sites

• Use a link label that tells the reader where the link takes them. Example: Check COVID-19 symptoms on the CDC website
• Consider using an aria-label to create a screen reader-only link label. Aria-labels can be helpful in specialized instances where there’s a clear reason to use separate text for people who use screen readers. The aria-label may append or replace text within a link to provide context about where the link goes.
• Avoid linking to the Code of Federal Regulations (CFR). On VA.gov pages, don’t add links to CFR references.

Links in lists

• List items can be links in certain situations. But we don’t want to overwhelm people with a long list of links, if possible.
• Not all items in a list need to be a link. It’s OK to have only 1 or 2 items in a list linked.
• If every item in a list is a link, keep the list short (less than 7 items). Every link should go to a different location—don’t link to the same page multiple times in the list.
• If 1 link applies to all items in the list, add the link on a separate line after the list.

There are 3 options for adding links to list items. The formatting depends on what fits best with the content. The VA.gov content and IA team can help you pick the best option for your content.

Option 1

For lists with only a few items that have relevant links, add the links on a separate line after each list item. Use a soft return (shift + enter on PCs, shift + return on Macs) so the link appears on a separate line, aligned with the list indent, with no space between the lines.

Option 2

When you have a list of brief items, make each of the list items a link. With this option, include the entire list item as part of the link. Don’t link just 1 or 2 words.

Option 3

If options 1 and 2 don’t make sense for the content, add the link at the end of the item as a separate sentence.

Privacy guidance

Link text should avoid Personally Identifiable Information (PII) or Protected Health Information (PHI) whenever possible.

If link text must include PII/PHI, click events can’t be tracked for that link.

• This ensures the information isn’t tracked back in analytics or other logs through the link text
• Teams will either need to consider other approaches to link text that don’t contain PII/PHI or find ways of getting site data other than the click events on those links

Links can’t pass PII/PHI as any part of a parameter or destination URL. Teams will need to utilize non-PII data or generate a non-PII number to use as an identifier.

Learn more on the URLs component page

File downloads

• No PII/PHI can be in the names of downloaded files except for the user’s name and download date
• Include a reminder to delete files on a public computer

Examples:

• A medications list page has several list items for medications prescribed over time. In this scenario, the medication name is a link they can select and is considered PHI. The click events for those links can’t be tracked in analytics.
• A list page with several lines and each item is a link they can select. The links for those list items pass a number as a parameter to display the corresponding detail page. The number passed is partly made up of the user’s Social Security number plus additional digits. The Social Security number is considered PII even though it’s combined with other information and not labeled as a Social Security number. In this case, generate a generic ID as an identifier for the detail page. The file number can be displayed on screen but can’t be passed in the URL/link destination.

Learn more about PII/PHI on the VA Platform website