Skip to content

Contrast checker: Check the visible colour of text clipped to its background - #86148

Merged
aaronrobertshaw merged 8 commits into
trunkfrom
fix/contrast-checker-text-gradient
Nov 3, 2026
Merged

aaronrobertshaw merged 8 commits into
trunkfrom
fix/contrast-checker-text-gradient

Conversation

@aaronrobertshaw

@aaronrobertshaw aaronrobertshaw commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Related:

What?

Makes the contrast checker compare the colour readers see when a block's background is clipped to its text.

Why?

With the background clipped to the text, the glyphs show that background, not the text colour. The checker still compared the two. So it warned on readable text, passed unreadable links, and never checked text gradients.

How?

  • Text colour: read the computed -webkit-text-fill-color. Transparent means the clipped background shows.
  • Backdrop: walk up past backgrounds clipped to text.
  • Gradients: warn on the worst opaque stop.
  • Images: skipped.
  • Links: a link colour keeps an opaque fill, so it is checked against the backdrop.
  • Copy: a text gradient warns on the Gradient control: "Part of this gradient has poor contrast against the background." Its popover now shows the notice.

As on trunk, a Global Styles text gradient alone gets no check. The worst stop can over-warn when it sits off the text.

Testing Instructions

  1. Add a black Group with a Heading: white text, yellow background, Clip on. Trunk warns, this PR doesn't.
  2. Add a Heading with a yellow to pink text gradient. This PR warns on Gradient, trunk doesn't.
  3. In the Group, add a linked Paragraph: black text, yellow clipped background, #333333 link colour. This PR warns on Link, trunk doesn't.

Testing Instructions for Keyboard

Select the step 2 Heading, Tab to Typography > Gradient and press Enter. The notice shows below the picker.

Screenshots or screencast

composite

Use of AI Tools

Written with Claude Code. I reviewed the code, tests and description.

@aaronrobertshaw aaronrobertshaw added [Type] Bug An existing feature does not function as intended [Package] Block editor /packages/block-editor [Feature] Design Tools Tools that impact the appearance of blocks both to expand the number of tools and improve the experi labels Nov 2, 2026
@aaronrobertshaw aaronrobertshaw self-assigned this Nov 2, 2026
@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

🤖 PR meta 🤖

Preview in WordPress Playground

🎉 Props

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: aaronrobertshaw <aaronrobertshaw@git.wordpress.org>
Co-authored-by: ramonjd <ramonopoly@git.wordpress.org>

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


Props Bot commands

You can trigger Props Bot actions by commenting on this PR:

  • @propsbot add <username> to give props to a GitHub user. Requires write access.
  • @propsbot remove <username> to leave a user out of the props. Requires write access.
  • @propsbot refresh to refresh this list. Adding the props-bot label works too.

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

📦 Bundle size

Size Change: +344 B (0%)

Total Size: 8.58 MB

📦 View Changed
Filename Size Change
build/scripts/block-editor/index.min.js 542 kB +344 B (+0.06%)

3903aa6 Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric 8fe91a0 trunk % Change
timeToFirstByte 55.65 ms +4.13% -4.04% 55.5 ms +3.78% -3.06% 0.27%
largestContentfulPaint 90 ms +4.44% -2.22% 92 ms +6.52% -4.35% -2.17%
lcpMinusTtfb 34.2 ms +5.26% -5.26% 34.35 ms +22.27% -1.31% -0.44%
wpBeforeTemplate 28.91 ms +5.47% -2.11% 29.02 ms +3.31% -2.34% -0.38%
wpTemplate 21.83 ms +5.63% -4.58% 21.98 ms +6.73% -4.19% -0.68%
wpTotal 51.87 ms +4.01% -4.38% 51.64 ms +3.83% -3.62% 0.45%
wpMemoryUsage 7.71 MB +0% -0% 7.67 MB +0% -0% 0.44%
wpDbQueries 16 +0% -0% 16 +0% -0% 0%

front-end-classic-theme

