Skip to content

Theme: Make chroma capacity caching deterministic - #82505

Open
ciampo wants to merge 3 commits into
trunkfrom
codex/theme-deterministic-chroma-cache
Open

Theme: Make chroma capacity caching deterministic#82505
ciampo wants to merge 3 commits into
trunkfrom
codex/theme-deterministic-chroma-cache

Conversation

@ciampo

@ciampo ciampo commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

Follow up to #82294 (comment).

What?

Make the taperChroma capacity cache deterministic while keeping its rounded cache buckets.

Why?

The cache key rounds lightness, hue, and the chroma cap, but trunk calculates the cached value from the first unrounded input in that bucket. The same ramp can therefore get a different result depending on which theme populated the cache first.

How?

Calculate each cached chroma capacity at the rounded lightness and hue represented by its key. Keep the hard chroma cap exact. A regression test checks that an unrelated input in the same bucket cannot change a later result. Generated ramps and token files are rebuilt from the corrected calculation.

Performance

The existing background ramp snapshots unit test was run in a separate process 11 times on each revision.

Revision Median test time Difference
Trunk (929bded78c7) 249 ms
This PR (8182a53b855) 251 ms +2 ms (+0.8%)

An exact-key prototype had a 541 ms median across nine runs, 117% slower than trunk on the same workload. Calculating at the rounded point fixes the order dependence without losing the useful cache hits.

Testing Instructions

  1. Run npm run test:unit:vitest -- packages/theme/src/color-ramps/test.
  2. Confirm that all color-ramp tests and snapshots pass.

Testing Instructions for Keyboard

Not applicable. This change has no user interface.

Use of AI Tools

OpenAI Codex helped isolate the change, write the regression test, measure performance, regenerate derived files, and draft this description. The author reviewed the implementation and results.

@coderabbitai

coderabbitai Bot commented Sep 6, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: 3da0e354-86b0-465e-9f36-71ae0f8a6a6a

📥 Commits

Reviewing files that changed from the base of the PR and between 929bded and 22c9134.

