Skip to content

Button: Align focus styles with design system #78646

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mirka merged 13 commits into from
Jul 1, 2026
Merged

Button: Align focus styles with design system #78646

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
53fdaec
Align components Button focus with design system outset ring.
mirka May 25, 2026
22d32db
Hide link underline when focused
mirka May 25, 2026
d201b9d
Move Button focus mixins to top of blocks.
mirka May 25, 2026
7f978ba
Unify link Button focus with other variants.
mirka May 25, 2026
aea9843
Preserve Button layout and scope forced-colors styles.
mirka May 25, 2026
13bfbd3
Add changelogs
mirka May 25, 2026
23bb4a9
Merge trunk
mirka Jun 23, 2026
3dab0ab
Merge trunk into button-outset-ring-focus
mirka Jun 26, 2026
0ca49f2
Merge remote-tracking branch 'origin/trunk' into button-outset-ring-f…
mirka Jun 30, 2026
0be0364
Use ButtonBorder for forced-colors outlines
mirka Jun 30, 2026
064cde8
Refine Button focus styles
mirka Jun 30, 2026
b845a4f
Add changelog
mirka Jun 30, 2026
987884b
Merge branch 'trunk' into button-outset-ring-focus
mirka Jul 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions packages/components/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@

### Enhancements

- `Button`: Align focus rings with the design system ([#78646](https://github.com/WordPress/gutenberg/pull/78646)).
- The `size` prop no longer has any effect and can be safely removed from the following:
- `BorderBoxControl` ([#79420](https://github.com/WordPress/gutenberg/pull/79420))
- `BorderControl` ([#79418](https://github.com/WordPress/gutenberg/pull/79418))
Expand Down
96 changes: 25 additions & 71 deletions packages/components/src/button/style.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
@use "sass:color";
@use "@wordpress/base-styles/colors" as *;
@use "@wordpress/base-styles/mixins";
@use "@wordpress/base-styles/variables" as *;
@use "../utils/theme-variables" as *;

Expand All @@ -11,6 +12,10 @@
*/

.components-button {
&:focus:not(:active) {
@include mixins.outset-ring__focus();
}

display: inline-flex;
text-decoration: none;
font-family: inherit;
Expand All @@ -21,11 +26,6 @@
cursor: var(--wpds-cursor-control);
appearance: none;
background: none;

@media not ( prefers-reduced-motion ) {
transition: box-shadow 0.1s linear;
}

height: $button-size;
align-items: center;
box-sizing: border-box;
Expand All @@ -42,12 +42,6 @@
color: $components-color-accent;

@mirka mirka May 25, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

I'll replace the tokens in a separate PR.

}

// Focus.
// See https://github.com/WordPress/gutenberg/issues/13267 for more context on these selectors.

@mirka mirka May 25, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Removed this issue link because they're no longer relevant.

&:focus:not(:active) {
box-shadow: 0 0 0 var(--wp-admin-border-width-focus) $components-color-accent;
}

/**
* Primary button style.
*/
Expand All @@ -59,24 +53,16 @@
text-decoration: none;
text-shadow: none;

// Show the boundary of the button, in High Contrast Mode.
outline: 1px solid transparent;

&:hover:not(:disabled) {
background: $components-color-accent-darker-10;
color: $components-color-accent-inverted;
}

&:active:not(:disabled) {
background: $components-color-accent-darker-20;
border-color: $components-color-accent-darker-20;
color: $components-color-accent-inverted;
}

&:focus:not(:active) {
box-shadow: inset 0 0 0 1px $components-color-background, 0 0 0 var(--wp-admin-border-width-focus) $components-color-accent;
}

&:disabled,
&:disabled:active:enabled,
&[aria-disabled="true"],
Expand All @@ -85,12 +71,6 @@
// TODO: Prepare for theming (https://github.com/WordPress/gutenberg/pull/45466/files#r1030872724)
color: rgba($white, 0.4);
background: $components-color-accent;
border-color: $components-color-accent;

@mirka mirka May 25, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

border-color was a no-op here. .components-button already sets border: 0, and primary never gives itself a non-zero border width, so border-color does not affect layout or appearance in normal mode.

Primary styling is background + color, not a border stroke (secondary uses inset box-shadow for that).

The forced-colors boundary did not come from border-color either. Trunk used outline: 1px solid transparent on primary (and outline: none on disabled). This PR moves that to @media (forced-colors: active) { outline: 1px solid ButtonText } on .is-primary. Removing border-color is unrelated to that change.

Same reasoning applies to the other removed border-color lines on primary (:active, is-busy): leftovers from when buttons may have used real borders, not something the current styles depend on.

outline: none;

&:focus:enabled {
box-shadow: inset 0 0 0 1px $components-color-background, 0 0 0 var(--wp-admin-border-width-focus) $components-color-accent;
}
}

&.is-busy,
Expand All @@ -107,7 +87,10 @@
$components-color-accent 70%
);
/* stylelint-enable */
border-color: $components-color-accent;
}

@media (forced-colors: active) {
outline: 1px solid ButtonBorder;
}
}

Expand All @@ -117,9 +100,6 @@

&.is-secondary,
&.is-tertiary {
// Show the boundary of the button, in High Contrast Mode.
outline: 1px solid transparent;

&:active:not(:disabled) {
box-shadow: none;
}
Expand All @@ -131,15 +111,24 @@
background: transparent;
transform: none;
}

@media (forced-colors: active) {
outline: 1px solid ButtonBorder;
}
}

/**
* Secondary button style.
*/

&.is-secondary {
box-shadow: inset 0 0 0 $border-width $components-color-accent, 0 0 0 currentColor;
outline: 1px solid transparent; // Shown in high contrast mode.
@media not ( prefers-reduced-motion ) {
transition: box-shadow 0.1s linear;
}

box-shadow:
inset 0 0 0 $border-width $components-color-accent,
0 0 0 currentColor;
Comment on lines +125 to +131

@mirka mirka Jun 30, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

box-shadow is now only for the border for the secondary variant.

white-space: nowrap;
color: $components-color-accent;
background: transparent;
Expand All @@ -156,8 +145,9 @@
box-shadow: inset 0 0 0 $border-width var(--wpds-color-stroke-interactive-neutral-disabled);
}

&:focus:not(:active) {
box-shadow: 0 0 0 currentColor inset, 0 0 0 var(--wp-admin-border-width-focus) $components-color-accent;
@media (forced-colors: active) {
// Inset box-shadow borders are not reliable in forced-colors mode.
box-shadow: none;
}
}

Expand All @@ -183,15 +173,6 @@
p + & {
margin-left: -($grid-unit-15 * 0.5);
}

&:disabled,
&[aria-disabled="true"],
&[aria-disabled="true"]:hover {
&:not(:focus) {
box-shadow: none;
outline: none;
}
}
}