Metric 8fe91a0 trunk % Change
timeToFirstByte 41.25 ms +10.18% -1.09% 47.15 ms +8.91% -4.24% -12.51%
largestContentfulPaint 88 ms +4.55% -0% 100 ms +4% -0% -12%
lcpMinusTtfb 47.2 ms +1.48% -0.95% 53.95 ms +3.15% -2.5% -12.51%
wpBeforeTemplate 26.35 ms +1.06% -2.31% 26.96 ms +5.68% -4.04% -2.26%
wpTemplate 12.08 ms +10.84% -1.9% 16.67 ms +6.78% -3.24% -27.53%
wpTotal 38.39 ms +10.13% -0.63% 44.01 ms +9.29% -4.39% -12.77%
wpMemoryUsage 6.28 MB +0% -0% 6.36 MB +0% -0% -1.21%
wpDbQueries 9 +0% -0% 13 +0% -0% -30.77%

media-processing

Metric 8fe91a0 trunk % Change
mediaProcessingJpeg 400.76 ms +1.35% -1.15% 403.09 ms +0.32% -1.18% -0.58%
mediaProcessingAvif 6134.66 ms +0.25% -0.05% 6178.11 ms +0.38% -0.3% -0.7%
mediaProcessingJpegToAvif 4251.69 ms +0.23% -0.14% 4260.97 ms +0.28% -0.09% -0.22%

media-upload

Metric 8fe91a0 trunk % Change
jpegUploadProcessing 1710.81 ms +15.5% -14.39% 1714.73 ms +13.6% -14.23% -0.23%
pngUploadProcessing 182.3 ms +32.64% -3.32% 179.14 ms +56.83% -4.03% 1.76%
largeJpegUploadProcessing 1466.31 ms +0.75% -1.45% 1463.62 ms +32.6% -0.29% 0.18%
multipleImageUploadProcessing 2015.14 ms +1.31% -0.16% 2035.79 ms +3.05% -0.06% -1.01%

post-editor

Metric 8fe91a0 trunk % Change
serverResponse 407.24 ms +3.33% -5.8% 400.29 ms +1.96% -8% 1.74%
firstPaint 372.03 ms +28.98% -4.94% 345.81 ms +8.13% -9.94% 7.58%
domContentLoaded 848.01 ms +7.08% -0.95% 869.33 ms +6.12% -4.19% -2.45%
loaded 848.99 ms +7.08% -0.93% 870.25 ms +6.12% -4.18% -2.44%
firstContentfulPaint 503.85 ms +5.16% -3.79% 512.17 ms +1.94% -8.6% -1.62%
firstBlock 2086.04 ms +6.86% -1.74% 2108.99 ms +1.38% -2.19% -1.09%
type 16.88 ms +4.92% -4.62% 16.99 ms +24.37% -5.94% -0.65%
typeWithoutInspector 18.54 ms +9.87% -2.8% 18.71 ms +9.94% -9.73% -0.91%
typeWithTopToolbar 22.82 ms +6.05% -6.22% 22.84 ms +7.66% -4.9% -0.09%
typeContainer 8.24 ms +14.81% -5.58% 8.86 ms +23.02% -10.27% -7%
focus 118.26 ms +11.81% -5.16% 125.03 ms +11.65% -5.91% -5.41%
firstFocus 221.97 ms +0% -0% 258.35 ms +0% -0% -14.08%
selectAll 356.48 ms +6.14% -2.26% 372.78 ms +5.66% -4.96% -4.37%
undo 32.13 ms +8.99% -4.39% 31.08 ms +11.49% -6.72% 3.38%
listViewOpen 72.55 ms +12.82% -2.84% 73.61 ms +23.61% -7.34% -1.44%
inserterOpen 41.25 ms +22.74% -9.14% 46.34 ms +4.01% -7.53% -10.98%
inserterHover 11.54 ms +11.09% -8.93% 12.58 ms +10.65% -14.47% -8.27%
inserterSearch 9.01 ms +3% -3.66% 10.9 ms +10.92% -7.98% -17.34%
loadPatterns 666.27 ms +8.52% -2.45% 718.51 ms +5.22% -3.98% -7.27%
wpTotal 397.76 ms +3.11% -5.99% 390.76 ms +2.11% -8.16% 1.79%
wpMemoryUsage 14.75 MB +0% -0% 14.72 MB +0% -0% 0.24%
wpDbQueries 55 +0% -0% 55 +0% -0% 0%

