Navigation block: Improve the wavy underline for dark backgrounds

[afercia]

Description

Splitting this out from #68628

When an item in the navigation block misses the link, a grammar-like 'wavy underline' is shown as visual indicator for the items that needs attention. This was introduced in #32512 and then refined in #34954 which made the underline blue.

#68628 make the underline red for the 'invalid' and 'draft' cases.

However, neither the original implementation nor #68628 took into consideration themes with a background color other than white or light color, where the wavy underlines may be barely visible.

Screenshot with Twenty Twenty-Four set to the 'Maelstrom' variation. Observe the blue outline of the 'Add link' default placeholder is barely visible. Similarly, the red underline for Invalid / Draft may be barely visible with other background colors.

I haven't tested it but I guess the underlines are not visible in Windows High Contrast Mode. I don't think it's an accessibility issue though because the underline is an additional visual indicator. The missing / invalid / draft states are already communicated with the palceholder text or visible label.

The current wavy underline styling could benefit from some improvements for dark background colors though.
Cc @WordPress/gutenberg-design

Step-by-step reproduction instructions

• Use Twenty Twenty-Four set to the 'Maelstrom' variation.
• Edit a navigation block and add an item without a link.
• Observe the blue wavy underline is barely visible on top of the blue background.
• To reproduce the Draft and invalid cases:
  • Add a link to an existing, published page and save.
  • In the WP admin, switch the linked page to be a Draft.
  • Refresh the editor and observe the draft state with a red underline.
  • In the WP admin, move the linked page to the trash.
  • Refresh the editor and observe the invalid state with a red underline.

Screenshots, screen recording, code snippet

No response

Environment info

No response

Please confirm that you have searched existing issues in the repo.

• Yes

Please confirm that you have tested with all plugins deactivated except Gutenberg.

• Yes

Please confirm which theme type you used for testing.

• Block
• Classic
• Hybrid (e.g. classic with theme.json)
• Not sure

[Rishit30G]

Hi @afercia,

Thanks for highlighting this! I believe a color like #268ED7 (RGB: 38, 141, 215) would be a good choice, as it remains visible on both light and dark backgrounds. For lighter backgrounds, this color meets accessibility contrast criteria.
However, for darker backgrounds, while it doesn’t fully pass the criteria, it is still reasonably visible.

Ref: https://webaim.org/resources/contrastchecker/

Sharing the screencast for the same:

Screen.Recording.2025-01-30.at.9.26.23.AM.mov

[afercia]

@Rishit30G I'm thinking that either we should strive to find colors that fit with any background color (which is a little challenging) or maybe consider to give up the idea of ​​differentiating the color depending whether it's a warning (red) or info (blue). By using the text currentColor the underline would always be well visible with any background, or as visible as the text.

As mentioned earlier, I don't think this is an accessibility issue because the underline is an additional visual aid. The text is already meaningful and provides the necessary information e.g.: Add link, Select page, (Invalid), (Draft).

Also, I'm not sure why the underline is made with a background image linear-gradient in the first place. To me, the CSS seeems unnecessarily complicated. The CSS property text-decoration can be used instead to achieve the same wavy underline. Something as simple as the following:

text-decoration: $alert-red wavy underline;
text-decoration-skip-ink: none;

If preferred, the thickness of the underline can be controlled to make it non-dependant from the font, e.g. text-decoration-thickness: 1px; or other value.

By omitting the color value text-decoration: wavy underline;, it would use the default currentColor. Animated GIF to illustrate ho the current color would always be visible though we would lose the red/blue meaning:

Some design feedback would be appreciated @WordPress/gutenberg-design

[hanneslsm]

I agree that currentColor is a viable option. I find the colors in the underline can create confusion anyway (why red, why currentcolor?). That one is a draft and one is invalid is not communicated clearly through the color.

I also agree with simpler CSS.
Not sure if we should use text-decoration-skip-ink: none; though.

[afercia]

