Navigation Link: Improve accessibility by removing non-interactive tooltips

[himanshupathak95]

Fixes: #68597

What?

Improves accessibility in the Navigation Link block by replacing tooltips with visual states for invalid and draft links.

Why?

The current implementation misuses tooltips to show additional information about link states. This creates accessibility issues.

Testing Instructions

• Test Missing Link State:

  • Add a Navigation block
  • Notice the "Add link" placeholder with a wavy underline
  • Verify no tooltip appears on the hover

• Test Invalid Link State:

  • Add a Navigation Link block
  • Link it to any post
  • Move that post to the trash in another tab
  • Return to editor and refresh

• Verify:

  • Link shows "(Invalid)" suffix
  • Has red wavy underline
  • No tooltip on hover

• Test Draft Link State:

  • Add a Navigation Link block
  • Create and link to a draft post

• Verify:

  • Link shows "(Draft)" suffix
  • Has yellow/warning wavy underline
  • No tooltip on hover

Screencast

Before

Screen.Recording.2025-01-15.at.11.52.35.mov

After

Screen.Recording.2025-01-15.at.11.48.17.mov

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: himanshupathak95 <abcd95@git.wordpress.org>
Co-authored-by: afercia <afercia@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[afercia]

@himanshupathak95 thanks for wokring on this!
I think it's going in the right direction and adding the Invalid / Draft state to the visible text is valuable.

However, I wouldn't use an aria-label at all. It introduces a mismatch between the visible text and the accessible name of the link. I'd think the visible text is sufficient to communicate the state so instead of doing this (markp examples):

<span ... aria-label="This item is missing a link">Add link</span>

<span aria-label="Navigation link text - Invalid">Lalala (Invalid)</span>

<span aria-label="Navigation link text - Draft">Lalala (Draft)</span>

I'd suggest to do this:

<span ... >Missing link</span>

<span>Lalala (Invalid)</span>

<span>Lalala (Draft)</span>

[himanshupathak95]

Thanks @afercia, for the suggestion. I have removed the labels as suggested.

Please let me know if there is a way to improve further 🚀

[afercia]

Everything looks good to me.
The only thing I would consider to change is luminous-vivid-amber because it doesn't reach a sufficient color contrast ratio with the white background. What about using vivid-red for both invalid and draft?

[afercia]

To recap what this PR does: it removes the incorrect usage of tooltips currently used to communicate the link state in case the link is missing, invalid or still pointing to a deleted or trashed / trashed page.

Screenshots of the removed tooltips:

These states are already sufficiently communicated by the visible label.
Additionally, the 'wave underline' already used for 'add link' is now red for invalid links.

Screenshots from this PR (amber suggested to be changed to red):

[himanshupathak95]

Hey @afercia, I have changed the wavy underline color from amber to red as per the suggestion.

Please let me know if there is still room for improvement.

[himanshupathak95]

@afercia In my opinion, if the problem with the amber color is the low contrast with a white background, maybe we can use a darker intermediate color? ( like mustard )

I feel the Invalid link and the Draft link behave differently and a visual color difference might aid this thought. What do you think about this?

[afercia]

I feel the Invalid link and the Draft link behave differently and a visual color difference might aid this thought.

@himanshupathak95 Yes I would agree that, conceptually, they are two different cases. However, that is based on the idea that the 'wavy underline' should communicate the type of warning. Should it? Wouldn't be simpler to always use the red 'wavy underline' as a visual hint for something that needs attention / fix? More or less, like the spellchecker red wavy underline, which doesn't tell what is wrong and it's just a signal of potential error.

[himanshupathak95]

Thanks, @afercia for the wonderful explanation. It makes sense now that I see it that way. I understand that the wavy underline serves as a universal signal for "needs attention”. The underline draws attention while the text itself can communicate the specific issue.

The current implementation aligns with this idea -

[afercia]

@himanshupathak95 thanks for the screenshot, that illustrates very well the good job you did in this PR. I'm going to have a final look and merge it, thanks!

[afercia]

I noticed the padding of the underline was inconsistent in the default placeholder 'Add link' and the draft/invalid labels:

Trunk	This PR

In the last commits I restored the original markup because the <span> element needs to be used for both cases wrapped in a <div> element and adjusted the CSS accordingly.

After:

@himanshupathak95 can you please check I didn't break anything 🙂 when you have a chance, thanks!

[afercia]

LGTM

[himanshupathak95]

@afercia Is the extra new line here intentional or can it be removed?

[himanshupathak95]

Thanks a lot, @afercia, for noticing the inconsistent padding and fixing it 🙇🏻

The changes test well for me. I think the PR is ready to ship once we remove the extra new line (if it was not intentional) 🚀

[afercia]

the extra new line

Oh 🤦🏻

[t-hamano]

Just to be sure, does the --wp--preset--color--vivid-red variable get output for any theme? Also, will this approach work for themes that don't have a white background?

[t-hamano]

I think the --wp--preset--color--vivid-red CSS variable is generated from the default theme.json that comes with core. Relying on the theme.json value is unstable, so can't we use the $alert-red variable, for example?

[afercia]

will this approach work for themes that don't have a white background?

Good point but it's an existing issue and should be addressed separately. For example, the blue wavy underline for the default 'Add link' placeholder is barely visible on a dark background. Screenshot with Twenty Twenty-Four > Maelstrom variation:

Re --wp--preset--color--vivid-red I'm not very familiar with what the best option would be. I trust your judgment and if you think the $alert-red variable is a better option please do feel free to push a follow-up 🙏🏻

I will create a new issue for the wavy underline on dark background.

[t-hamano]

Good point but it's an existing issue and should be addressed separately.

That's certainly true.

if you think the $alert-red variable is a better option

This CSS variable appears to be used in various places in the Gutenberg project to represent an "error" or "invalid" state (Example).

Therefore, I would like to submit a follow-up PR that uses this variable.

[t-hamano]

@himanshupathak95 Have you tried the following format?

&.is-invalid,
&.is-draft {
	span {
		--wp-underline-color: #{$alert-red};
	}
}

[himanshupathak95]

--wp-underline-color: #{$alert-red};

No, I didn't try this back then, but now I tested it and it's working.

[t-hamano]

@himanshupathak95 Would you like to submit a follow-up PR? You worked on this issue, so you probably know more about it than anyone else 🙂

[himanshupathak95]

@himanshupathak95 Would you like to submit a follow-up PR? You worked on this issue, so you probably know more about it than anyone else 🙂

Thanks for asking, @t-hamano, Yes, I will raise a PR shortly

[t-hamano]

I am thinking of fixing all the instances of color variables generated from the default theme.json that comes with the core (wherever possible without breaking anything 🤞🏻).

One instance in the same file is this line here

Are you referring to the --wp-admin-theme-color CSS variable? This CSS variable is not generated from the theme.json.

[himanshupathak95]

Are you referring to the --wp-admin-theme-color CSS variable? This CSS variable is not generated from the theme.json.

Yes, I just found that out. I got confused, apologies.