[thetaPC]

Issue number: resolves internal

---

What is the current behavior?

Buttons only have bold colors. Unlike chip and badge, which also have a color prop, there's no hue prop for muted colors.

What is the new behavior?

• Adds a hue prop to ion-button. It reads the prop first, then IonButton.hue in the theme config, and defaults to bold, like chip
• Adds hue.subtle to the recipe in every theme, with the same fills, states, semantic colors, ripple and disabled styles as bold
• Subtle colors come from the shared subtle palette that chip, badge and text already use:
  • solid: the subtle fill with its paired contrast text
  • outline: the same background as bold (transparent, or the page color in ionic), foreground text and a subtle shade border. md keeps its neutral 12% border
  • clear: transparent with foreground text
• Text on the page or a translucent tint uses foreground, and text on an opaque fill of the color uses contrast, matching ion-text and FW-6422
• md and ios outline buttons use foreground for their text too, like clear. In ios, clear buttons with a color also keep foreground on hover and focus
• Buttons inside ion-datetime and ion-input-password-toggle stay bold, since those components only style the bold tokens, so a hue from the config doesn't restyle them
• Adds a hue test page that shows both hues in every fill, color and state
• Adds an axe check for subtle buttons in the light and dark palettes, without the colors listed under Known gaps
• Snapshots are in chore(button): update snapshots for the subtle hue #31656.

Does this introduce a breaking change?

• Yes
• No

The text of outline buttons in md and ios uses the color's darker foreground instead of base. In ios, clear buttons with a color also keep foreground on hover and focus. To revert, set IonButton.hue.bold.outline.<state>.color (.semantic.<state>.color with a color) for global styles, or --ion-button-hue-bold-outline-<state>-color for component-specific styles, to the color's base. For ios clear buttons with a color, set IonButton.hue.bold.clear.semantic.<state>.color or --ion-button-hue-bold-clear-semantic-<state>-color for hover and focus to the color's base as well.

Other information

Why these choices

• The shared subtle palette instead of iOS 17's tinted button: the iOS 17 kit's Bezeled style is the button's color at 15% (#D9E5FC for primary), measured from the kit and from a native UIButton in its tinted configuration. The shared palette (#EBF1FD) matches ios chips and badges, works for every color and follows the palette in dark mode. iOS 17's value would make subtle buttons darker than the subtle chips beside them
• md and ionic have no subtle design: MD2 has no tonal button, and the ionic design only has fill, outline and ghost. Both follow the shared subtle palette
• Outline keeps bold's background: a subtle fill behind an outline would make it look like a subtle solid button
• Outline text uses foreground in md and ios: the text sits on the page, not on a fill of the color, so it follows the same rule as clear. Using base made outline labels lighter than clear labels in the same color

Known gaps

• Subtle light, warning and success text fails WCAG's 4.5:1 on white, the same as in subtle chips. The colors come from the shared palette, so the fix belongs there (FW-6417). Subtle light also fails in dark mode. The axe check leaves these colors out until FW-6417 fixes them
• Toolbars only override bold, so a subtle button in a toolbar uses the theme's subtle tokens. The ion-buttons and toolbar migrations can add their own

How to test

Check	Before	After	What to look for
Both hues, ios		After	Each fill shows bold, then subtle, in every color. Subtle solid has a pale fill with colored text, and subtle outline and clear have darker colored text
Both hues, md		After	Same as ios, with the ripple on press and elevation on subtle solid
Both hues, ionic		After	Hovering or pressing subtle outline and clear fills them with the subtle shade
Outline text, md	Before	After	Colored outline labels are darker, matching clear buttons
Outline text, ios	Before	After	Same as md

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
ionic-framework	Ready	Preview	Nov 12, 2026 10:03pm UTC

[ShaneK]

Looks good to me, thanks for the fixes, just a couple of small follow-ups on the tests!

[ShaneK]

Looks good to me, great work!

[ShaneK]

In the ionic theme, the text on a hovered subtle outline or clear button darkens while it's pressed and goes back on release, for example rgb(0, 84, 233) to rgb(0, 74, 205) for primary. The merge in 392620e removed their activated tokens, so the color here falls back to the default color instead of the hover one. Bold doesn't hit this because its hover color is already the default. Which would you prefer?

• Make the subtle outline and clear hover color match the default, like bold
• Restore the activated color as the contrast color for ionic subtle outline and clear

[thetaPC]

Went with the first option in 844c5ad. Ionic subtle outline and clear were the only buttons in any theme whose hover changed the text color, so their hover now keeps foreground, like bold. Restoring the activated color would have brought back a text color change on touch, where a press goes straight from the resting color to contrast. I also added a test that hovers each hue and fill, presses, and checks the text color stays the same. It fails on the old tokens with the colors you found.