Not sure if we should use text-decoration-skip-ink: none; though.

Screenshot to illustrate the difference:

Without text-decoration-skip-ink: none; any character descender glyph and also the parenthesis will 'interrupt' the underline, which is the default in modern browsers for the underline. Not sure that would be ideal.

Without	With

[afercia]

Investigating the original PR that used the blue color for the default placeholder text 'Add link' it actually used this:

--wp-underline-color: var(--wp-admin-theme-color);

Quoting from the PR:

It also adds the admin theme spot color to the underline, to share some block editor UI DNA:
If the theme has a dark background, white will be used instead of the spot color.

So to my understanding there was the intent to handle dark backgrounds but I'm not sure that ever worked well because that's actually the primary color in the User profile color schemes preferences, which is a blue #007cba by default. As such I'm not sure it ever worked with dark backgrounds.

[hanneslsm]

Screenshot to illustrate the difference:

Without text-decoration-skip-ink: none; any character descender glyph and also the parenthesis will 'interrupt' the underline, which is the default in modern browsers for the underline. Not sure that would be ideal.

Thanks for the screenshots. I vote for not using text-decoration-skip-ink: none; because readability is more important than the information the wavy underline conveys.

[hanneslsm]

Actually, it looks like in the current implementation is a text-underline-offset.
I think this is in fact the best approach. Setting text-decoration-skip-ink: none; but adding a offset for better readability.

[afercia]

Actually, it looks like in the current implementation is a text-underline-offset.
I think this is in fact the best approach. Setting text-decoration-skip-ink: none; but adding a offset for better readability.

@hanneslsm thanks for your feedback. Not sure the link you provided works, it brings me to a 'can’t be found' page. Can you please check maybe in an incognito tab? Anyways, the current implementation doesn't use text-cedoration at all, it uses a background image linear gradient and a small bottom padding to the element the background is set to.

gutenberg/packages/block-library/src/navigation-link/editor.scss

Lines 83 to 110 in 055f881

	.wp-block-navigation-link__placeholder-text {
	span {
	$blur: 10%;
	$width: 6%;
	$stop1: 30%;
	$stop2: 64%;
	--wp-underline-color: var(--wp-admin-theme-color);
	background-image:
	linear-gradient(45deg, transparent ($stop1 - $blur), var(--wp-underline-color) $stop1, var(--wp-underline-color) ($stop1 + $width), transparent ($stop1 + $width + $blur)),
	linear-gradient(135deg, transparent ($stop2 - $blur), var(--wp-underline-color) $stop2, var(--wp-underline-color) ($stop2 + $width), transparent ($stop2 + $width + $blur));
	background-position: 0 100%;
	background-size: 6px 3px;
	background-repeat: repeat-x;
	// Since applied to a span, it doesn't change the footprint of the item,
	// but it does vertically shift the underline to better align.
	padding-bottom: 0.1em;
	}
	&.is-invalid,
	&.is-draft {
	span {
	--wp-underline-color: #{$alert-red};
	}
	}
	}

I'd agree text-underline-offset would help.

[hanneslsm]

Not sure the link you provided works, it brings me to a 'can’t be found' page. Can you please check maybe in an incognito tab?

I just linked the image from your original issue, the one with Lalala (Draft).
Thanks for linking the code.
I could imagine that linear-gradient was used, so that it doesn't interfere with the styling from the user / theme, e.g. for underlined links.

[afercia]

I could imagine that linear-gradient was used, so that it doesn't interfere with the styling from the user / theme, e.g. for underlined links.

It doesn't seem the case. To my understanding, when the menu item shows the placeholder text or labels, any underline provided by the theme is intentionally reset to none:

gutenberg/packages/block-library/src/navigation-link/editor.scss

Lines 77 to 78 in 4dadd50

	// While in a placeholder state, hide any underlines the theme might add.
	text-decoration: none !important;

Current trunk when setting the underline to the Navigation block > Styles > Typography > Underline:

Quick test using text-decoration wavy: