Skip to content

Theme: Preserve contrast after color rounding - #86189

Merged
ciampo merged 7 commits into
trunkfrom
codex/theme-rounded-contrast
Nov 10, 2026
Merged

ciampo merged 7 commits into
trunkfrom
codex/theme-rounded-contrast

Conversation

@ciampo

@ciampo ciampo commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Follow-up to #82505 and #82591.

What?

Preserve configured contrast targets after generated colors are rounded to 8-bit sRGB, and report remaining failures from the final emitted colors. Generated default color token values shift slightly too.

Why?

Blue and Ocean weak neutral text fell below 4.5:1 even though their internal color calculations reached 4.52:1.

How?

Make the rounding reserve proportional to the contrast target and account for the solver's logarithmic tolerance. Check every configured reference after seed adjustment, including reused colors, while preserving the existing exclusions. Restore the fgFill target to 4.5 because the shared reserve now handles rounding, avoiding unnecessary seed adjustments.

Default ramps, tokens, and fallbacks are rebuilt. The separate 3:1 brand-fill warnings remain.

Testing Instructions

  1. Open Design System → Theme → Theme Provider → Color Scales → Sample Combinations in local Storybook.
  2. Check Blue and Ocean. Their weak neutral text should reach approximately 4.63:1 and 4.62:1, respectively, and their 4.5:1 text warnings should clear. The 3:1 fill warnings remain.
  3. Check Default light, WordPress light, and Light. They should still report No warnings.
  4. In the Default story, set the background to #1e1e1e with primary #3858e9. Confirm the resting brand-fill warnings remain, while text passes its contrast checks.

Testing Instructions for Keyboard

Use the keyboard to edit the Default story's color controls and confirm that the warning report updates with the same results.

Verification

All 321 affected tests pass, including Chromium. The production build, theme typecheck, and JavaScript lint pass. A comparison covering 2,560 seed and background-lightness combinations reduces adjusted seeds from 396 to 374 when the fgFill target returns from 4.55 to 4.5. Both fill states retain at least 4.5576:1 text contrast in that sample.

Use of AI Tools

Codex investigated the failures, implemented the numerical safeguards and regression tests, regenerated the token files, ran verification, addressed review feedback, and drafted this description. Separate Codex agents reviewed the changes.

@github-actions github-actions Bot added [Package] Base styles /packages/base-styles [Package] Theme /packages/theme labels 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: ciampo <mciampini@git.wordpress.org>
Co-authored-by: mirka <0mirka00@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: +153 B (0%)

Total Size: 8.63 MB

📦 View Changed
Filename Size Change
build/modules/boot/index.min.js 51.3 kB +22 B (+0.04%)
build/modules/core-fields/page.min.js 7.07 kB +4 B (+0.06%)
build/modules/core-fields/post_type_supports.min.js 80.5 kB -15 B (-0.02%)
build/modules/core-fields/wp_template_part.min.js 38.5 kB -8 B (-0.02%)
build/modules/core-fields/wp_template.min.js 10.5 kB -6 B (-0.06%)
build/modules/workflow/index.min.js 41.8 kB +6 B (+0.01%)
build/scripts/block-directory/index.min.js 42.7 kB +7 B (+0.02%)
build/scripts/block-editor/index.min.js 545 kB +28 B (+0.01%)
build/scripts/block-library/index.min.js 425 kB -9 B (0%)
build/scripts/components/index.min.js 336 kB +27 B (+0.01%)
build/scripts/customize-widgets/index.min.js 22.9 kB +2 B (+0.01%)
build/scripts/edit-site/index.min.js 379 kB +25 B (+0.01%)
build/scripts/edit-widgets/index.min.js 29.1 kB +3 B (+0.01%)
build/scripts/editor/index.min.js 568 kB +21 B (0%)
build/scripts/format-library/index.min.js 72.6 kB -2 B (0%)
build/scripts/media-utils/index.min.js 234 kB +8 B (0%)
build/scripts/notices/index.min.js 45.8 kB +9 B (+0.02%)
build/scripts/patterns/index.min.js 12.9 kB -1 B (-0.01%)
build/scripts/theme/index.min.js 27 kB +37 B (+0.14%)
build/scripts/widgets/index.min.js 64.7 kB -9 B (-0.01%)
build/styles/block-library/editor.css 13 kB -1 B (-0.01%)
build/styles/block-library/editor.min.css 10.6 kB -1 B (-0.01%)
build/styles/block-library/icon/editor-rtl.css 1.54 kB -1 B (-0.06%)
build/styles/block-library/icon/editor.min.css 585 B -1 B (-0.17%)
build/styles/block-library/query/editor-rtl.css 1.47 kB -1 B (-0.07%)
build/styles/block-library/query/editor-rtl.min.css 539 B -1 B (-0.19%)
build/styles/block-library/query/editor.css 1.47 kB -1 B (-0.07%)
build/styles/block-library/query/editor.min.css 539 B -1 B (-0.19%)
build/styles/edit-site/style-rtl.css 20.6 kB +1 B (0%)
build/styles/edit-site/style-rtl.min.css 16.7 kB +1 B (+0.01%)
build/styles/edit-site/style.css 20.6 kB +1 B (0%)
build/styles/edit-site/style.min.css 16.7 kB +1 B (+0.01%)
build/styles/editor/style-rtl.css 31.5 kB +1 B (0%)
build/styles/editor/style-rtl.min.css 27.2 kB +2 B (+0.01%)
build/styles/editor/style.css 31.6 kB +1 B (0%)
build/styles/editor/style.min.css 27.2 kB +2 B (+0.01%)
build/styles/theme/design-tokens-rtl.css 3.17 kB -1 B (-0.03%)
build/styles/theme/design-tokens-rtl.min.css 1.52 kB +2 B (+0.13%)
build/styles/theme/design-tokens.css 3.17 kB -1 B (-0.03%)
build/styles/theme/design-tokens.min.css 1.52 kB +2 B (+0.13%)

