Skip to content

Components: Align Button colors with the UI package - #85073

Closed
jameskoster wants to merge 16 commits into
trunkfrom
stabilize-ui-button
Closed

jameskoster wants to merge 16 commits into
trunkfrom
stabilize-ui-button

Conversation

@jameskoster

@jameskoster jameskoster commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Follows merged #85939. Busy-spinner work remains in #85960. Related to #84573 and #76135.

What?

Align legacy Button colors with the semantic colors used by @wordpress/ui.

Why?

Use the same theme-aware colors without changing button sizing, wrapping, typography, or busy presentation.

How?

Use WPDS semantic tokens and their generated fallbacks for Button colors. Update grouped, toolbar, and header overrides to keep their state colors consistent. Preserve disabled primary header fills in light and dark themes, and system-color fills in forced colors mode. Keep busy stripes visible during pointer and keyboard activation.

Color customization changes: With the token stylesheet loaded, WPDS colors take precedence over admin color schemes and legacy --wp-components-color-* overrides. Without the tokens, generated fallbacks follow the admin color scheme. Use ThemeProvider to customize the WPDS palette.

Testing Instructions

  1. Run npm run storybook:e2e:dev and open the Button "Variant States" story. Check light, dark, and a custom orange primary color. Enabled labels should remain readable, including against both busy stripes.
  2. Check normal, pressed, destructive, and disabled states while resting and hovering.
  3. In the editor, Widgets, and Customizer, toggle the header controls. Pressed buttons should use matching colors; pressed disabled primary controls should keep their neutral fill in light and dark themes.
  4. In a Toolbar, check pressed disabled secondary and tertiary buttons. Their fill should stay inset.
  5. Turn on forced colors and check pressed header controls in the editor, Widgets, and Customizer. Enabled controls should have a selection fill; disabled controls should have a disabled fill.
  6. On a page without ThemeProvider, compare Button with and without the WPDS token stylesheet. WPDS colors win when loaded; the selected admin scheme supplies the generated fallback when tokens are absent.

Testing Instructions for Keyboard

  1. Move the pointer away, Tab to a pressed or destructive button, and hold Space. Its label should remain readable.
  2. Activate a busy button with Enter or Space. Its label and stripes stay visible, and the button remains clickable.

Screenshots or screencast

Latest trunk at capture time, e85ab418c68, compared with this PR at a403e34c1c5. Each pair uses matching props, viewport, theme, and reduced-motion settings.

Light-theme Button variant matrix, with trunk on the left and this PR on the right

Detailed Button states

Space captures hold Space with the pointer away from the button. Hover captures place the pointer over the button.

State Trunk This PR
Disabled primary, light Trunk: disabled primary Button in the light theme This PR: disabled primary Button in the light theme
Pressed tertiary, dark, Space held Trunk: pressed tertiary Button during Space activation in the dark theme This PR: pressed tertiary Button during Space activation in the dark theme
Busy secondary, dark, Space held Trunk: busy secondary Button during Space activation in the dark theme This PR: busy secondary Button during Space activation in the dark theme
Destructive primary, dark, hover Trunk: destructive primary Button on hover in the dark theme This PR: destructive primary Button on hover in the dark theme
Header compositions in the dark theme

These isolated compositions use production Button, Toolbar, and header styles. Each header shows an enabled and a disabled pressed primary control.

Trunk This PR
Trunk: Editor, Widgets, and Customizer pressed header controls in the dark theme This PR: Editor, Widgets, and Customizer pressed header controls in the dark theme

Use of AI Tools

This PR was implemented with Cursor. I reviewed the styling, recommendation metadata, and tests, and I am responsible for the change.

The rebase, color-only rescope, and follow-up fixes used Codex and independent local agent reviews.

@github-actions github-actions Bot added [Package] Components /packages/components [Package] Editor /packages/editor [Package] Block library /packages/block-library [Tool] ESLint plugin /packages/eslint-plugin [Package] Block editor /packages/block-editor [Package] Edit Widgets /packages/edit-widgets [Package] Edit Site /packages/edit-site [Package] Base styles /packages/base-styles [Package] Commands /packages/commands [Package] UI /packages/ui labels Oct 19, 2026
@github-actions

github-actions Bot commented Oct 19, 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: jameskoster <jameskoster@git.wordpress.org>
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: +2.19 kB (+0.03%)

Total Size: 8.63 MB