⛔ Files ignored due to path filters (1)
  • packages/theme/src/color-ramps/test/__snapshots__/index.test.ts.snap is excluded by !**/*.snap
📒 Files selected for processing (8)
  • packages/base-styles/internal/_wpds-token-fallbacks.scss
  • packages/theme/CHANGELOG.md
  • packages/theme/prebuilt/css/design-tokens.css
  • packages/theme/prebuilt/js/design-token-fallbacks.mjs
  • packages/theme/src/color-ramps/lib/default-ramps.ts
  • packages/theme/src/color-ramps/lib/taper-chroma.ts
  • packages/theme/src/color-ramps/test/taper-chroma.test.ts
  • packages/theme/tokens/color.json

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.


📝 Summary

Summary by CodeRabbit

  • Bug Fixes

    • Fixed color ramp generation so results remain consistent regardless of cache population order.
    • Corrected fallback color behavior across error, surface, foreground, and stroke tokens.
  • Style

    • Updated the color palette and design-token values for primary, informational, success, warning, caution, and error states.
    • Refined surface backgrounds, interactive states, text colors, fills, and borders for improved visual consistency.

Walkthrough

Updated theme color tokens, default color ramps, generated fallback values, and chroma cache quantization. Added a regression test and changelog entry for cache-order-independent ramp generation.

Changes

Theme color system

Layer / File(s) Summary
Color token and ramp definitions
packages/theme/tokens/color.json, packages/theme/src/color-ramps/lib/default-ramps.ts
Updated primitive color tokens and default ramp values across the supported color palettes.
Chroma cache quantization
packages/theme/src/color-ramps/lib/taper-chroma.ts, packages/theme/src/color-ramps/test/taper-chroma.test.ts, packages/theme/CHANGELOG.md
Aligned cache keys and max-chroma calculations with quantized lightness and hue values. Added regression coverage and changelog documentation.
Generated token fallbacks
packages/base-styles/internal/_wpds-token-fallbacks.scss, packages/theme/prebuilt/css/design-tokens.css, packages/theme/prebuilt/js/design-token-fallbacks.mjs
Regenerated fallback values for surfaces, foregrounds, interactive states, and strokes.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 22c91

This update makes color-ramp cache results independent of cache population order and refreshes the corresponding theme token outputs. No current merge-blocking risk remains.

Suggested reviewers: simison

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 4 files. (4 skipped: 4 … Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly identifies the main change: making taperChroma chroma-capacity caching deterministic.
Description check ✅ Passed The description directly explains the caching change, its motivation, implementation, performance impact, and testing instructions.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 4 files. (4 skipped: 4 unsupported.)

  • Fix all pre-merge checks with AI
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/theme-deterministic-chroma-cache

Warning

Some tools did not complete. Review the errors below.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

packages/theme/prebuilt/css/design-tokens.css

ESLint skipped: missing config or dependency (missing-dependency). The ESLint configuration references a package that is not available in the sandbox.

packages/theme/prebuilt/js/design-token-fallbacks.mjs

ESLint skipped: the matched ESLint configuration already failed (missing-dependency).

packages/theme/src/color-ramps/lib/default-ramps.ts

ESLint skipped: the matched ESLint configuration already failed (missing-dependency).

  • 2 others

Comment @coderabbitai help to get the list of available commands.

@github-actions github-actions Bot added [Package] Base styles /packages/base-styles [Package] Theme /packages/theme labels Sep 6, 2026

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.

These are the main code changes, the rest is either tests or regenerated snapshots / prebuilt assets

@ciampo ciampo self-assigned this Sep 6, 2026
@ciampo ciampo added the [Type] Bug An existing feature does not function as intended label Sep 6, 2026
@ciampo
ciampo marked this pull request as ready for review September 6, 2026 13:42
@ciampo
ciampo requested a review from a team as a code owner September 6, 2026 13:42
@github-actions

github-actions Bot commented Sep 6, 2026

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

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>

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

@github-actions

github-actions Bot commented Sep 6, 2026

Copy link
Copy Markdown

🤖 PR meta 🤖

📦 Bundle size

Size Change: -228 B (0%)

Total Size: 8 MB

📦 View Changed
Filename Size Change
build/scripts/block-editor/index.min.js 479 kB +1 B (0%)
build/scripts/components/index.min.js 267 kB +1 B (0%)
build/scripts/customize-widgets/index.min.js 59 kB -22 B (-0.04%)
build/scripts/edit-widgets/index.min.js 66.8 kB -23 B (-0.03%)
build/scripts/editor/index.min.js 584 kB -14 B (0%)
build/scripts/format-library/index.min.js 40.3 kB +1 B (0%)
build/scripts/theme/index.min.js 26.9 kB +1 B (0%)
build/styles/components/style-rtl.css 16.1 kB -20 B (-0.12%)
build/styles/components/style-rtl.min.css 13.6 kB -21 B (-0.15%)
build/styles/components/style.css 16.2 kB -19 B (-0.12%)
build/styles/components/style.min.css 13.7 kB -21 B (-0.15%)
build/styles/theme/design-tokens-rtl.css 3.09 kB -23 B (-0.74%)
build/styles/theme/design-tokens-rtl.min.css 1.49 kB -23 B (-1.52%)
build/styles/theme/design-tokens.css 3.09 kB -23 B (-0.74%)
build/styles/theme/design-tokens.min.css 1.49 kB -23 B (-1.52%)

22c9134 Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric d17acaf trunk % Change
timeToFirstByte 66.1 ms +2.87% -12.63% 59.35 ms +12.97% -6.07% 11.37%
largestContentfulPaint 100 ms +8% -4% 98 ms +6.12% -10.2% 2.04%
lcpMinusTtfb 37.9 ms +6.33% -18.21% 32 ms +24.37% -6.09% 18.44%
wpBeforeTemplate 35.67 ms +2.44% -20.04% 32.12 ms +7.35% -13.39% 11.05%
wpTemplate 25.11 ms +4.02% -2.15% 24.73 ms +3.03% -5.94% 1.54%
wpTotal 61.36 ms +3.03% -12.17% 55.38 ms +11.97% -5.69% 10.8%
wpMemoryUsage 7.52 MB +0% -0% 7.48 MB +0% -0% 0.46%
wpDbQueries 17 +0% -0% 17 +0% -0% 0%

front-end-classic-theme

Metric d17acaf trunk % Change
timeToFirstByte 46.4 ms +5.71% -6.03% 45.9 ms +4.25% -4.25% 1.09%
largestContentfulPaint 92 ms +8.7% -4.35% 92 ms +4.35% -2.17% 0%
lcpMinusTtfb 45.5 ms +3.63% -2.42% 45.35 ms +3.86% -1.32% 0.33%
wpBeforeTemplate 26.99 ms +18.12% -4.37% 27.49 ms +6.58% -5.57% -1.82%
wpTemplate 14.24 ms +8.43% -2.39% 14.66 ms +4.64% -3.07% -2.86%
wpTotal 43.39 ms +5.35% -7.03% 42.49 ms +5.67% -3.48% 2.12%
wpMemoryUsage 5.51 MB +0% -0% 5.47 MB +0% -0% 0.64%
wpDbQueries 14 +0% -0% 14 +0% -0% 0%

media-processing

Metric d17acaf trunk % Change
mediaProcessingJpeg 403.01 ms +0.34% -0.57% 399.17 ms +0.62% -0.55% 0.96%
mediaProcessingAvif 6258.05 ms +0.25% -0.51% 6226.57 ms +0.17% -0.21% 0.51%
mediaProcessingJpegToAvif 4454.9 ms +0.07% -0.38% 4411.75 ms +0.26% -0.1% 0.98%

media-upload

Metric d17acaf trunk % Change
jpegUploadProcessing 1436.21 ms +34.64% -1.43% 1429.49 ms +1.7% -1.01% 0.47%
pngUploadProcessing 215.65 ms +3.62% -3.77% 204.5 ms +3.33% -1.37% 5.45%
largeJpegUploadProcessing 1404.17 ms +0.46% -0.74% 1405.02 ms +0.28% -0.37% -0.06%
multipleImageUploadProcessing 1568.49 ms +0.32% -1.53% 1573.44 ms +9.61% -1.4% -0.31%

post-editor

Metric d17acaf trunk % Change
serverResponse 455.91 ms +1.59% -11.25% 424.81 ms +5.26% -4.73% 7.32%
firstPaint 209.69 ms +15.17% -3.9% 262.08 ms +52.78% -31.85% -19.99%
domContentLoaded 1321.1 ms +0.13% -3.44% 1279.39 ms +2.22% -1.89% 3.26%
loaded 1322.4 ms +0.14% -3.43% 1280.85 ms +2.23% -1.91% 3.24%
firstContentfulPaint 441.37 ms +4.15% -9.5% 420.67 ms +3.69% -2.67% 4.92%
firstBlock 3518.96 ms +1.63% -0.98% 3417.46 ms +1.05% -0.82% 2.97%
type 16.45 ms +12.4% -2.25% 16.9 ms +16.75% -9.41% -2.66%
typeWithoutInspector 15.38 ms +3.71% -7.02% 14.43 ms +4.85% -8.73% 6.58%
typeWithTopToolbar 19.51 ms +7.12% -4% 19.46 ms +8.38% -3.34% 0.26%
typeContainer 9.38 ms +5.44% -6.4% 9.03 ms +11.18% -11.3% 3.88%
focus 82.52 ms +19.44% -7.27% 77.46 ms +15.76% -6.7% 6.53%
firstFocus 183.19 ms +0% -0% 223.93 ms +0% -0% -18.19%
selectAll 559.82 ms +1.56% -1.49% 568.7 ms +3.63% -4.61% -1.56%
listViewOpen 66.92 ms +18.56% -10.71% 66.48 ms +16.37% -4.77% 0.66%
inserterOpen 24.63 ms +8.24% -9.74% 25.36 ms +4.22% -7.41% -2.88%
inserterHover 3.53 ms +5.95% -7.65% 3.91 ms +9.97% -4.6% -9.72%
inserterSearch 8.13 ms +17.71% -4.55% 9.59 ms +11.05% -5.94% -15.22%
loadPatterns 648.6 ms +2.54% -3.77% 652.47 ms +7.36% -2.4% -0.59%
wpTotal 444.42 ms +1.72% -11.56% 413.99 ms +5.21% -4.99% 7.35%
wpMemoryUsage 13.06 MB +0% -0% 13.02 MB +0% -0% 0.28%
wpDbQueries 54 +0% -1.85% 54 +0% -0% 0%

site-editor

Metric d17acaf trunk % Change
serverResponse 504.53 ms +4.76% -3.92% 483.14 ms +4.01% -5.6% 4.43%
firstPaint 247.7 ms +77.84% -8.07% 287.48 ms +39.16% -15.16% -13.84%
domContentLoaded 1399.16 ms +0.94% -1.33% 1377.34 ms +1.55% -0.36% 1.58%
loaded 1400.33 ms +0.93% -1.33% 1378.5 ms +1.56% -0.35% 1.58%
firstContentfulPaint 446.75 ms +0.42% -1.4% 435.76 ms +1.13% -0.58% 2.52%
firstBlock 4416.41 ms +0.56% -0.26% 4397.64 ms +0.54% -1.13% 0.43%
type 14.31 ms +4.89% -3.21% 15.28 ms +3.66% -7.72% -6.35%
navigate 103.58 ms +11.29% -2.06% 101.36 ms +3.96% -12.29% 2.19%
loadPatterns 1585.93 ms +1.97% -10.58% 1366.06 ms +7.65% -7.74% 16.1%
loadPages 1124.44 ms +1.05% -2.39% 1133.51 ms +5.2% -2.71% -0.8%
wpTotal 494.7 ms +4.77% -4.02% 473.18 ms +4.26% -5.64% 4.55%
wpMemoryUsage 12.07 MB +0% -0% 12.04 MB +0% -0% 0.23%
wpDbQueries 43 +2.33% -0% 43 +2.33% -0% 0%

22c9134 Run

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

1 participant