Skip to content

Global Styles: Show a contrast warning for the site's text color - #86186

Open
im3dabasia wants to merge 6 commits into
trunkfrom
add/global-styles-text-contrast-checker
Open

im3dabasia wants to merge 6 commits into
trunkfrom
add/global-styles-text-contrast-checker

Conversation

@im3dabasia

@im3dabasia im3dabasia commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

What?

Part of #48055

Shows a contrast warning in Styles > Typography > Text, as suggested in #48055 (comment).

How?

  • Checks the site's text color against its background color.
  • Reuses block-editor's getContrastWarning, now a private API.
  • Skips gradients, images and unreadable colors.
  • ContrastChecker now skips colors it can't read, such as oklch(), instead of treating them as black.

Follow-ups

Left out to keep this small:

  • Check text against each gradient stop.
  • Headings, Links and Buttons.
  • Palette notice.

Testing Instructions

  1. Go to Site Editor > Styles > Typography > Text > Color.
  2. Pick a color close to the background: a warning appears.
  3. Pick a high-contrast color: the warning disappears.
  4. Set a background gradient: no warning shows.

Screenshots or screencast

Screen.Recording.2026-11-02.at.4.35.47.PM.mov

Use of AI Tools

Claude Code helped write the code and tests. I reviewed and tested the changes.

@im3dabasia
im3dabasia requested a review from jasmussen November 2, 2026 12:21
@im3dabasia im3dabasia self-assigned this Nov 2, 2026
@im3dabasia
im3dabasia requested a review from ellatrix as a code owner November 2, 2026 12:21
@im3dabasia im3dabasia added [Type] Enhancement A suggestion for improvement. [Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). Global Styles Anything related to the broader Global Styles efforts, including Styles Engine and theme.json labels Nov 2, 2026
@github-actions github-actions Bot added the [Package] Block editor /packages/block-editor label Nov 2, 2026
@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

🤖 PR meta 🤖

Preview in WordPress Playground Preview in Storybook

🎉 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: im3dabasia <im3dabasia1@git.wordpress.org>
Co-authored-by: aaronrobertshaw <aaronrobertshaw@git.wordpress.org>
Co-authored-by: Deepak-Bhojwani <deepakbhojwani@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: +212 B (0%)

Total Size: 8.66 MB

📦 View Changed
Filename Size Change
build/scripts/block-editor/index.min.js 555 kB +17 B (0%)
build/scripts/edit-site/index.min.js 383 kB +19 B (0%)
build/scripts/editor/index.min.js 572 kB +176 B (+0.03%)

7bcf010 Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric 790a09e trunk % Change
timeToFirstByte 55.55 ms +6.48% -4.14% 54.3 ms +5.99% -5.06% 2.3%
largestContentfulPaint 86 ms +6.98% -2.33% 84 ms +4.76% -4.76% 2.38%
lcpMinusTtfb 29.9 ms +6.69% -5.18% 28.95 ms +22.63% -3.8% 3.28%
wpBeforeTemplate 28.63 ms +11.32% -1.99% 27.96 ms +8.8% -3.15% 2.4%
wpTemplate 21.99 ms +3.5% -5.05% 21.72 ms +5.52% -7.14% 1.24%
wpTotal 51.47 ms +6.18% -4.41% 50.18 ms +5.1% -5.12% 2.57%
wpMemoryUsage 7.75 MB +0% -0% 7.71 MB +0% -0% 0.45%
wpDbQueries 16 +0% -0% 16 +0% -0% 0%

front-end-classic-theme

Metric 790a09e trunk % Change
timeToFirstByte 44.95 ms +5.12% -3.23% 44.3 ms +5.76% -1.81% 1.47%
largestContentfulPaint 80 ms +5% -0% 80 ms +5% -5% 0%
lcpMinusTtfb 35.55 ms +4.64% -2.25% 33.95 ms +10.75% -2.36% 4.71%
wpBeforeTemplate 24.46 ms +4.54% -2.29% 24.01 ms +10.54% -1.08% 1.87%
wpTemplate 16.42 ms +3.84% -1.58% 16.06 ms +8.9% -1.87% 2.24%
wpTotal 41.49 ms +5.64% -3.4% 40.99 ms +6.56% -2.61% 1.22%
wpMemoryUsage 6.44 MB +0% -0% 6.40 MB +0% -0% 0.56%
wpDbQueries 13 +0% -0% 13 +0% -0% 0%

media-processing

Metric 790a09e trunk % Change
mediaProcessingJpeg 419.03 ms +0.43% -0.47% 415.71 ms +2.11% -0.39% 0.8%
mediaProcessingAvif 6251.4 ms +0.63% -0.32% 6265.98 ms +0.51% -0.18% -0.23%
mediaProcessingJpegToAvif 4380.79 ms +0.05% -0.48% 4371.56 ms +0.12% -0.27% 0.21%