📦 View Changed
Filename Size Change
build/styles/components/style-rtl.css 18.1 kB +250 B (+1.4%)
build/styles/components/style-rtl.min.css 15.2 kB +302 B (+2.03%)
build/styles/components/style.css 18.2 kB +245 B (+1.37%)
build/styles/components/style.min.css 15.2 kB +299 B (+2%)
build/styles/customize-widgets/style-rtl.css 3.04 kB +122 B (+4.18%)
build/styles/customize-widgets/style-rtl.min.css 2.02 kB +122 B (+6.43%) 🔍
build/styles/customize-widgets/style.css 3.04 kB +123 B (+4.22%)
build/styles/customize-widgets/style.min.css 2.02 kB +122 B (+6.43%) 🔍
build/styles/edit-widgets/style-rtl.css 5.4 kB +76 B (+1.43%)
build/styles/edit-widgets/style-rtl.min.css 3.98 kB +75 B (+1.92%)
build/styles/edit-widgets/style.css 5.39 kB +75 B (+1.41%)
build/styles/edit-widgets/style.min.css 3.98 kB +75 B (+1.92%)
build/styles/editor/style-rtl.css 31.5 kB +51 B (+0.16%)
build/styles/editor/style-rtl.min.css 27.3 kB +102 B (+0.38%)
build/styles/editor/style.css 31.6 kB +48 B (+0.15%)
build/styles/editor/style.min.css 27.3 kB +101 B (+0.37%)

a403e34 Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric 5e7e553 trunk % Change
timeToFirstByte 41.8 ms +11.72% -2.87% 42.35 ms +2.83% -4.84% -1.3%
largestContentfulPaint 72 ms +5.56% -5.56% 70 ms +8.57% -2.86% 2.86%
lcpMinusTtfb 28.4 ms +4.23% -2.99% 28.1 ms +15.12% -6.94% 1.07%
wpBeforeTemplate 21.95 ms +16.04% -2.69% 21.74 ms +6.95% -1.93% 0.97%
wpTemplate 16.61 ms +5.3% -4.52% 16.36 ms +5.56% -3.97% 1.53%
wpTotal 38.36 ms +12.43% -2.89% 38.91 ms +3.52% -4.19% -1.41%
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 5e7e553 trunk % Change
timeToFirstByte 34.95 ms +5.29% -4.29% 34.55 ms +4.2% -2.75% 1.16%
largestContentfulPaint 76 ms +5.26% -0% 76 ms +5.26% -0% 0%
lcpMinusTtfb 42.6 ms +1.88% -1.88% 42.4 ms +1.3% -2.12% 0.47%
wpBeforeTemplate 18.91 ms +4.92% -0.74% 18.86 ms +3.92% -1.11% 0.27%
wpTemplate 12.76 ms +4.94% -3.29% 12.57 ms +4.61% -3.1% 1.51%
wpTotal 32.2 ms +5.47% -3.63% 31.97 ms +4.38% -2.31% 0.72%
wpMemoryUsage 6.41 MB +0% -0% 6.38 MB +0% -0% 0.53%
wpDbQueries 13 +0% -0% 13 +0% -0% 0%

media-processing

Metric 5e7e553 trunk % Change
mediaProcessingJpeg 327.32 ms +0.96% -0.87% 325.5 ms +0.36% -1.07% 0.56%
mediaProcessingAvif 4844.7 ms +0.4% -0.34% 4882.75 ms +0.13% -0.21% -0.78%
mediaProcessingJpegToAvif 3385.44 ms +0.01% -0.3% 3384.61 ms +0.37% -0.46% 0.02%

media-upload

Metric 5e7e553 trunk % Change
jpegUploadProcessing 1433.98 ms +0.79% -1.5% 1420.86 ms +1.16% -0.81% 0.92%
pngUploadProcessing 209.38 ms +5.9% -3.68% 213.85 ms +4.37% -4.19% -2.09%
largeJpegUploadProcessing 1414.59 ms +0.39% -0.63% 1412.86 ms +0.3% -0.14% 0.12%
multipleImageUploadProcessing 1470 ms +2.56% -1.05% 1472.34 ms +0.36% -0.59% -0.16%

post-editor

