[adamsilverstein]

What?

Combines three in-flight notes-highlighting PRs into one, per feedback on #80493. They all change how a note marks its place in the canvas, and the result only makes sense reviewed together:

• Notes: keep the block outline, remove the spotlight dimming on note selection #80493 - keep the block outline, drop the spotlight dimming on note selection
• Notes: highlight the whole text block for block-level notes #80498 - highlight the whole text block for block-level notes
• Notes: stop the highlight tint from deepening, emphasize markers with an underline #80544 - hold the tint at one low alpha, emphasize with an underline (fixes Notes: highlight tints reduce text contrast, and the strong state doubles the loss #80543)

Those three stay open for now and can be closed in favor of this one.

Fixes #72860.
Fixes #80543.

Why?

Each PR was solving a piece of the same problem, and the pieces conflicted:

• Notes: highlight the whole text block for block-level notes #80498 tinted a whole block at 0x40, deepening to 0x80 when selected.
• Notes: stop the highlight tint from deepening, emphasize markers with an underline #80544 removed exactly that deepening for inline markers, because the tint sits behind the text: every increment is subtracted from whatever contrast the theme provides, and the composited result can't be measured from CSS since the canvas background comes from theme.json.
• Notes: keep the block outline, remove the spotlight dimming on note selection #80493 removed the spotlight, which is what the "selected" state used to lean on.

Landing them separately would have shipped an intermediate state nobody wants to see, and left the last one to unpick the first two.

How?

One consistent model, with a marking that is visible at rest in every case:

	Rest	Hover / focus / selected
Inline marker	author tint @ 0x40 + underline on its words	underline thickens to 3px
Block-level note	author tint @ 0x40 + rule along the block's bottom edge	+ the block's own outline
Whole canvas	untouched	untouched (no dimming)

The resting indicator is the point, and it is what lets the spotlight go: with nothing shown at rest, removing the dimming would leave no connection between a note in the sidebar and its place in the canvas, which is @jasmussen's central objection.

The tint alpha is a single constant with no per-state variant anywhere, guarded by a unit test in both builders. Emphasis is only ever a silhouette change - a thicker rule - so marking a note costs the theme's text contrast one fixed amount and never more, which is the #80543 constraint.

Two details worth reviewing:

• The block-level rule sits under the block, not under each line. A wrapped paragraph striped on every line reads as formatting, where a single bottom edge reads as a boundary. For single-line blocks (list items, headings) the two are identical, which is the case the mockups show. It is an inset box-shadow rather than a border so adding it cannot reflow the canvas.
• Selection emphasis for block-level notes is the block outline, since thickening a rule that spans a whole paragraph is much louder than doing the same to a few words.

Per @jasmussen's feedback on #80544, every rule is color-mix(in srgb, <author color> 30%, currentColor) at 1.5px. The canvas can be light or dark while the palette is fixed, so anchoring to the text color is what keeps the stroke above the 3:1 non-text contrast minimum in both, with as much author hue as fits underneath it; the fixed pixel thickness keeps it distinct from a hyperlink at body size without becoming a bar under a heading.

Incidentally this also resolves the dimming @noruzzamans noticed while testing #80544 - that was the spotlight, which #80493 removes.

Testing Instructions

Enable notes, then in the post editor:

1. Block-level note. Select a paragraph without selecting any text, add a note. Click away so nothing is selected: the paragraph stays tinted with a rule along its bottom edge. Select the note in the sidebar and the block picks up its outline, with the tint no stronger than before.
2. Inline note. Select a few words, add a note. Click away: those words stay tinted and underlined. Hover the marker, or select the note from the sidebar, and the underline thickens - the tint behind the words does not deepen.
3. No spotlight. With a note selected, the rest of the canvas stays at full contrast - nothing dims.
4. Try both in a dark theme, and with several authors' notes on one page.

Automated

• npm run test:unit packages/editor/src/components/collab-sidebar - 19 tests over the two CSS builders, including guards that the marking is present on the resting rule, that neither builder can reintroduce a per-state alpha, and that the rule color never resolves to the raw palette value.
• npm run test:e2e -- test/e2e/specs/editor/various/block-notes.spec.js - 49 passing locally, covering the resting underline and its thickening on selection, the block's resting bottom rule, the computed mix against the theme's text color, and the tint holding steady across states.

Screenshots or screencast

Coming in a follow-up comment: both markings at rest with nothing selected - block-level note on the first paragraph, inline note on the second.

AI Use

Both the code and this description came out of a long back and forth with 🤖 Claude Code. I will review and test.

[github-actions]

Size Change: +575 B (+0.01%)

Total Size: 7.92 MB

📦 View Changed