site-editor

Metric 8fe91a0 trunk % Change
serverResponse 327.42 ms +5.03% -7.92% 328.51 ms +0.51% -1.46% -0.33%
firstPaint 333.09 ms +24.07% -5.76% 312.3 ms +3.85% -8.09% 6.66%
domContentLoaded 760.48 ms +7.8% -2.21% 733.91 ms +1.1% -2.63% 3.62%
loaded 761.52 ms +7.76% -2.23% 734.78 ms +1.16% -2.64% 3.64%
firstContentfulPaint 439.2 ms +14.96% -2.25% 424.71 ms +1.89% -4.13% 3.41%
firstBlock 2193.24 ms +2.15% -2.76% 2128.24 ms +0.86% -2.71% 3.05%
type 17.92 ms +8.37% -12.61% 19 ms +7.16% -15.68% -5.68%
navigate 105.75 ms +7.1% -1.71% 102.74 ms +5.57% -4.25% 2.93%
loadPatterns 1066.96 ms +5.12% -9.57% 917.8 ms +1.73% -1.76% 16.25%
loadPages 972.47 ms +4.71% -0.38% 965.93 ms +7.18% -3.29% 0.68%
wpTotal 319 ms +5.09% -8.21% 320.07 ms +0.53% -1.57% -0.33%
wpMemoryUsage 12.77 MB +0% -0% 12.73 MB +0% -0% 0.28%
wpDbQueries 45 +0% -0% 45 +0% -0% 0%

3903aa6 Run

🏁 Flaky tests

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.

Page List converts to Navigation Links with entity bindings in /test/e2e/specs/editor/blocks/navigation.spec.js, passed after 1 failed attempt.
Error: expect(locator).toContainText(expected) failed

Locator: getByRole('region', { name: 'Editor settings' }).getByRole('tabpanel', { name: 'Content' }).getByRole('button', { name: /Link to:/ })
Expected substring: "test-page-1"
Received string:    "Link to:Cat/catPagePublished"
Timeout: 5000ms

Call log:
  - Expect "toContainText" getByRole('region', { name: 'Editor settings' }).getByRole('tabpanel', { name: 'Content' }).getByRole('button', { name: /Link to:/ }) with timeout 5000ms
  - waiting for getByRole('region', { name: 'Editor settings' }).getByRole('tabpanel', { name: 'Content' }).getByRole('button', { name: /Link to:/ })
    14 × locator resolved to <button type="button" aria-expanded="false" aria-haspopup="dialog" class="components-button link-preview-button is-next-40px-default-size is-secondary">…</button>
       - unexpected value "Link to:Cat/catPagePublished"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/blocks/navigation.spec.js:1949:31
Undo restores the post selection when another synced entity is loaded (RTC WebSocket) in /test/e2e/specs/editor/collaboration/collaboration-undo-redo.spec.ts, passed after 1 failed attempt.
Error: expect(received).toMatchObject(expected)

- Expected  - 2
+ Received  + 2

  Object {
    "attributeKey": "content",
    "blockIndex": 0,
    "content": "abcdef",
-   "endOffset": 3,
-   "offset": 3,
+   "endOffset": 6,
+   "offset": 6,
  }

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/collaboration-undo-redo.spec.ts:363:5
should give the image its context menu while selected @WebKit @Firefox in /test/e2e/specs/editor/blocks/image.spec.js, passed after 1 failed attempt.
Test timeout of 100000ms exceeded.
should keep correct selection when dragging outside block (-firefox) in /test/e2e/specs/editor/various/multi-block-selection.spec.js, passed after 1 failed attempt.
Error: expect(received).toMatchObject(expected)