Metric 5e7e553 trunk % Change
serverResponse 482.58 ms +1.23% -6.9% 440.18 ms +8.64% -1.43% 9.63%
firstPaint 367.7 ms +4.01% -20.4% 368.87 ms +32.84% -13.66% -0.32%
domContentLoaded 849.54 ms +1.99% -1.61% 848.91 ms +0.91% -0.78% 0.07%
loaded 850.46 ms +2.02% -1.58% 850.02 ms +0.94% -0.8% 0.05%
firstContentfulPaint 503.46 ms +1.67% -4.72% 489.25 ms +4.38% -0.91% 2.9%
firstBlock 2213.79 ms +1.03% -1.83% 2206.82 ms +0.55% -1.4% 0.32%
type 16.3 ms +5.09% -9.51% 16.28 ms +2.83% -7.49% 0.12%
typeWithoutInspector 17.03 ms +9.51% -12.16% 15.93 ms +3.45% -6.47% 6.91%
typeWithTopToolbar 22.28 ms +7.5% -5.61% 21.7 ms +6.54% -6.31% 2.67%
typeContainer 8.22 ms +72.02% -9.73% 8.16 ms +7.48% -8.58% 0.74%
focus 112.12 ms +12.15% -4.91% 116.8 ms +6.81% -5.15% -4.01%
firstFocus 244.44 ms +0% -0% 239.83 ms +0% -0% 1.92%
selectAll 428.04 ms +0.02% -8.98% 427.8 ms +1.3% -1.6% 0.06%
undo 28.68 ms +5.37% -4.85% 27.85 ms +8.08% -2.51% 2.98%
listViewOpen 77.69 ms +14% -2.55% 75.96 ms +6.9% -9.04% 2.28%
inserterOpen 43.65 ms +7.12% -5.09% 40.61 ms +7.29% -7.54% 7.49%
inserterHover 11.37 ms +8.8% -8.8% 11.19 ms +9.56% -5.81% 1.61%
inserterSearch 7.94 ms +12.34% -3.4% 7.65 ms +11.37% -3.14% 3.79%
loadPatterns 624.88 ms +4.64% -5.49% 634.05 ms +4.04% -4.27% -1.45%
wpTotal 472.96 ms +1.28% -7.03% 430.46 ms +8.86% -1.44% 9.87%
wpMemoryUsage 14.77 MB +0% -0% 14.74 MB +0% -0% 0.24%
wpDbQueries 55 +0% -0% 55 +0% -0% 0%

site-editor

Metric 5e7e553 trunk % Change
serverResponse 389.39 ms +2.4% -2.1% 382.27 ms +0.77% -3.7% 1.86%
firstPaint 345.71 ms +3.63% -1.7% 327.76 ms +20.98% -7.35% 5.48%
domContentLoaded 829.34 ms +2.36% -1.3% 814.55 ms +0.48% -0.66% 1.82%
loaded 830.28 ms +2.38% -1.28% 815.45 ms +0.49% -0.66% 1.82%
firstContentfulPaint 475.55 ms +6.63% -0.5% 471.21 ms +0.12% -1.5% 0.92%
firstBlock 2377.5 ms +6.37% -1.38% 2306.31 ms +1.07% -0.87% 3.09%
type 17.91 ms +2.23% -9.38% 16.69 ms +8.15% -4.25% 7.31%
navigate 105.18 ms +6.36% -1.06% 101.57 ms +1.52% -7.86% 3.55%
loadPatterns 1095.73 ms +14.16% -3.47% 1224.75 ms +12.56% -18.68% -10.53%
loadPages 959.75 ms +1.78% -1.41% 955.75 ms +2.13% -3.09% 0.42%
wpTotal 380.06 ms +2.45% -2.13% 372.94 ms +0.82% -4.42% 1.91%
wpMemoryUsage 12.79 MB +0% -0% 12.75 MB +0% -0% 0.27%
wpDbQueries 45 +0% -0% 45 +0% -0% 0%

a403e34 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
Undo restores the post selection when another synced entity is loaded 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
moves selected text into another paragraph in /test/e2e/specs/editor/various/draggable-blocks.spec.js, passed after 1 failed attempt.
Error: expect(received).toMatchObject(expected)

- Expected  - 2
+ Received  + 2

  Array [
    Object {
      "attributes": Object {
-       "content": "First third",
+       "content": "First second third",
      },
      "name": "core/paragraph",
    },
    Object {
      "attributes": Object {
-       "content": "Fourth second fifth",
+       "content": "Fourth fifth",
      },
      "name": "core/paragraph",
    },
  ]

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/draggable-blocks.spec.js:1167:41
should select with shift + click in /test/e2e/specs/editor/various/multi-block-selection.spec.js, passed after 1 failed attempt.
Error: expect(received).toEqual(expected) // deep equality

- Expected  - 1
+ Received  + 0

  Array [
-   1,
    2,
  ]

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:380:5

a403e34 Run