Filename	Size	Change
build/scripts/editor/index.min.js	581 kB	+575 B (+0.1%)

_{compressed-size-action}

[noruzzamans]

@adamsilverstein I previously tested the same functionality (block-level tint, inline underline, no dimming) successfully on the individual PRs (#80493, #80498, #80544). For this combined PR, I'm unable to locate the option to enable Notes — checked the Experiments page and Preferences panel on both a local git pull of this branch and the Playground link, but couldn't find the toggle. Not sure if I'm missing something on my end — flagging in case it's a genuine access issue.

[adamsilverstein]

For this combined PR, I'm unable to locate the option to enable Notes

Thanks for the continued testing @noruzzamans!

Right we removed the note item from the formats sub-menu, it wasn't actually ever supposed to be there (it isn't there in 7.0 either)!

You will find it in the "kebob" menu (...):

Testing this I'm not sure its quite right in terms of addressing the most recent feedback from @jasmussen - I'm going to review again.

[github-actions]

Flaky tests detected in cdea363.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/33116189102
📝 Reported tests:

two users concurrently move list items (RTC WebSocket) in /test/e2e/specs/editor/collaboration/collaboration-stress.spec.ts, passed after 1 failed attempt.

TimeoutError: locator.click: Timeout 10000ms exceeded.
Call log:
  - waiting for locator('role=toolbar[name="Block tools"i]').locator('role=button[name="Move up"i]')
    - locator resolved to <button id=":rq:" type="button" tabindex="-1" aria-label="Move up" data-toolbar-item="true" aria-describedby="block-editor-block-mover-button__description-0" class="components-button block-editor-block-mover-button is-up-button is-next-40px-default-size has-icon">…</button>
  - attempting click action
    - waiting for element to be visible, enabled and stable
    - element is visible, enabled and stable
    - scrolling into view if needed
    - done scrolling
  - element was detached from the DOM, retrying

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/collaboration-stress.spec.ts:623:7
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/collaboration-stress.spec.ts:602:3

[noruzzamans]

For this combined PR, I'm unable to locate the option to enable Notes

Thanks for the continued testing @noruzzamans!

Right we removed the note item from the formats sub-menu, it wasn't actually ever supposed to be there (it isn't there in 7.0 either)!

You will find it in the "kebob" menu (...):

Testing this I'm not sure its quite right in terms of addressing the most recent feedback from @jasmussen - I'm going to review again.

Apologies for the earlier confusion — I found the option and re-tested this now.

1. Block-level note: Works as expected.
2. Inline note: Works as expected.
3. No spotlight: Confirmed — the rest of the canvas stays at full contrast when a note is selected, no dimming.

One note: previously (on an earlier version I tested), hovering a note showed the underline in the author's color. Just flagging in case that's an intentional change here.

Screen.Recording.2026-07-23.at.10.13.17.AM.mov

[jasmussen]

Taking for a quick spin, I'm seeing this:

That's a 2px pure currentcolor border. This can work if it's the direction that is deemed necessary, but I'd like us to still try the color-mix 30/70 currentColor+highlightColor composite if we can, and I'd love to try a 1.5px border. The latter part may not be possible unless you use box-shadow, which may not be ideal in this case, if that's the case ignore this.

This image has a block level note:

I'm not seeing any indication at rest. I'd been hoping for the same color overlay and 1.5px border, except all around the image.

[joedolson]

Testing in Windows High Contrast Mode, this is going to need to add support for forced-colors; right now, the mark sets a background-color, but leaves the text as inherit, which can result in problems:

[adamsilverstein]

Thanks for the review and feedback everyone, I will work on addressing it!

[adamsilverstein]

Thanks for the reviews everyone, I pushed a round of changes addressing the feedback.

@jasmussen:

I'd like us to still try the color-mix 30/70 currentColor+highlightColor composite if we can

Done - the stroke is now color-mix(in srgb, currentColor 30%, <author color>), so 70% author color. I checked the numbers for all seven palette colors: at a 70% share every one clears the 3:1 non-text minimum against both a white and a near-black canvas. Orange is the floor at exactly 3.0:1 on white, cyan next at 3.3:1, everything else has more headroom - so your eyedropping was right, 70% is about the most color we can seed in while staying safe.

and I'd love to try a 1.5px border

The resting underline is already text-decoration-thickness: 1.5px - browsers round that up to 2 device pixels at 1x zoom, which I believe is the 2px you measured. Selecting or hovering the note thickens it to 3px. If it still reads too heavy at rest I'm happy to try other values.

This image has a block level note ... I'm not seeing any indication at rest. I'd been hoping for the same color overlay and 1.5px border, except all around the image.