media-upload

Metric 790a09e trunk % Change
jpegUploadProcessing 1993.82 ms +1.69% -1.22% 1958.4 ms +2.34% -21.91% 1.81%
pngUploadProcessing 276.75 ms +1.48% -1.11% 281.81 ms +4.75% -1.92% -1.8%
largeJpegUploadProcessing 1974.3 ms +1.71% -20.72% 1969.07 ms +1.63% -22.19% 0.27%
multipleImageUploadProcessing 2090.14 ms +0.66% -0.26% 2098.23 ms +0.24% -1.71% -0.39%

post-editor

Metric 790a09e trunk % Change
serverResponse 394.35 ms +1.61% -8.63% 378.87 ms +5.84% -4.13% 4.09%
firstPaint 389.53 ms +26.32% -2.54% 404.29 ms +6.04% -11.89% -3.65%
domContentLoaded 754.88 ms +12.52% -1.31% 762.07 ms +1.62% -1.34% -0.94%
loaded 755.82 ms +12.54% -1.3% 763.06 ms +1.61% -1.33% -0.95%
firstContentfulPaint 434.2 ms +16.54% -2.37% 433.6 ms +2.04% -1.46% 0.14%
firstBlock 1926.78 ms +7.1% -1.03% 1944.74 ms +0.75% -0.96% -0.92%
type 16.61 ms +8.19% -11.08% 16.72 ms +6.1% -12.14% -0.66%
typeWithoutInspector 16.61 ms +6.5% -12.7% 17.3 ms +3.41% -11.91% -3.99%
typeWithTopToolbar 22.34 ms +5.01% -4.34% 21.48 ms +2.23% -4.98% 4%
typeContainer 7.76 ms +7.47% -7.09% 7.68 ms +11.85% -7.42% 1.04%
focus 113.57 ms +5.86% -3.81% 106.87 ms +7.11% -3.82% 6.27%
firstFocus 238.49 ms +0% -0% 234.76 ms +0% -0% 1.59%
selectAll 319.39 ms +0.57% -0.15% 309.29 ms +3.56% -2.54% 3.27%
undo 27.54 ms +11.44% -3.38% 26.56 ms +6.25% -5.72% 3.69%
listViewOpen 72.44 ms +6.57% -13.97% 70.02 ms +7.2% -10.34% 3.46%
inserterOpen 41.6 ms +7.55% -10.02% 40.93 ms +10.07% -10.99% 1.64%
inserterHover 10.92 ms +11.36% -8.61% 11.61 ms +7.92% -7.58% -5.94%
inserterSearch 8.67 ms +13.73% -3.58% 8.15 ms +6.87% -8.34% 6.38%
loadPatterns 624.05 ms +3.7% -5.7% 620.77 ms +9.22% -3.5% 0.53%
wpTotal 384.27 ms +1.82% -8.75% 369.3 ms +5.99% -4.25% 4.05%
wpMemoryUsage 14.81 MB +0% -0% 14.77 MB +0% -0% 0.25%
wpDbQueries 55 +0% -0% 55 +0% -0% 0%

site-editor

Metric 790a09e trunk % Change
serverResponse 401.2 ms +0.99% -5.7% 398.08 ms +1.76% -6.22% 0.78%
firstPaint 442.56 ms +5.68% -4.33% 412.33 ms +10.34% -4.58% 7.33%
domContentLoaded 814.23 ms +5.17% -1.32% 813.31 ms +2.08% -1.33% 0.11%
loaded 815.41 ms +5.16% -1.36% 814.43 ms +2.09% -1.33% 0.12%
firstContentfulPaint 457.99 ms +8.93% -4.13% 460.93 ms +2.29% -1.88% -0.64%
firstBlock 2380.66 ms +6.91% -0.92% 2392.28 ms +1.27% -0.6% -0.49%
type 16.45 ms +11.12% -6.93% 18.71 ms +4.49% -12.13% -12.08%
navigate 110.01 ms +9.18% -3.98% 107.99 ms +1.15% -1.58% 1.87%
loadPatterns 1394.39 ms +2.41% -6.16% 1352.28 ms +5.97% -14.45% 3.11%
loadPages 930.23 ms +2.49% -1.66% 925.6 ms +3.04% -0.75% 0.5%
wpTotal 391.59 ms +1% -5.81% 388.35 ms +1.77% -6.36% 0.83%
wpMemoryUsage 12.82 MB +0% -0% 12.79 MB +0% -0% 0.25%
wpDbQueries 45 +0% -0% 45 +0% -0% 0%