- Expected  - 1
+ Received  + 1

  Array [
    Object {
      "attributes": Object {
-       "content": "1",
+       "content": "23",
      },
      "name": "core/paragraph",
    },
  ]

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/multi-block-selection.spec.js:787:41
should not have a dead zone between blocks (lower) in /test/e2e/specs/editor/various/writing-flow.spec.js, passed after 1 failed attempt.
TypeError: Cannot read properties of null (reading 'y')
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/writing-flow.spec.js:984:39
should undo without broken temporary state in /test/e2e/specs/editor/blocks/image.spec.js, passed after 1 failed attempt.
Error: expect(received).toBe(expected) // Object.is equality

- Expected  - 2
+ Received  + 2

- <!-- wp:image -->
- <figure class="wp-block-image"><img alt=""/></figure>
+ <!-- wp:image {"id":25,"sizeSlug":"full","linkDestination":"none"} -->
+ <figure class="wp-block-image size-full"><img src="http://localhost:8891/wp-content/uploads/2026/11/c2678966-5269-40a8-99cd-38776b7e4074.png" alt="" class="wp-image-25"/></figure>
  <!-- /wp:image -->
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/blocks/image.spec.js:432:49

3903aa6 Run

@aaronrobertshaw
aaronrobertshaw force-pushed the fix/contrast-checker-text-gradient branch from 7efdc3e to ac6a493 Compare November 2, 2026 08:01
…ground

When a block clips its background to the text, the checker compared the
text colour with that clipped background, so it warned or passed on the
wrong pair.

Read the text's computed fill instead. A transparent fill shows the
clipped background: a solid colour as is, a gradient by its lowest
contrast opaque stop, and an image is skipped. Find the backdrop by
walking up past backgrounds clipped to text. The Typography panel now
checks a text gradient and shows its warning on the Gradient control.
The low contrast icon on a gradient control opens a popover that never
showed the warning text, since the notice only rendered for colours.
Render it after the gradient picker too, so the text gradient warning is
readable where it is fixed.
Covers solid and gradient backgrounds clipped to the text, an ancestor's
clip, a fill given back, images, translucent stops and links.
The Gradient control does not depend on the text color setting, so its
check should not either.
@aaronrobertshaw
aaronrobertshaw force-pushed the fix/contrast-checker-text-gradient branch from 18730ed to 9a0abc6 Compare November 2, 2026 11:05
@aaronrobertshaw
aaronrobertshaw marked this pull request as ready for review November 2, 2026 11:09

@ramonjd ramonjd left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Image Image

Works as advertised.

Left a question about returning undefined for no text clipping and alpha === 0

When no ancestor clips its background to the text, report the transparent
fill instead of nothing, so the transparency warning still shows.
@aaronrobertshaw
aaronrobertshaw merged commit 71eac1e into trunk Nov 3, 2026
85 checks passed
@aaronrobertshaw
aaronrobertshaw deleted the fix/contrast-checker-text-gradient branch November 3, 2026 09:38
@github-actions github-actions Bot added this to the Gutenberg 24.4 milestone Nov 3, 2026
@Mamaduka

Mamaduka commented Nov 5, 2026

Copy link
Copy Markdown
Member

FYI, the new typography-panel.browser.test.tsx is very flaky and fails every couple of runs.

@ramonjd

ramonjd commented Nov 6, 2026

Copy link
Copy Markdown
Member

FYI, the new typography-panel.browser.test.tsx is very flaky and fails every couple of runs.

throwing some tokens at it now

@ramonjd

ramonjd commented Nov 6, 2026

Copy link
Copy Markdown
Member

FYI, the new typography-panel.browser.test.tsx is very flaky and fails every couple of runs.

#86403

The test now waits for the popover to finish opening

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Feature] Design Tools Tools that impact the appearance of blocks both to expand the number of tools and improve the experi [Package] Block editor /packages/block-editor [Type] Bug An existing feature does not function as intended

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants