Documentation links are hard to spot

[thibaudcolas]

On the TypeScript website, links within the page content are hard to spot. There are two issues:

• Normal links are different from paragraph text in color only, with a contrast ratio to surrounding text that is too low (text: #242424, link: #265988, contrast ratio: 2.11:1).
• Links on code-style text are visually identical to code-style text without links

Example:

https://www.typescriptlang.org/docs/handbook/declaration-files/library-structures.html

Search Terms:

Website links, documentation links, documentation code link, accessibility

Expected behavior:

It should be possible to visually scan a documentation page and identify what is a link.

Actual behavior:

Links on paragraph text have a very low contrast ratio that makes them hard to spot. Links on code are impossible to spot, and it's very frustrating to have to hover all the inline snippets or try to guess which ones are links.

Related Issues: Couldn't find any.

---

I can see a few solutions to this:

• Style links based on something else than color. The established accessibility best practice is to use an underline.
• Pick a color for links that has high-enough contrast to surrounding text.
• For code links, display them with the link color rather than the code color #bf414a.

Relevant resources:

• https://webaim.org/techniques/hypertext/link_text#appearance
• WCAG 2.0 F73: Failure of Success Criterion 1.4.1 due to creating links that are not visually evident without color vision
• WCAG 2.0 G183: Using a contrast ratio of 3:1 with surrounding text and providing additional visual cues on focus for links or controls where color alone is used to identify them

[thibaudcolas]

I see the TypeScript website is now open source, so I’m happy to contribute a PR for this if there is some agreement on the preferred solution.

[orta]

Sure thing, I think:

• links in code should have the underline (and I'm cool with having a bolder red for contrast)
• Could #187ABF work for the text links? If not then I think having an underline is fine (I'm also OK with both too)

These entire styles should be switched out by the end of the year with a re-design I'm working on which shouldn't have these issues as it'll be based on the fabric design patterns

[ondrej-merkun]

I'd like to work on this.

[thibaudcolas]

I see this has been fixed in #98 – thank you @ondrej-merkun 🎉.