7bcf010 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.

Navigates the list via UP/DOWN arrow keys from action buttons in /test/e2e/specs/site-editor/dataviews-list-layout-keyboard.spec.js, passed after 1 failed attempt.
Error: expect(locator).toBeFocused() failed

Locator:  getByRole('row', { name: 'Page Two Edit Actions' }).getByRole('button', { name: 'Edit' })
Expected: focused
Received: inactive
Timeout:  5000ms

Call log:
  - Expect "toBeFocused" getByRole('row', { name: 'Page Two Edit Actions' }).getByRole('button', { name: 'Edit' }) with timeout 5000ms
  - waiting for getByRole('row', { name: 'Page Two Edit Actions' }).getByRole('button', { name: 'Edit' })
    14 × locator resolved to <button type="button" tabindex="-1" class="components-button is-small" id="view-list-0-164-primary-action-edit-post">Edit</button>
       - unexpected value "inactive"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/dataviews-list-layout-keyboard.spec.js:243:5
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
keeps the default tab on the moved tab in /test/e2e/specs/editor/blocks/tabs.spec.js, passed after 1 failed attempt.
Error: expect(received).toBe(expected) // Object.is equality

Expected: 0
Received: 1

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/blocks/tabs.spec.js:359:60
should apply a named font size using the font size buttons in /test/e2e/specs/editor/various/font-size-picker.spec.js, passed after 1 failed attempt.
Error: expect(received).toBe(expected) // Object.is equality

- Expected  - 2
+ Received  + 2

- <!-- wp:paragraph {"fontSize":"large"} -->
+ <!-- wp:paragraph {"fontSize":"medium"} -->
- <p class="has-large-font-size">Paragraph to be made "large"</p>
+ <p class="has-medium-font-size">Paragraph to be made "large"</p>
  <!-- /wp:paragraph -->

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/font-size-picker.spec.js:153:6
should reset a named font size using the tools panel menu in /test/e2e/specs/editor/various/font-size-picker.spec.js, passed after 1 failed attempt.
Error: expect(received).toBe(expected) // Object.is equality

- Expected  - 2
+ Received  + 2

- <!-- wp:paragraph {"fontSize":"medium"} -->
+ <!-- wp:paragraph {"fontSize":"small"} -->
- <p class="has-medium-font-size">Paragraph with font size reset using tools panel menu</p>
+ <p class="has-small-font-size">Paragraph with font size reset using tools panel menu</p>
  <!-- /wp:paragraph -->

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/font-size-picker.spec.js:178:6
should select synced pattern in /test/e2e/specs/editor/various/writing-flow.spec.js, passed after 1 failed attempt.
Error: expect(locator).toBeFocused() failed

Locator:  locator('[name="editor-canvas"]').contentFrame().locator('[data-type="core/block"]')
Expected: focused
Received: inactive
Timeout:  5000ms

Call log:
  - Expect "toBeFocused" locator('[name="editor-canvas"]').contentFrame().locator('[data-type="core/block"]') with timeout 5000ms
  - waiting for locator('[name="editor-canvas"]').contentFrame().locator('[data-type="core/block"]')
    14 × locator resolved to <div tabindex="0" role="document" draggable="true" data-title="Pattern" data-type="core/block" data-is-drop-zone="true" aria-label="Block: Pattern" id="block-aef0ac97-7766-471d-b2cd-d38958c44ba1" data-block="aef0ac97-7766-471d-b2cd-d38958c44ba1" class="block-editor-block-list__block wp-block is-selected is-reusable block-library-block__reusable-block-container wp-block-block block-editor-block-list__layout">…</div>
       - unexpected value "inactive"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/writing-flow.spec.js:1464:5

7bcf010 Run

@Deepak-Bhojwani

Copy link
Copy Markdown
Contributor

Test Report

Environment

  • WordPress Playground with this PR's build (?gutenberg-pr=86186)
  • Theme: Twenty Twenty-Five
  • Browser: Chrome on Windows 11

