[A11y] Inline links not visually distinct from text

[ritiupa]

axe-core flags link-in-text-block (serious) on /reference/ and /reference/p5/circle/. Inline links inside body text are only distinguishable by color. There is no underline or other visual indicator. This fails WCAG 1.4.1 (Use of Color).

Examples:
The p5.sound link in the intro paragraph on /reference/
The ellipseMode() link inside body text on /reference/p5/circle/

Steps to reproduce:

1. Go to /reference/ or /reference/p5/circle/
2. Run axe DevTools or npm run test:a11y
3. See link-in-text-block violation

Expected: inline links should be visually distinguishable without relying on color alone, for example by adding an underline.

I searched open and closed issues before filing. No existing issue covers this rule in this repo.

@coseeian, flagging for label review.

[coseeian]

Hi @ritiupa, thanks for bringing this up.

I’m actually aware of this one - it’s been on my radar. The reason I haven't opened a dedicated issue for it yet is that, while adding an underline is trivial from a purely engineering standpoint, the broader scope requires a discussion with the p5.js product owner. We need to evaluate whether making underlines the default is acceptable to the design direction of the entire site, or if we can potentially introduce an accessibility preference toggle, similar to what GitHub does.

Because of these larger product decision scope, I wanted to avoid opening a public issue that contributors might immediately jump into fixing before we have a defined direction.

I’ve assigned this to myself for now. I'll find time to work on this and sync with the product owners about their thoughts.

[ksen0]

Thanks @coseeian and @ritiupa , I've added this to the Usability&Design issue. To my knowledge, nothing is in the way, we could add underlines. However, it would be good to get some feedback on this. I will share this question with the PF team and on the p5js-web and maintainers discord channels. If there are no objections before end of day (anywhere on earth) July 20th, then I think this work can be unblocked. If there are any objections then we can consider how to address them in a way that ultimately improvs site accessibility.

I think if there are other problems like this - simple to execute and relatively isolated but pending a decision - we can approach in the same way: Make a "discussion" issue that does not accept volunteers before a decision is reached; share widely for a week; proceed when there is consensus. Though it would be good not to open too many such discussion issues simultaneously, if possible.

[limzykenneth]

Links currently have underline on when hovered over, is the idea to switch that to always be underlined instead?

[ksen0]

@limzykenneth yes, so they are more clearly links before interaction occurs

[doradocodes]

I agree, I think it's a good idea to have links to constantly have an underline, rather than only on hover, especially on mobile when there is no hover state. I think it makes links more distinguishable.

[davepagurek]

I'm in favour of this, on a practical and also aesthetic level!

[SableRaf]

A relevant passage from https://www.w3.org/WAI/WCAG21/Techniques/failures/F73

Red and pink are the same color (hue) but they have different lightness (which is not color). So red and pink would pass the requirement for "not distinguished by color (hue) alone" since they differ by lightness (which is not color) - as long as the difference in lightness (contrast) is 3:1 or greater.

Links on the p5.js website are just shy of passing the contrast requirements (screenshot below).

So it seems the question, as @ksen0 wrote on Discord is: do we have a design preference between slightly increasing color contrast and persistent underline? (or both I suppose)

[ksen0]

Hi all! Since there have been no objections (we've shared this link also on social media and with the team), let's unblock adding underlines to links in text bodies.

@ritiupa can you help make that more precise? Ie only body text, right?

[coseeian]

Hi everyone, I just got back and caught up on the thread. Thanks for pushing this forward and facilitating the discussion!

I really appreciate the decision to go with persistent underlines rather than an accessibility toggle - it simplifies things significantly and (theoretically) keeps it to CSS changes only. Increasing the color contrast slightly alongside adding underlines sounds like a great move if we can do both.

Starting with underlines for body text links seems like a solid first step. To keep things manageable, we can decouple the color contrast adjustment and any other potential scope changes into separate tasks/PRs so we don't get blocked waiting on them.

If this direction works for everyone, I'll open a PR for the link underlines within .rendered-markdown first.

[ksen0]

Thanks @coseeian ! Please go ahead with the underline PR, and everyone can review that one to make sure we have the same understanding of scope.

I am happy for more contrasting colors as well but +1 on keeping this as a separate design discussion to keep us from getting blocked.

[coseeian]

Here is the PR for adding link underlines within .rendered-markdown: #1528
I've checked this across several pages listed in the site navigation, and things look good on my end. Let me know if I missed anything! :)