@jameskoster jameskoster added [Feature] UI Components Impacts or related to the UI component system Design System Issues related to the system of combining components according to best practices. and removed [Package] Editor /packages/editor [Package] Block library /packages/block-library [Tool] ESLint plugin /packages/eslint-plugin [Package] Block editor /packages/block-editor [Package] Edit Widgets /packages/edit-widgets [Package] Edit Site /packages/edit-site [Package] Base styles /packages/base-styles [Package] Commands /packages/commands labels Oct 19, 2026
@github-actions github-actions Bot added [Package] Editor /packages/editor [Package] Block library /packages/block-library [Tool] ESLint plugin /packages/eslint-plugin [Package] Block editor /packages/block-editor [Package] Edit Widgets /packages/edit-widgets [Package] Edit Site /packages/edit-site [Package] Base styles /packages/base-styles [Package] Commands /packages/commands labels Oct 19, 2026
@ciampo
ciampo force-pushed the stabilize-ui-button branch from 5297c07 to 2d27402 Compare November 9, 2026 17:33
@ciampo
ciampo requested a review from manzoorwanijk as a code owner November 9, 2026 17:33
@ciampo ciampo added the [Type] Enhancement A suggestion for improvement. label Nov 9, 2026
@ciampo
ciampo requested a review from Mamaduka November 9, 2026 17:36
@ciampo

ciampo commented Nov 9, 2026

Copy link
Copy Markdown
Contributor

Thank you, Jay !

Given that visually things look good, let's wait for a code-focused review, too.

This comment was marked as resolved.

@mirka

mirka commented Nov 10, 2026

Copy link
Copy Markdown
Member

I still feel misaligned with the overall scope/ambition/risk profile of this PR, and it's making it hard to greenlight for me.

It's pretty big even with just the Button changes, so I'm not sure why it's mixed together with changes in so many other components. I may be missing something but it doesn't seem to need to land together.

I also don't quite understand why we're not going with the smallest possible change in the Button stylesheet. It seems like it could be just a token value swap, but it's actually changing a lot of structure and specificity, which increases the breakage surface. Is that restructuring intended, and worth it at this point? If it is intended, could it be broken down further into smaller changesets with justification? It feels like a departure from the usual caution we've exercised for this component.

(A quick local test with a simple token swap strategy seemed fine by the way.)

@ciampo

ciampo commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

It seems like it could be just a token value swap

I haven't experimented in details, but we can probably preserve more of the existing selectors and order. My aim was to use the matching WPDS foreground, background, and border tokens across states, including in dark and custom themes. That needs mapping at each declaration, since the legacy accent variable serves several roles, and destructive buttons currently override it locally. But that doesn't mean all the selector restructuring needs to come with it.

A "safer" iteration would be to keep the existing structure wherever possible and justify any remaining selector changes with specific failing cases, such as keyboard activation or busy stripes disappearing.

it doesn't seem to need to land together.

Some of the surrounding changes are coupled to Button's pressed colors. Toolbar paints its own pressed background, and the headers override that background again. Those need to stay paired with Button's foreground changes, but they could form a separate PR together.

Maybe we could split this PR into three smaller parts:

  1. Map ordinary Button variants to WPDS tokens, preserving the existing selectors wherever possible.
  2. Migrate destructive states to the matching error tokens, including their busy colors.
  3. Migrate pressed states together with the corresponding Toolbar and header overrides.

WDYT ?

@mirka

mirka commented Nov 11, 2026

Copy link
Copy Markdown
Member

Not sure how many PRs total, but I think the first pass would be really easy to land if it were only value changes with no specificity/selector changes. We can get pretty far with just that, right?

@ciampo

ciampo commented Nov 11, 2026

Copy link
Copy Markdown
Contributor

Sure, we can get a useful first pass with value changes only. Most ordinary states already declare fg and bg together, so using matching WPDS tokens doesn't itself require changing selectors.

As mentioned above, the main caveat is destructive buttons: they override the shared accent variable to red. Replacing its uses with brand tokens would bypass those overrides, so we'd need to preserve that mechanism or leave the affected declarations for a later pass.

I'd also keep the pressed-state changes together with Toolbar and the header overrides, since those paint their own backgrounds and need to match Button's foreground. That group can be deferred.

Those state-by-state mappings will still be needed to align with UI Button and follow the theme with accessible text contrast, including in dark and custom themes. I'm happy to split that work into smaller PRs. That doesn't mean every selector change in this PR is necessary; any that remain should be justified by a specific failing case, such as keyboard activation.

I'll proceed to implement those changes across a series of PRs so that you can take a look and validate the split

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

Labels

Design System Issues related to the system of combining components according to best practices. [Feature] UI Components Impacts or related to the UI component system [Package] Components /packages/components [Package] Edit Widgets /packages/edit-widgets [Package] Editor /packages/editor [Type] Enhancement A suggestion for improvement.

Projects

Status: 💫 Done

Development

Successfully merging this pull request may close these issues.

4 participants