Steps

  1. Went to Site Editor > Styles > Typography > Text > Color.
  2. Started with the default text color, Contrast (#111111), on the white background.
  3. Picked Base (#FFFFFF), which is the same as the background.
  4. Switched back to Contrast (#111111).
  5. Picked Accent 1 (#FFEE58), a light yellow.

Results

  • ✅ Step 2: No warning with the default high-contrast color.
  • ✅ Step 3: The notice "This color has poor contrast against the background. Consider increasing contrast." appears in the color popover, and an info icon appears on the Color item.
  • ✅ Step 4: The warning and the icon go away as soon as a high-contrast color is selected again.
  • ✅ Step 5: The warning appears again for the light yellow. The preview confirms the text is hard to read.

Works as described.

Screencast

Screen-Recording-Gutenberg-PR-86186.mp4

@aaronrobertshaw aaronrobertshaw left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thanks for working on this @im3dabasia 👍

I've taken it for a spin

✅ Preset colours resolve before the check
✅ The warning reuses the block editor's copy

A few cases need addressing before we merge though.

Background gradients

The check skips color.gradient but not background.gradient, so it compares against the colour behind the gradient.

  • Readable text on a light gradient over #222 warns
  • #f0f0f0 text on a light gradient over black doesn't

Skipping them, like the Background panel, is simplest. getLowestContrastColor() from #86148 could check the worst stop instead and might be better.

Text gradients

With backgroundClip: text, trunk shows the warning on the Gradient control. The root has none, so nothing shows but screen readers still announce it. These could be skipped too.

Unparseable colours

An oklch() text colour reads as black, so light text on black warns. The OTHER_COLOR guard from #86148 would fix this.

Tests

Tests for these and an updated description would be great.

The check skipped gradients in the legacy color.gradient location only, so
a gradient in background.gradient was checked against the color behind it.
A text gradient is stored in background.gradient, so it is skipped with the
other gradients. The root has no gradient control to show the warning on,
so nothing should be announced either.
colord reads a color it cannot parse, such as oklch(), as black, so light
text on a black background was reported as poor contrast. Skip the check
for those colors instead.
@im3dabasia

Copy link
Copy Markdown
Contributor Author

Thanks for the review, @aaronrobertshaw! I've addressed the feedback:

  1. Background gradients and text gradients are now skipped.
  2. Colours that can't be read, such as oklch(), are skipped in ContrastChecker itself, so the post editor gets the fix too.
  3. Added tests for each case and updated the description.

Checking against the worst gradient stop is left as a follow-up. Could you take another look?

@aaronrobertshaw aaronrobertshaw left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thanks for the updates @im3dabasia 👍

✅ Background and text gradients no longer give a false warning
✅ New tests and an updated description

Background gradients

I don't think there is a great hurry to land this so I think we should go with the better approach suggested and land the worst stop check here instead of a follow-up.

Global Styles stops may need resolving first.

Colours that can't be read

The isValid() checks also change the block inspector. Its oklch(), lab() and color-mix() colours now skip the check. In my testing that removed three false warnings but lost six correct ones.

86186-oklch

Could these colours be resolved instead of skipped? Reading them back from a 1×1 canvas gave the right sRGB value each time. That fixes both warnings.

Self-review

Before re-requesting review, could you do a full self-review and post a short summary of what you checked? If you use an AI tool, the prompt below might help.

Example self-review prompt
You are reviewing my Gutenberg pull request as a strict core reviewer, before it goes back to a human: https://github.com/WordPress/gutenberg/pull/86186

Do not add features. Find every problem, fix it, and prove each fix on screen. Do not trust earlier replies, commit messages or your own past summaries. Verify everything in the code and in a running site.

1. Read everything first
- Read the full PR thread, including resolved comments. List each review point, who raised it, and its status (fixed, not fixed, disputed). For each "fixed", give the exact line that fixes it.
- Where a reviewer offered a skip and a better option, implement the better option unless the thread agreed otherwise.
- Read the full diff against trunk and the closest precedent (#86148 and packages/block-editor/src/hooks/contrast-checker.ts). Note every difference and why.

2. Justify every line
- For each changed line, say what it does, why it is needed, and what breaks without it. Remove anything you cannot justify.
- Check that shared code (ContrastChecker, getContrastWarning) changes only what this PR needs. List every other caller and how it is affected.

3. Test every case on screen, against a trunk build
- Site Editor > Styles > Typography > Text > Color in Twenty Twenty-Five: preset and custom colours, a background colour, a background gradient (light and dark stops), a legacy color.gradient, a text gradient, a background image, oklch() and color-mix() colours, transparent text.
- Check the warning text and the screen reader announcement for each.
- Post editor: block text and background colour warnings still behave as on trunk, including oklch() colours.

4. Checks
- npm run test:unit on the touched tests, npm run lint:js on every changed file, npm run typecheck. Break the code each test covers and confirm the test fails.
- Compare any failing CI job with trunk's latest run.

5. Report
Write a short summary for the thread: each review point and how it was addressed, every difference from trunk, open questions (one sentence each), and anything not fixed with the reason. Re-request review only when every case passes or is listed as an open question.

This branch has not been deployed

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

Labels

[Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). Global Styles Anything related to the broader Global Styles efforts, including Styles Engine and theme.json [Package] Block editor /packages/block-editor [Type] Enhancement A suggestion for improvement.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants