Components: update Button to use more wpds tokens by simison · Pull Request #79993 · WordPress/gutenberg

simison · 2026-07-08T10:11:59Z

What?

Migrate @wordpress/components Button baseline styles to WPDS tokens (typography, spacing, sizing, radius, and focus), while preserving existing component behaviour and legacy 36px default height.
Adds "With Icon" Storybook example for easier testing of that case specifically.
Updates "small" buttons to use same font size as UI Button (11px → 13px).

Doesn't migrate colour-related variables yet to keep testing easier/more focused. I have another follow-up which migrates colors: #79994

Earlier PRs on Button tokenisation:

Why?

Aligns Theming systems between @wordpress/components and @wordpress/ui.

How?

Testing Instructions

Run storybook: npm run storybook:dev and open http://localhost:50240/?path=/docs/components-button--docs

Verify Button variants in Storybook (default, primary, secondary, tertiary, link, small, compact, icon-only) all look and behave the same:

Resting
Hover
Focus
Focus hover
Active
Keyboard navigation

Testing Instructions for Keyboard

Screenshots or screencast

There should not be any visual difference between before/after:

Before

After

Icon one specifically:

Before

After

Use of AI Tools

yes

github-actions · 2026-07-08T10:12:08Z

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

Required label: Any label starting with [Type].
Labels found: [Package] Components, [Feature] Component System, Design System.

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

github-actions · 2026-07-08T10:14:25Z

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: simison <simison@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: jasmussen <joen@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>

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

simison · 2026-07-08T10:19:36Z

+	// Legacy default height (36px) has no exact WPDS size token match.
+	--wp-components-button-height: 36px;


Not sure if there's an alternative solution 🤔

github-actions · 2026-07-08T10:23:10Z

Size Change: +435 B (+0.01%)

Total Size: 7.75 MB

📦 View Changed

Filename	Size	Change
`build/styles/components/style-rtl.css`	18.2 kB	+112 B (+0.62%)
`build/styles/components/style-rtl.min.css`	15.1 kB	+103 B (+0.69%)
`build/styles/components/style.css`	18.2 kB	+115 B (+0.63%)
`build/styles/components/style.min.css`	15.1 kB	+105 B (+0.7%)

_{compressed-size-action}

github-actions · 2026-07-08T10:48:31Z

Flaky tests detected in b87b609.
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.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/29116506316
📝 Reported issues:

[Flaky Test] three users concurrently edit a large post with diverse blocks (RTC WebSocket) #79926 in /test/e2e/specs/editor/collaboration/collaboration-stress.spec.ts

ciampo

I'm torn on whether we should continue to use the SASS variables or switch to WPDS tokens directly. if the goal is true @wordpress/ui alignment, we should migrate Button internals toward WPDS tokens directly. If the goal is legacy compatibility, keep component aliases or use local Button variables that bridge both, eg

--wp-components-button-background-color: var(
  --wp-components-color-accent,
  var(--wpds-color-background-interactive-brand-strong)
);

That gives a migration path without dropping existing customization hooks too abruptly.

Re. background: transparent, I guess that we should generally map to WPDS weak background tokens (instead of raw transparent) when they represent a button tone/variant.

We should also be careful when replacing background: none with a color token. background: none resets images too, which matters for busy/loading styles.

Here's a potential mapping

components primary
-> ui brand solid
bg: --wpds-color-background-interactive-brand-strong
bg active: --wpds-color-background-interactive-brand-strong-active
fg: --wpds-color-foreground-interactive-brand-strong

components secondary
-> ui brand outline
bg: --wpds-color-background-interactive-brand-weak        // #0000
bg active: --wpds-color-background-interactive-brand-weak-active
bg disabled: --wpds-color-background-interactive-brand-weak-disabled
border: --wpds-color-stroke-interactive-brand
fg: --wpds-color-foreground-interactive-brand