e4d93ad Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric 1f63fba trunk % Change
timeToFirstByte 57.15 ms +9.54% -5.16% 63.85 ms +3.45% -5.87% -10.49%
largestContentfulPaint 92 ms +10.87% -4.35% 102 ms +9.8% -5.88% -9.8%
lcpMinusTtfb 35.05 ms +5.14% -3.14% 37.7 ms +26.39% -3.45% -7.03%
wpBeforeTemplate 30.38 ms +8.99% -5.99% 32.49 ms +5.17% -3.97% -6.49%
wpTemplate 23.13 ms +6.05% -6.53% 26.16 ms +5.77% -6.96% -11.58%
wpTotal 53.27 ms +10.17% -5.63% 59.51 ms +2.74% -5.66% -10.49%
wpMemoryUsage 7.72 MB +0% -0% 7.69 MB +0% -0% 0.43%
wpDbQueries 16 +0% -0% 16 +0% -0% 0%

front-end-classic-theme

Metric 1f63fba trunk % Change
timeToFirstByte 47.6 ms +7.35% -3.47% 48.85 ms +5.32% -2.15% -2.56%
largestContentfulPaint 104 ms +3.85% -3.85% 104 ms +3.85% -0% 0%
lcpMinusTtfb 55.15 ms +3.17% -1.9% 56 ms +0.89% -3.3% -1.52%
wpBeforeTemplate 27.36 ms +8.55% -2.27% 27.92 ms +6.38% -2.36% -2.01%
wpTemplate 16.74 ms +9.14% -3.52% 17.16 ms +5.01% -3.03% -2.45%
wpTotal 44.42 ms +7.5% -3.29% 45.57 ms +5.6% -2.59% -2.52%
wpMemoryUsage 6.41 MB +0% -0% 6.38 MB +0% -0% 0.53%
wpDbQueries 13 +0% -0% 13 +0% -0% 0%

media-processing

Metric 1f63fba trunk % Change
mediaProcessingJpeg 405.47 ms +0.79% -0.85% 409.47 ms +0.32% -0.86% -0.98%
mediaProcessingAvif 6181.84 ms +0.7% -0.06% 6200.51 ms +0.8% -0.25% -0.3%
mediaProcessingJpegToAvif 4277.31 ms +0.11% -0.29% 4244.85 ms +0.45% -0.04% 0.76%

media-upload

Metric 1f63fba trunk % Change
jpegUploadProcessing 1946.93 ms +0.86% -24.08% 1947.78 ms +1.32% -0.67% -0.04%
pngUploadProcessing 287.28 ms +6.03% -38.75% 231.01 ms +26.93% -23.15% 24.36%
largeJpegUploadProcessing 1955.23 ms +0.23% -0.57% 1946.35 ms +0.75% -0.2% 0.46%
multipleImageUploadProcessing 2085.75 ms +1.17% -0.22% 2070.18 ms +0.93% -1.05% 0.75%

post-editor

