From 52ac756518a708c39ad0ed5dc553ac56c4f59f4b Mon Sep 17 00:00:00 2001
From: adamsilverstein <adamsilverstein@earthboundhosting.com>
Date: Tue, 21 Jul 2026 12:30:21 -0700
Subject: [PATCH] Notes: keep the highlight tint at one low alpha, emphasize
 with an underline

The per-author tint sits behind the marker's text, so it is subtracted from
whatever text/background contrast the theme provides, and the canvas background
comes from theme.json, so the composited result cannot be measured from CSS.
Doubling the alpha on hover, focus, and selection doubled that loss: on a
mid-tone canvas an orange-authored marker dropped from a passing 4.54:1 to
2.67:1.

Hold the tint at the rest alpha in every state and carry emphasis with an
opaque underline in the author's color instead, which reads more strongly than
a heavier wash without touching what sits behind the text.
---
 packages/editor/CHANGELOG.md                  |  1 +
 .../collab-sidebar/note-highlight-styles.js   | 46 ++++++++++++++-----
 .../test/note-highlight-styles.js             | 34 ++++++++++++--
 .../specs/editor/various/block-notes.spec.js  | 38 +++++++++++----
 4 files changed, 93 insertions(+), 26 deletions(-)

diff --git a/packages/editor/CHANGELOG.md b/packages/editor/CHANGELOG.md
index aaeed12c50c67c..766c6ab2e2f89e 100644
--- a/packages/editor/CHANGELOG.md
+++ b/packages/editor/CHANGELOG.md
@@ -8,6 +8,7 @@
 
 ### Bug Fixes
 
+-   Notes: Stop deepening an inline note marker's tint on hover, focus, and selection. The tint sits behind the text and is subtracted from whatever contrast the theme provides, so emphasis is now an author-colored underline instead ([#80543](https://github.com/WordPress/gutenberg/issues/80543)).
 -   `mediaUpload`: Add an `isTransportOnly` parameter, set by the `@wordpress/upload-media` queue, which owns progress tracking and save locking for its own items and uses this function only as its server transport. Fixes the progress snackbar showing "1 of 2" for a single HEIC upload in Safari ([#80369](https://github.com/WordPress/gutenberg/issues/80369)).
 
 ## 14.51.0 (2026-07-14)
diff --git a/packages/editor/src/components/collab-sidebar/note-highlight-styles.js b/packages/editor/src/components/collab-sidebar/note-highlight-styles.js
index b0c53e178c14ae..86ad5a693c5e34 100644
--- a/packages/editor/src/components/collab-sidebar/note-highlight-styles.js
+++ b/packages/editor/src/components/collab-sidebar/note-highlight-styles.js
@@ -9,11 +9,31 @@ import { useStyleOverride } from '@wordpress/block-editor';
  */
 import { getAvatarBorderColor } from './utils';
 
-// Hex alpha suffixes for the rest / active states. Kept low so the marker
-// reads as a soft tint at rest and gets noticeably stronger when focused or
-// hovered. (0x40 ≈ 25%, 0x80 ≈ 50%.)
-const REST_ALPHA = '40';
-const ACTIVE_ALPHA = '80';
+/*
+ * Hex alpha suffix for the tint painted behind the marker's text. One low value
+ * for every state, on purpose: the tint sits behind the glyphs, so raising it
+ * eats into whatever text/background contrast the theme already provides, and
+ * the canvas background comes from `theme.json`, so the composited result
+ * cannot be measured from CSS. (0x40 ≈ 25%.)
+ */
+const TINT_ALPHA = '40';
+
+/**
+ * Emphasis for hover / focus / the selected note. Carried by an opaque
+ * underline in the author's color rather than a stronger tint, so the marker
+ * reads more strongly without changing what sits behind the text.
+ *
+ * @param {string} color The author's `#RRGGBB` color.
+ * @return {string} Declarations for the emphasized state.
+ */
+function emphasis( color ) {
+	return (
+		'text-decoration-line:underline;' +
+		`text-decoration-color:${ color };` +
+		'text-decoration-thickness:0.125em;' +
+		'text-underline-offset:0.15em;'
+	);
+}
 
 // Reset the browser's default `<mark>` styling so the per-author rules below
 // are what readers actually see (without it, `mark` ships with a bright yellow
@@ -25,6 +45,10 @@ const BASE_RESET = 'mark.wp-note{background-color:transparent;color:inherit;}';
  * Build the CSS rule set that tints each inline-note marker with its author's
  * avatar color. Pure helper extracted so it can be unit-tested without React.
  *
+ * The tint stays at a single low alpha in every state and emphasis is expressed
+ * as an underline, so marking a note can only cost the theme's text contrast
+ * the one fixed amount, never more when the note is hovered or selected.
+ *
  * @param {Array}       threads    Unresolved note threads (each with `id` and `author`).
  * @param {string|null} selectedId ID of the currently selected note, if any.
  * @return {string} A serialized CSS string targeting the in-content note markers.
@@ -43,14 +67,12 @@ export function buildHighlightCss( threads, selectedId = null ) {
 		// from stored data.
 		const escapedId = String( thread.id ).replace( /["\\]/g, '\\$&' );
 		const sel = `mark.wp-note[data-id="${ escapedId }"]`;
-		rules.push( `${ sel }{background-color:${ color }${ REST_ALPHA };}` );
+		rules.push( `${ sel }{background-color:${ color }${ TINT_ALPHA };}` );
 		rules.push(
-			`${ sel }:hover,${ sel }:focus-within{background-color:${ color }${ ACTIVE_ALPHA };}`
+			`${ sel }:hover,${ sel }:focus-within{${ emphasis( color ) }}`
 		);
 		if ( selectedId && String( selectedId ) === String( thread.id ) ) {
-			rules.push(
-				`${ sel }{background-color:${ color }${ ACTIVE_ALPHA };}`
-			);
+			rules.push( `${ sel }{${ emphasis( color ) }}` );
 		}
 	}
 	return rules.join( '' );
@@ -65,8 +87,8 @@ export function buildHighlightCss( threads, selectedId = null ) {
  * Uses `useStyleOverride` so the styles reach the iframed canvas; a plain
  * `<style>` element rendered in the sidebar would only affect the parent doc.
  *
- * Opacity boosts on `:hover`, `:focus-within`, and when the matching thread is
- * the editor's selected note.
+ * An author-colored underline is added on `:hover`, `:focus-within`, and when
+ * the matching thread is the editor's selected note.
  *
  * @param {Object}      props
  * @param {Array}       props.threads      Unresolved note threads.
diff --git a/packages/editor/src/components/collab-sidebar/test/note-highlight-styles.js b/packages/editor/src/components/collab-sidebar/test/note-highlight-styles.js
index b3dc09b56293e9..1be54e8c7c1f0a 100644
--- a/packages/editor/src/components/collab-sidebar/test/note-highlight-styles.js
+++ b/packages/editor/src/components/collab-sidebar/test/note-highlight-styles.js
@@ -28,15 +28,15 @@ describe( 'buildHighlightCss', () => {
 		);
 	} );
 
-	it( 'emits a higher-alpha (0x80) rule on hover and focus-within for each thread', () => {
+	it( 'emphasizes hover and focus-within with an author-colored underline', () => {
 		const css = buildHighlightCss( [ { id: 7, author: 1 } ] );
 		const color = getAvatarBorderColor( 1 );
 		expect( css ).toContain(
-			`mark.wp-note[data-id="7"]:hover,mark.wp-note[data-id="7"]:focus-within{background-color:${ color }80;}`
+			`mark.wp-note[data-id="7"]:hover,mark.wp-note[data-id="7"]:focus-within{text-decoration-line:underline;text-decoration-color:${ color };`
 		);
 	} );
 
-	it( 'boosts opacity for the selected thread by appending a second rule', () => {
+	it( 'emphasizes the selected thread by appending a second rule', () => {
 		const css = buildHighlightCss(
 			[ { id: 7, author: 1 } ],
 			'7' // selected
@@ -46,16 +46,40 @@ describe( 'buildHighlightCss', () => {
 		expect( css ).toContain(
 			`mark.wp-note[data-id="7"]{background-color:${ color }40;}`
 		);
-		// Active rule appended later, so the cascade picks it.
+		// Emphasis rule appended later, so the cascade picks it.
 		const restIndex = css.indexOf(
 			`mark.wp-note[data-id="7"]{background-color:${ color }40;}`
 		);
 		const activeIndex = css.lastIndexOf(
-			`mark.wp-note[data-id="7"]{background-color:${ color }80;}`
+			`mark.wp-note[data-id="7"]{text-decoration-line:underline;`
 		);
 		expect( activeIndex ).toBeGreaterThan( restIndex );
 	} );
 
+	/*
+	 * The tint sits behind the glyphs, so every increment of it is subtracted
+	 * from whatever text/background contrast the theme provides, and CSS cannot
+	 * measure the composited result because the canvas background comes from
+	 * `theme.json`. Emphasis therefore has to come from somewhere other than a
+	 * stronger wash. Guards against reintroducing a per-state alpha.
+	 */
+	it( 'never paints a stronger tint behind the text than the rest alpha', () => {
+		const css = buildHighlightCss(
+			[
+				{ id: 7, author: 1 },
+				{ id: 12, author: 3 },
+			],
+			'7'
+		);
+		const alphas = [
+			...css.matchAll( /background-color:#[0-9a-f]{6}([0-9a-f]{2})?/gi ),
+		]
+			.map( ( [ , alpha ] ) => alpha )
+			.filter( Boolean );
+		expect( alphas.length ).toBeGreaterThan( 0 );
+		expect( alphas.every( ( alpha ) => alpha === '40' ) ).toBe( true );
+	} );
+
 	it( 'matches numeric and string selectedId variants', () => {
 		const cssNum = buildHighlightCss( [ { id: 7, author: 1 } ], 7 );
 		const cssStr = buildHighlightCss( [ { id: 7, author: 1 } ], '7' );
diff --git a/test/e2e/specs/editor/various/block-notes.spec.js b/test/e2e/specs/editor/various/block-notes.spec.js
index 0355efc69b6879..c2ca46cd49193d 100644
--- a/test/e2e/specs/editor/various/block-notes.spec.js
+++ b/test/e2e/specs/editor/various/block-notes.spec.js
@@ -1327,9 +1327,9 @@ test.describe( 'Block Notes', () => {
 			const mark = editor.canvas.locator( 'mark.wp-note' ).first();
 			await expect( mark ).toBeVisible();
 
-			// Creating a note auto-selects it, which renders the marker at the
-			// active opacity. Move focus to the title to deselect so the marker
-			// settles back to its rest tint.
+			// Creating a note auto-selects it, which emphasizes the marker with
+			// an underline. Move focus to the title to deselect so only the
+			// tint is left to assert on.
 			await editor.canvas
 				.getByRole( 'textbox', { name: 'Add title' } )
 				.click();
@@ -1594,10 +1594,16 @@ test.describe( 'Block Notes', () => {
 			await expect( paragraph ).toHaveText( 'Hello brave new world.' );
 		} );
 
-		test( 'boosts the marker opacity when its note is selected', async ( {
+		test( 'underlines the marker when its note is selected, without deepening the tint', async ( {
 			editor,
 			page,
+			requestUtils,
 		} ) => {
+			const me = await requestUtils.rest( { path: '/wp/v2/users/me' } );
+			const expectedColor =
+				AVATAR_BORDER_COLORS[ me.id % AVATAR_BORDER_COLORS.length ];
+			const { r, g, b } = hexToRgb( expectedColor );
+
 			await editor.insertBlock( {
 				name: 'core/paragraph',
 				attributes: { content: 'Select my note.' },
@@ -1633,22 +1639,36 @@ test.describe( 'Block Notes', () => {
 				);
 				return match && match[ 4 ] ? Number( match[ 4 ] ) : 1;
 			};
+			const underlineOf = async () =>
+				mark.evaluate( ( el ) => {
+					const style = window.getComputedStyle( el );
+					return `${ style.textDecorationLine } ${ style.textDecorationColor }`;
+				} );
 
 			// Deselect the freshly added note (focus the title) so the marker
-			// drops to its rest tint (≈0x40/255).
+			// settles into its unemphasized state.
 			await editor.canvas
 				.getByRole( 'textbox', { name: 'Add title' } )
 				.click();
-			await expect.poll( alphaOf ).toBeLessThan( 0.35 );
+			await expect.poll( underlineOf ).toContain( 'none' );
 
-			// Selecting the note from the sidebar promotes its marker to the
-			// stronger active alpha (≈0x80/255) via the selected-note rule.
+			// Selecting the note from the sidebar emphasizes its marker with an
+			// underline in the author's color.
 			await page
 				.getByRole( 'region', { name: 'Editor settings' } )
 				.getByRole( 'treeitem', { name: 'Note: Pick me' } )
 				.click();
 
-			await expect.poll( alphaOf ).toBeGreaterThan( 0.4 );
+			await expect
+				.poll( underlineOf )
+				.toBe( `underline rgb(${ r }, ${ g }, ${ b })` );
+
+			/*
+			 * The tint behind the text must not deepen with the emphasis: it is
+			 * subtracted from whatever contrast the theme already provides, and
+			 * CSS cannot measure the composited result. See #80543.
+			 */
+			expect( await alphaOf() ).toBeLessThan( 0.35 );
 		} );
 	} );