Done - non-text blocks (images, containers) now paint the same tint as an overlay above the block, with the 1.5px rule drawn all the way around. The overlay ignores pointer events so the block stays editable through it.

@joedolson:

Testing in Windows High Contrast Mode, this is going to need to add support for forced-colors

Added - under forced-colors: active the marker now opts into the system Mark/MarkText pair so the text color follows the forced background, and block-level highlights (which lose both their tint and their box-shadow rule in that mode) fall back to a dashed outline - dashed so it stays distinct from the solid outline on the selected block. I'd appreciate a re-test in Windows High Contrast whenever you have a chance, I wasn't able to verify on macOS.

@noruzzamans:

previously (on an earlier version I tested), hovering a note showed the underline in the author's color. Just flagging in case that's an intentional change here.

Good catch - the underline color changed while we tuned contrast, and with this latest push it is mostly the author's color again (70% author, 30% text color), at rest and on hover; hover just thickens it. Thanks for the continued testing!

[adamsilverstein]

Capturing some screenshots I see this still needs some tuning, working on it.

[annezazu]

Checking this out and I want to underscore that on hide, the markers should go away. I'm thinking about this from a writer's point of view and how frustrating it would be to hide notes to focus only for random text to be highlighted.

[joedolson]

Fair enough. It's not what I would want, but I'm not going to fight the point!

[t-hamano]

@adamsilverstein Thanks for the update!

I'm not entirely sure what the ideal solution is yet 🤔, but I'm wondering if we can simplify the CSS rules. For example:

• Inline-level notes: Text has an underline and a background color.
• Block-level notes: The entire block gets a background color and an outline, with no underline on the text.

This rule seems very simple and straightforward to me, and it appears to be working well. What does everyone think?

Windows High Contrast Mode.

For consistency, we could also apply system colors to the borders of block-level notes.