Metric 1f63fba trunk % Change
serverResponse 422.18 ms +0.74% -7.89% 411.22 ms +3.26% -7.07% 2.67%
firstPaint 351.73 ms +4.7% -9.26% 393.08 ms +22.9% -17.55% -10.52%
domContentLoaded 851.04 ms +1.36% -1.63% 845.14 ms +1.6% -0.61% 0.7%
loaded 852.1 ms +1.36% -1.62% 846.21 ms +1.61% -0.61% 0.7%
firstContentfulPaint 497.79 ms +4.73% -3.81% 485.8 ms +1.78% -0.91% 2.47%
firstBlock 2201.5 ms +3.61% -3.11% 2160.15 ms +0.93% -0.86% 1.91%
type 17.68 ms +3.79% -12.33% 17.85 ms +1.34% -11.48% -0.95%
typeWithoutInspector 18.46 ms +3.58% -16.36% 17.99 ms +3.11% -13.95% 2.61%
typeWithTopToolbar 23.99 ms +4.88% -8.84% 24.3 ms +15.68% -12.35% -1.28%
typeContainer 8.55 ms +13.92% -3.39% 7.88 ms +2.79% -2.41% 8.5%
focus 123.91 ms +4.41% -3.99% 117.76 ms +7.18% -3.63% 5.22%
firstFocus 273.79 ms +0% -0% 237.28 ms +0% -0% 15.39%
selectAll 338.23 ms +4.2% -0.94% 346.25 ms +10.62% -3.54% -2.32%
undo 31.91 ms +4.92% -6.99% 31.24 ms +5.57% -4.71% 2.14%
listViewOpen 81.09 ms +14.42% -9.3% 75.13 ms +11.62% -3.7% 7.93%
inserterOpen 43.71 ms +9.06% -4.78% 41.54 ms +12.28% -5.1% 5.22%
inserterHover 12.77 ms +8.85% -12.69% 11.98 ms +10.27% -9.02% 6.59%
inserterSearch 9.69 ms +7.12% -10.84% 8.98 ms +19.82% -4.45% 7.91%
loadPatterns 701.17 ms +3.16% -4.19% 701.46 ms +2.14% -2.02% -0.04%
wpTotal 412.65 ms +0.79% -8.18% 401.79 ms +3.06% -7.36% 2.7%
wpMemoryUsage 14.77 MB +0% -0% 14.74 MB +0% -0% 0.24%
wpDbQueries 55 +0% -0% 55 +0% -0% 0%

site-editor

Metric 1f63fba trunk % Change
serverResponse 255.5 ms +7.14% -6.09% 262.2 ms +4.73% -4.41% -2.56%
firstPaint 262.62 ms +7.92% -11.07% 242.76 ms +9.06% -4.25% 8.18%
domContentLoaded 606.43 ms +2.17% -4.83% 615.29 ms +2.15% -1.61% -1.44%
loaded 607.27 ms +2.16% -4.83% 616.24 ms +2.13% -1.62% -1.46%
firstContentfulPaint 353.09 ms +4.52% -2.36% 353.5 ms +3.38% -1.92% -0.12%
firstBlock 1804.77 ms +1.23% -1.75% 1838.52 ms +1.04% -1.67% -1.84%
type 13.51 ms +6.37% -6% 16.64 ms +7.99% -1.5% -18.81%
navigate 92.33 ms +4.28% -18.14% 93.87 ms +8.55% -4.75% -1.64%
loadPatterns 900.41 ms +12.97% -7.63% 1026.74 ms +11.9% -7.81% -12.3%
loadPages 983.67 ms +3.99% -2.5% 1023.92 ms +4.54% -1.55% -3.93%
wpTotal 248.96 ms +7.3% -6.35% 255.55 ms +4.93% -4.65% -2.58%
wpMemoryUsage 12.79 MB +0% -0% 12.75 MB +0% -0% 0.27%
wpDbQueries 45 +0% -0% 45 +0% -0% 0%

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

As a user I expect my navigation to use the colors I selected for it in /test/e2e/specs/editor/blocks/navigation-colors.spec.js, passed after 1 failed attempt.
Error: locator.click: Error: strict mode violation: getByRole('option', { name: 'Cyan bluish gray' }) resolved to 2 elements:
    1) <button type="button" role="option" tabindex="-1" aria-selected="false" aria-label="Cyan bluish gray" id="components-circular-option-picker-1-13" class="components-button components-circular-option-picker__option is-next-40px-default-size"></button> aka locator('#components-circular-option-picker-1-13')
    2) <button type="button" role="option" tabindex="-1" aria-selected="false" aria-label="Cyan bluish gray" id="components-circular-option-picker-2-25" class="components-button components-circular-option-picker__option is-next-40px-default-size"></button> aka locator('#components-circular-option-picker-2-25')