/**
Expand All @@ -210,10 +191,6 @@
color: color.adjust($alert-red, $lightness: -20%);
}

&:focus:not(:active) {
box-shadow: 0 0 0 var(--wp-admin-border-width-focus) $alert-red;
}

&:active:not(:disabled, [aria-disabled="true"]) {
background: $gray-400;
}
Expand Down Expand Up @@ -263,8 +240,9 @@

height: auto;

&:focus {
&:focus:not(:active) {

@mirka mirka May 25, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Omitting active states to match other variants.

border-radius: $radius-small;
text-decoration: none;
}

&:disabled,
Expand All @@ -273,14 +251,6 @@
}
}

// Windows High Contrast mode will show this outline, but not the box-shadow.
// This rule is placed after variant outline declarations (e.g. is-primary,
// is-secondary, is-tertiary) to ensure it wins by source order at the same
// specificity, while not using `:not(:active)` to avoid outline flicker.
&:focus {
outline: 3px solid transparent;
}

&:not(:disabled, [aria-disabled="true"]):active {
color: $components-color-foreground;
}
Expand Down Expand Up @@ -383,22 +353,6 @@
}
}

&:focus:not(:active) {
box-shadow: inset 0 0 0 1px $components-color-background, 0 0 0 var(--wp-admin-border-width-focus) $components-color-accent;
}

// Windows High Contrast mode will show this outline, but not the box-shadow.
&:focus {
outline: 2px solid transparent;
}
}

// Hide focus outline on :active to provide click feedback in forced-colors
// mode, where box-shadow is not visible. Higher specificity (0,3,0)
// ensures this wins over variant outline declarations. Placed after
// .is-pressed to also win by source order at equal specificity (0,3,0).
&:focus:active {
outline: none;
}

svg {
Expand Down
Loading