diff --git a/packages/editor/src/components/collab-sidebar/note-highlight-styles.js b/packages/editor/src/components/collab-sidebar/note-highlight-styles.js
--- a/packages/editor/src/components/collab-sidebar/note-highlight-styles.js
+++ b/packages/editor/src/components/collab-sidebar/note-highlight-styles.js
@@ -259,7 +259,7 @@ export function buildBlockHighlightCss( blockHighlights ) {
 		rules.push(
 			`@media (forced-colors: active){${ blockSelectors.join(
 				','
-			) }{outline:${ RULE_THICKNESS } dashed;outline-offset:2px;}${ overlaySelectors.join(
+			) }{outline:${ RULE_THICKNESS } dashed Mark;outline-offset:2px;}${ overlaySelectors.join(
 				','
 			) }{border:none;}}`
 		);

[t-hamano]

This runs on every store change, including every keystroke, and findNoteInBlock scans the content of every noted block each time. Could we memoize it per attributes object (e.g. with a WeakMap)?

[t-hamano]

I believe this PR is a great improvement, ensuring that all notes are visualized consistently and that block-level and inline-level elements are visually distinguishable. I think it is ready to ship, but we might want to try this minor optimization.

Before	After

For consistency, we could also apply system colors to the borders of block-level notes.

diff --git a/packages/editor/src/components/collab-sidebar/note-highlight-styles.js b/packages/editor/src/components/collab-sidebar/note-highlight-styles.js
--- a/packages/editor/src/components/collab-sidebar/note-highlight-styles.js
+++ b/packages/editor/src/components/collab-sidebar/note-highlight-styles.js
@@ -259,7 +259,7 @@ export function buildBlockHighlightCss( blockHighlights ) {
 		rules.push(
 			`@media (forced-colors: active){${ blockSelectors.join(
 				','
-			) }{outline:${ RULE_THICKNESS } dashed;outline-offset:2px;}${ overlaySelectors.join(
+			) }{outline:${ RULE_THICKNESS } dashed Mark;outline-offset:2px;}${ overlaySelectors.join(
 				','
 			) }{border:none;}}`
 		);

By the way, it turns out that this proposal isn't ideal. Mark is intended as a background color for MarkText, so its contrast against Canvas isn't guaranteed. While this is fine in dark themes, the dashed yellow line might become almost invisible in high-contrast themes with a white background.

[Mamaduka]

I also plan to do a review pass on this. Will fix merge conflicts as well.

Thanks for moving this forward, folks!

[adamsilverstein]

Thanks for the additional feedback and reviews here to help get this polished @t-hamano!

[Mamaduka]

This looks good in my testing; great work! @jameskoster, can you also have a look before we merge?

Pushed a review pass with two cleanups, no behavior changes:

• note-highlight-styles.js: merged getBlockLevelHighlights into buildBlockHighlightCss, since all threads are unresolved and the primary pick reduced to "first wins". The forced-colors marker styles are now one rule emitted last, and each block gets its own forced-colors rule. Also dropped the clientId escaping and use one rule per marker. Only the block-level CSS is derived in useSelect now.
• E2E: the highlight tests now use toHaveCSS (with pseudo: 'after') instead of hand-rolled computed-style parsing. The table, columns, and paragraph block-level tests checked the same rule the unit tests already cover, so I kept one on an image block, which also checks the outline on note and block selection. The two inline marker tests are now one.

Screenshot

[jameskoster]

I'm afraid I am not close enough to the Notes feature to give any concrete feedback. I'd need to first immerse myself which would take some time and I don't want to hold up the effort. If the work is based on feedback from Joen and @t-hamano approves, that's good enough for me!

[Mamaduka]

I've updated the branch and resolved merge conflicts.

@jasmussen, this could use a final design pass if you have time. My screenshot above shows the post when multiple users add notes. Depending on the number of users and notes, content can become very colorful.

[jasmussen]

Yes, this is on my todo for today, but probably after lunch! Catching up, but I'll have something for you in a little bit. Thanks for the ping.

[jasmussen]

Thanks for your patience. This is on a good track, and I think overall safe to merge and iterate. And there are a couple of things I think we can tweak, but nothing that should block this. Here's what I see overall, on block level and inline level notes:

Your previous screenshot was a little hard to review because there was so much going on. That's still valid to review, but in most cases notes will likely be a few inline notes, a couple of block level notes, and not quite the full mix your screenshots showed.

---

Before I dive into details, some notes for posterity: designs started with just the background colour, like so:

Reviews suggested these need decoration that has higher contrast, so we added the border for block level, and underline for inline level notes:

Blue vs. orange in the above depends on your assigned user colour, i.e. if you're assigned green, they're green. But notably the border and underline have a colour-mix based colour that combines your user colour with currentColor (i.e. the text colour) to ensure both contrast, and a connection to the user colour:

This is important for dark background contexts, e.g. black background and white text:

---

So that's the history of the design target, which I'll compare this branch against. And things get pretty close, certainly close enough to ship.

Let's start with the inline notes:

Looks pretty good. The colour-mix combo of currentColor and user-colour looks well balanced. That's in the resting state. When I select a note, it needs to be highlighted:

This part I think we can improve:

• It's unclear why the background becomes grey. I'd either not change the background at all (since the underline change acts as contrast), or just make it slightly more opaque.
• The underline change is substantial, and gets very noisy. I understand we need a shape change between active and resting state, so there's a clear connection between attached note and marking. Investigating, it looks like the thickness changes from 1.5px to 3px. It gets very loud.

An alternative is this. 1.5px with 20% marking opacity at rest, 2px with 40% marking opacity at select:

If that half pixel is deemed insufficient contrast between resting and selected state, you could go 1px at rest, 2px at select:

The same is worth considering for block level notes:

Currently there's no disambiguation between a block-level-noted block at rest vs. select, both are the same. You could ambiguate them both in the same way: 20% opacity and thin stroke width at rest, 40% opacity and thicker stroke width on select. Again in two options, 1.5 to 2px:

1px to 2px:

Maybe 40% opacity is too much in both cases, you can tune that, can try 30, with the borders it's mostly decorative so "feeling" territory.

This will likely also benefit the case where you have both block level and inline level notes, living together:

---

Those are some followups to look at, but other than that, looks good. What do you think?

[Mamaduka]

Thanks for the review, @jasmussen!

We can ship those minor paper-cut fixes during the beta/RC period; I'm sure there will be more.

Your previous screenshot was a little hard to review because there was so much going on. That's still valid to review, but in most cases notes will likely be a few inline notes, a couple of block level notes, and not quite the full mix your screenshots showed.

That's the actual state the user might end up in. I agree it might be rare, but we should also keep those "chaotic" states in mind. People often break our designs in ways we rarely expect 😄

[jasmussen]

That's the actual state the user might end up in. I agree it might be rare, but we should also keep those "chaotic" states in mind. People often break our designs in ways we rarely expect 😄

We absolutely do, and there's lots we can do here if it turns problematic quickly, including tweaking the colours and opacities.

But I think the main thing we can do, which was also part of the initial proposal—perhaps a thing we can try in the beta period—is to give special treatment to all text blocks. Instead of treating them as "generic blocks" with a border all around, mark everything inside instead, like normal text editors do:

It's not completely clear that's better, one of the challenges is that it's at present easier to make a block level note than it is to make an inline level note, even on paragraphs. So simply the act of adding the note where we've already been around the block, I'm sure more will reveal itself there too.

[Mamaduka]

Sounds good. Let's work on tweaks during beta. I'm going to merge this now.