Call log:
  - waiting for getByRole('option', { name: 'Cyan bluish gray' })

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/blocks/navigation-colors.spec.js:324:5
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
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":21,"sizeSlug":"full","linkDestination":"none"} -->
+ <figure class="wp-block-image size-full"><img src="http://localhost:8889/wp-content/uploads/2026/11/3b79b01d-f5f9-4f00-98f9-084f9770a2a5.png" alt="" class="wp-image-21"/></figure>
  <!-- /wp:image -->
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/blocks/image.spec.js:432:49

From 16c3715, not the current head. Run

@ciampo ciampo added the [Type] Bug An existing feature does not function as intended label Nov 2, 2026 — with ChatGPT Codex Connector
@ciampo ciampo self-assigned this Nov 2, 2026
@ciampo
ciampo requested a balanced review from Copilot November 2, 2026 13:38
@ciampo
ciampo requested a review from jsnajdr November 2, 2026 13:40

Copilot AI 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.

🟢 Approval recommended

No active review issues remain for the contrast-rounding and final-color validation changes.

No open issues 🎉

What changed in this PR

This PR updates @wordpress/theme color generation to preserve contrast targets after 8-bit sRGB rounding and report remaining failures from the final emitted colors.

Changes:

  • Makes the rounding margin proportional to the contrast target and accounts for solver tolerance.
  • Validates final colors after seed adjustment, including reused steps, while preserving existing exclusions.
  • Adds regression coverage and regenerates default ramps, tokens, and fallbacks.
File Description
packages/​theme/​tokens/​color.json Updates generated color values.
packages/​theme/​src/​test/​theme-provider.browser.test.tsx Updates browser warning expectations.
packages/​theme/​src/​test/​theme-provider-color-warnings.test.ts Updates the seed-adjustment regression case.
packages/​theme/​src/​color-ramps/​test/​index.test.ts Adds contrast and rounding regression tests.
packages/​theme/​src/​color-ramps/​lib/​utils.ts Applies proportional margin and solver-tolerance compensation.
packages/​theme/​src/​color-ramps/​lib/​index.ts Checks final emitted colors for contrast failures.
packages/​theme/​src/​color-ramps/​lib/​default-ramps.ts Refreshes precomputed default ramps.
packages/​theme/​src/​color-ramps/​lib/​constants.ts Defines the rounding margin and clarifies tolerance units.
packages/​theme/​README.md Updates documented contrast ratios.
packages/​theme/​prebuilt/​js/​design-tokens.mjs Refreshes generated token metadata and fallbacks.
packages/​theme/​prebuilt/​js/​design-token-fallbacks.mjs Refreshes JavaScript token fallbacks.
packages/​theme/​prebuilt/​css/​design-tokens.css Refreshes generated CSS token values.
packages/​theme/​CHANGELOG.md Records the contrast correction.
packages/​base-styles/​internal/​_wpds-token-fallbacks.scss Synchronizes Sass token fallbacks.

Review effort: Balanced

@github-actions github-actions Bot added the [Package] Components /packages/components label Nov 2, 2026
@ciampo
ciampo marked this pull request as ready for review November 2, 2026 13:57
@ciampo
ciampo requested a review from a team as a code owner November 2, 2026 13:57
Comment thread packages/theme/CHANGELOG.md Resolved
Comment on lines +71 to +91
it( 'reports a ramp warning when rounded colors miss a required contrast target', () => {
const { ramp, warnings } = buildRamp(
'rgb(0 10.6 0)',
{
...BG_RAMP_CONFIG,
fgSurface3: {
contrast: {
reference: 'seed',
followDirection: 'lighter',
target: 20.05,
},
lightness: () => 1,
},
},
{ rescaleToFitContrastTargets: false }
);

expect( getContrast( ramp.surface2, ramp.fgSurface3 ) ).toBeLessThan(
20.05
);
expect( warnings ).toContain( 'fgSurface3' );

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.

I think this passes with the old warning logic too. Is that expected?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

True, I missed that.

I've added a new regression test that fails with the old logic: meeting the configured target must clear the warning even if the rounding reserve is missed.

@ciampo
ciampo force-pushed the codex/theme-rounded-contrast branch from 16c3715 to e4d93ad Compare November 10, 2026 07:25
@ciampo
ciampo enabled auto-merge (squash) November 10, 2026 08:57
@ciampo
ciampo merged commit 75a9ee7 into trunk Nov 10, 2026
130 of 137 checks passed
@ciampo
ciampo deleted the codex/theme-rounded-contrast branch November 10, 2026 09:12
@github-actions github-actions Bot added this to the Gutenberg 24.5 milestone Nov 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Package] Base styles /packages/base-styles [Package] Components /packages/components [Package] Theme /packages/theme [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