components tertiary
-> ui brand minimal
bg: --wpds-color-background-interactive-brand-weak        // #0000
bg active: --wpds-color-background-interactive-brand-weak-active
bg disabled: --wpds-color-background-interactive-brand-weak-disabled
fg: --wpds-color-foreground-interactive-brand

destructive secondary/tertiary
-> error outline/minimal equivalent
bg: --wpds-color-background-interactive-error-weak        // #0000
bg active: --wpds-color-background-interactive-error-weak-active
fg: --wpds-color-foreground-interactive-error
border: --wpds-color-stroke-interactive-error for outline-ish secondary

This is a change with a potential large visual impact, probably better to land it after the next Gutenberg release (which means this change will be included in WP 7.2, giving us ample time to test and make adjustments if needed)

Also cc @t-hamano as some the folks with the keenest eye on Button.

ciampo · 2026-07-09T10:40:35Z

-			// TODO: Prepare for theming (https://github.com/WordPress/gutenberg/pull/45466/files#r1030872724)
-			color: rgba($white, 0.4);
+			color: var(--wpds-color-foreground-interactive-brand-strong-disabled);


This is a potentially substantial difference. More in general, would you mind updating a full matrix of the button variants, like done in #78646 ?

We have a specific Storybook example used for ad-hoc e2e viz reg that you can visit by running npm run storybook:e2e:dev

Thanks for the tip about strokybook:e2e! Didn't know we had more examples to test with there.

I'm assuming some visual changes are ok considering what we just did with Notice.

Primary+disabled button:

Components Button in PR:

Components Button in trunk (looks better):

UI Button:

So I think we should change the background and text colour in tandem, at least for the disabled state, to avoid some kind of mixed style between the two that doesn't look that great.

Yes, although I believe this warrants a broader conversation (to make sure we potentially address button styles on the php side) and the blessing of @WordPress/gutenberg-design

