TOP001 - Descriptive link text labels

Tags: accessibility, links

Aliases: descriptive-link-text-labels

Fixable via script: Not fixable due to being context-based

This rule is triggered when a link has a text label that meets one of the following criteria:

• Uses the words "this" or "here"
• Exactly matches one of our blacklisted link texts (commonly used text labels that are insufficiently descriptive)

Example of links that have text labels that include "this" or "here":

You can read more about variables in JavaScript [here](https://example.com).
[This article](https://example.com) provides more information about closures.

To fix this issue, remove the words "here" and "this" and use more descriptive text that clearly conveys the purpose or content of the link. You may need to also update the surrounding text. The following code block demonstrates how the links from above could be fixed:

You can read more about [variables in JavaScript](https://example.com).
[An in-depth article about closures in JavaScript](https://example.com) provides more information.

Note that even if the text is somewhat descriptive, this rule will still flag occurrences of "this" or "here":

[Here is a comprehensive guide to understanding closures](https://example.com).

In this case, it's still better to rephrase the link text to be more concise and descriptive:

[Comprehensive guide to understanding closures](https://example.com)

Additionally, consider including relevant keywords in the link text to provide more context:

For more information, refer to the [official documentation on closures in JavaScript](https://example.com).

This rule is also triggered if the entire link text exactly matches any of our blacklisted texts, which consists of commonly used text labels that are not sufficiently descriptive while not containing "this" or "here". Examples include (but are not limited to) "video", "article", "an article", "docs", "the docs", "documentation", and "homepage":

For more information, watch this [video](https://example.com) about the CSS box model.
You can read more about it in the [documentation](https://example.com).

The above links can be rephrased to be sufficiently descriptive by themselves:

For more information, watch this [video about the CSS box model](https://example.com).
You can read more about it in the [Proc class documentation](https://example.com).

Rationale

Descriptive link text improves accessibility by providing clear and meaningful context about the link's destination. Links with text labels using the words "this" or "here" tend to be less descriptive and may not effectively convey the purpose of the link to users, especially those using assistive technologies. Similarly, text labels like "video", "article" or "docs" act in the same way for users of assistive technologies, requiring knowledge of the surrounding non-link text for context. By using specific and relevant keywords in the link text, you can enhance the user experience and make it easier for users to understand the context and purpose of the link.