Catching up. What needs a decision here? Is it the disabled state? If yes then I agree trunk looks better, gray on blue is barely legible (even though it doesn't have to be on a disabled button).

Noting that there was a previous attempt to move disabled buttons to look substantially less prominent in #70674, which was reverted specifically because we wanted to move towards a more considered token-based system. In that range, does this move us in the right direction? If it's mostly the disabled states, let me know and I'll test more in-depth those styles.

@jasmussen, in the UI-Button disabled state looks like this:

Can we make the components-Button look the same, or is it better to keep it as-is today (image below) and migrate to the new disabled style by swapping out components around Gutenberg one-by-one?

Thanks for the clarity. I feel like this is moving in the right direction, on all counts, and is a good argument for why we made the origiginal change. It's exactly what we said we'd do: do it systematically, with tokens. Kudos.

Can we make the components-Button look the same, or is it better to keep it as-is today (image below) and migrate to the new disabled style by swapping out components around Gutenberg one-by-one?

That's a good question. In principle that would be ideal since they are meant to look the same. But perhaps it's okay for this to be a slow transition with the old still keeping the legacy behavior? How do you feel about it?

We did mention that, ideally, we would minimize the visual difference between @wordpress/components and @wordpress/ui componentry to ensure a better transition.

IMO, we should prioritize refactoring the styles in @wordpress/components to follow the new look from @wordpress/ui, since it will allow us to mix-and-match the two components (legacy and new version) without too many inconsistencies as we progressively refactor the repo (and as third party devs may continue to use the legacy version)

simison · 2026-07-10T19:04:58Z

I updated this PR to touch only font size, border width, spacing and things like that; I'm moving all the colours-related token swapping to happen at once in the follow-up PR #79994

I'll update PR description with screenshots.

simison · 2026-07-15T08:08:56Z

+		// 22px has no exact WPDS line-height token match (sm is 20px, md is 24px).
 		line-height: 22px;


UI uses --wpds-typography-line-height-sm (20px) for all sizes, including small.

UI small = 24px tall, 13px font (font-size-md), 20px line-height, 0 vertical padding.

Components small = 24px tall, 11px font (font-size-xs), 22px line-height, 0 vertical padding.

Both end up 24px tall.

...separate question if we should align the font sizes for the small variant. Could be a good follow-up or done already here.

Default and compact use already the same font size.

Outer size matches, although typography, internal spacing and "growth" behaviour are different.

I feel like the line height shouldn't be what guarantees the minimum clickable areas (24px), and therefore I prefer the wordpress/ui approach that uses min-height. Moreover, I believe that changing line-height here won't change the clickable box.

Still, I believe we could align font-size and line height here (ie. use font-size-md and line-height-sm) , I guess we could do it in this PR?

We will need to update the matrix screenshots, since small buttons will grow wider (not taller)

Still, I believe we could align font-size and line height here (ie. use font-size-md and line-height-sm) , I guess we could do it in this PR?

Let's do it. 👍 It's unavoidable anyway if we want to be able to mix components and have things look consistent.

Updated!

We will need to update the matrix screenshots, since small buttons will grow wider (not taller)

There was no small (nor compact) variants in the e2e matrix.

I added them locally and here's comparison, but snapshots wouldn't need updating:

Before

After

UI Button matrix with same additions:

Hmm link button in small format now inherits wrong padding, need to fix that.

Sounds good! Let me know once you've fixed that and I'll take another look

Not super pretty but simply avoiding resetting the padding to 0: dc954ec

Hmm, I can see some regressions with small link buttons height:

Excluding .is-link from both height and padding fixes the horizontal padding, but it makes the small link target depend on its content. With the current cascade, a text-only small link is 20px tall, an icon-only one is 24px, and an icon-and-text one is 36px because the later .has-icon rule restores 6px block padding around the 24px icon. Trunk kept all three at 24px. Could we guarantee the 24px small control height for every variant and special-case only the link padding? The small link-and-icon case also needs to avoid reacquiring that later block padding.

simison · 2026-07-15T09:00:24Z

This is a change with a potential large visual impact, probably better to land it after the next Gutenberg release (which means this change will be included in WP 7.2, giving us ample time to test and make adjustments if needed)

@ciampo, agreed on this — which exact GB version is safe for Button changes?

ciampo · 2026-07-15T15:46:29Z

This is a change with a potential large visual impact, probably better to land it after the next Gutenberg release (which means this change will be included in WP 7.2, giving us ample time to test and make adjustments if needed)

@ciampo, agreed on this — which exact GB version is safe for Button changes?

Probably 23.7? (@t-hamano can confirm)

t-hamano · 2026-07-15T16:09:14Z

This is a change with a potential large visual impact, probably better to land it after the next Gutenberg release (which means this change will be included in WP 7.2, giving us ample time to test and make adjustments if needed)

@ciampo, agreed on this — which exact GB version is safe for Button changes?

Probably 23.7? (@t-hamano can confirm)

This PR will not be backported to WP 7.1, correct? If so, there is nothing to do. Merging this PR now will release it as part of GB 23.7.

ciampo · 2026-07-15T16:46:04Z

+		// 22px has no exact WPDS line-height token match (sm is 20px, md is 24px).
 		line-height: 22px;


Outer size matches, although typography, internal spacing and "growth" behaviour are different.

I feel like the line height shouldn't be what guarantees the minimum clickable areas (24px), and therefore I prefer the wordpress/ui approach that uses min-height. Moreover, I believe that changing line-height here won't change the clickable box.

Still, I believe we could align font-size and line height here (ie. use font-size-md and line-height-sm) , I guess we could do it in this PR?

We will need to update the matrix screenshots, since small buttons will grow wider (not taller)

ciampo · 2026-08-20T11:20:05Z

Now that 7.1 shipped, should we resume work and aim to ship this soon into the 7.2 dev cycle?

Noting that, in the meantime, we've unified focus rings already

simison requested review from a team and ajitbohra as code owners July 8, 2026 10:12

simison added [Package] Components /packages/components [Feature] Component System WordPress component system Design System Issues related to the system of combining components according to best practices. labels Jul 8, 2026

github-project-automation Bot added this to Design systems — Backlog Jul 8, 2026

simison mentioned this pull request Jul 8, 2026

Components: Components and UI Button color parity #79994

Draft

simison commented Jul 8, 2026

View reviewed changes

This comment was marked as outdated.

Sign in to view

ciampo reviewed Jul 9, 2026

View reviewed changes

simison force-pushed the update/components-button-wpds-tokens branch from f9a939d to b87b609 Compare July 10, 2026 18:59

aduth mentioned this pull request Jul 13, 2026

Notice: Fix low-contrast action controls on dark theme backgrounds #80209

Closed

ciampo mentioned this pull request Jul 14, 2026

Notice: link/secondary action controls are low-contrast on dark theme backgrounds #80211

Open

simison force-pushed the update/components-button-wpds-tokens branch from b87b609 to 78bd5e9 Compare July 14, 2026 15:15

simison requested review from ciampo and mirka July 14, 2026 15:26

simison added the [Type] Enhancement A suggestion for improvement. label Jul 14, 2026

ciampo reviewed Jul 14, 2026

View reviewed changes

Comment thread packages/components/CHANGELOG.md Outdated

Comment thread packages/components/src/button/style.scss

simison force-pushed the update/components-button-wpds-tokens branch from e8becb6 to e5a84a5 Compare July 15, 2026 07:28

simison commented Jul 15, 2026

View reviewed changes

simison force-pushed the update/components-button-wpds-tokens branch from 5844afe to 5872476 Compare July 15, 2026 08:11

ciampo reviewed Jul 15, 2026

View reviewed changes

simison force-pushed the update/components-button-wpds-tokens branch 3 times, most recently from 037c139 to dc954ec Compare July 17, 2026 16:46

simison added 8 commits July 28, 2026 16:50

Components Button: Migrate basic styles to design tokens

9e55521

Add "With Icon" Storybook example

e1b8423

Update changelog

46629da

Rebase fix for outline

f09df87

Dashicon space fix

05f2c9e

Restore legacy 6px padding for icons

d8b7205

Align with UI Button font size for small buttons

c7bd7cd

Fix small link button padding

5abb944

simison force-pushed the update/components-button-wpds-tokens branch from dc954ec to 5abb944 Compare July 28, 2026 13:50

simison mentioned this pull request Jul 28, 2026

Storybook e2e: add small, compact and icon examples to button matrix #80793

Merged

		// Legacy default height (36px) has no exact WPDS size token match.
		--wp-components-button-height: 36px;

		// 22px has no exact WPDS line-height token match (sm is 20px, md is 24px).
		line-height: 22px;

Conversation

simison commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Testing Instructions for Keyboard

Screenshots or screencast

Before

After

Icon one specifically:

Before

After

Use of AI Tools

Uh oh!

github-actions Bot commented Jul 8, 2026

Uh oh!

github-actions Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

ciampo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Primary+disabled button:

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ciampo Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

simison commented Jul 10, 2026

Uh oh!

Uh oh!

Uh oh!

simison Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

simison Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

simison Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

simison Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

simison commented Jul 8, 2026 •

edited

Loading

github-actions Bot commented Jul 8, 2026 •

edited

Loading

github-actions Bot commented Jul 8, 2026 •

edited

Loading

github-actions Bot commented Jul 8, 2026 •

edited

Loading

ciampo Jul 13, 2026 •

edited

Loading

simison Jul 15, 2026 •

edited

Loading

simison Jul 15, 2026 •

edited

Loading

simison Jul 16, 2026 •

edited

Loading

simison Jul 17, 2026 •

edited

Loading

ciampo commented Aug 20, 2026 •

edited

Loading