Add corner radius presets to ThemeProvider

[jameskoster]

What

Adds a cornerRadius theme aspect to ThemeProvider, letting consumers pick a roundness preset for a subtree: none, subtle, moderate, or pronounced.

Preset values are authored as Terrazzo modes on the border-radius primitives and emitted as prebuilt CSS. ThemeProvider always sets data-wpds-corner-radius on its scoping div (defaulting to subtle); the cascade updates --wpds-border-radius-* for all @wordpress/ui components in that subtree.

Also includes a corner-radius control in the Design System Theme Storybook toolbar and a preset <select> in the Example Application story.

Why

Corner radius is a meaningful theme personality axis (sharp vs. soft UI), but today the border-radius scale is static. Color and cursor are already configurable via ThemeProvider; radius can follow the same pattern so apps can tune roundness without overriding tokens manually.

Using build-time token modes (not runtime CSS injection) keeps this simple, performant, and composable: multiple ThemeProvider instances on a page can use different presets, and nested providers inherit/override via the cascade. Portalled UI (dialogs, tooltips, menus) is expected to render its own dedicated ThemeProvider, which carries the preset to the portalled subtree rather than relying on the root provider's preset leaking through :root.

Early exploration used uniform multipliers per preset (e.g. 2× / 3× across all primitives). That felt lop-sided in practice: absolute jumps grow with token size, so cards and dialogs (--wpds-border-radius-lg) changed dramatically while buttons and inputs (--wpds-border-radius-sm) barely moved. The preset values are hand-tuned per primitive instead. At higher presets the per-size scale intentionally compresses toward a shared radius — small controls round up substantially while large surfaces are held back — so a pronounced theme reads as strongly rounded controls on calmly rounded cards and shells, rather than ballooning every corner.

A runtime taper formula (e.g. per-token multiplier curves or a multiplier escape hatch) was considered but deferred — with four presets across five primitives (~20 explicit values), explicit mode values are easier to reason about, validate in Storybook, and ship without a second code path.

The scale started at six presets and was reduced to four after feedback that six was too many for an initial offering and that some adjacent names were ambiguous.

Preset names use a roundness-amount scale (subtle → pronounced) rather than t-shirt sizes or shape words (sharp, pill, etc.). That avoids colliding with the underlying --wpds-border-radius-* token sizes (xs–xl) and avoids overpromising a specific corner shape on larger surfaces (e.g. a card in the default preset is gently rounded, not literally "sharp"). none is kept as the one literal, unambiguous value.

How

• border.json: Each of the five radius primitives (xs, sm, md, lg, xl) defines $extensions.mode overrides for all four presets (corner-radius-none, -subtle, -moderate, -pronounced). The xl primitive (page and app shell surfaces) is the newest addition and is brought into the preset system here so shells scale alongside the other steps. subtle is the default and matches the static base values, but is authored explicitly like the others (no longer a no-op baseline). The tokens/modes/*.json files and prebuilt CSS are generated from these.
• terrazzo.config.ts: Added a modeSelectors entry per preset, each gated on its [data-wpds-corner-radius="…"] attribute.
• ThemeProvider: New cornerRadius prop (a CornerRadiusPreset string); resolves with inheritance (default subtle) and always writes data-wpds-corner-radius (including subtle).
• useThemeProviderStyles: Resolves the preset into resolvedSettings; no runtime --wpds-border-radius-* emission.
• Storybook: Design System Theme toolbar control for corner radius; preset <select> in the Example Application demo, whose "General" card now includes InputControl, SelectControl, and a Save Button so the radius change is demonstrable across input and control sizes alongside cards; falsy toolbar globals coerced to undefined so invalid values like '' are not passed through.
• Docs: README + CHANGELOG updated; CornerRadiusPreset exported from @wordpress/theme.

Preset scale

Preset	xs	sm	md	lg	xl
none	0	0	0	0	0
subtle (default)	1	2	4	8	12
moderate	6	8	12	16	20
pronounced	18	20	22	24	26

subtle mirrors the existing static radii. Toward pronounced, the smaller primitives climb steeply (e.g. xs 1 → 18) while the larger surfaces grow more gently (lg 8 → 24, xl 12 → 26), so compact controls become strongly rounded while cards and shells stay tastefully — not excessively — round.

Test plan

• Open Design System → Theme → Theme Provider → Example Application in Storybook
• Use the Theme toolbar (Corner radius) and/or the in-story <select> to switch between None / Subtle / Moderate / Pronounced and confirm Button, Card, Notice, Tabs, and the form fields (inputs, select) update
• Pay attention to buttons and inputs vs cards/dialogs and shell surfaces — at pronounced, compact controls should round up strongly while cards and shells stay moderately rounded
• Confirm color and background controls still work alongside corner radius
• Verify default (subtle) matches pre-existing border-radius appearance
• Confirm a portalled component (e.g. Dialog or Tooltip) that renders its own ThemeProvider picks up that provider's preset

Screenshots

Screen.Recording.2026-06-11.at.15.44.09.mov

Use of AI

Made with Cursor

[jasmussen]

I like it! Can I feed it arbitrary values? Maybe I want everything pill-shaped (i.e. border-radius: 9999px;)

[github-actions]

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: jameskoster <jameskoster@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: aduth <aduth@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: jasmussen <joen@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]

Size Change: +170 B (0%)

Total Size: 8.59 MB

📦 View Changed

Filename	Size	Change
build/modules/boot/index.min.js	52.8 kB	+99 B (+0.19%)
build/scripts/theme/index.min.js	22.1 kB	+71 B (+0.32%)

_{compressed-size-action}

[github-actions]

Flaky tests detected in 9f6c1c0.
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/27355771890
📝 Reported issues:

• [Flaky Test] shouldn't conflict with server-side autosave #78706 in /test/e2e/specs/editor/various/autosave.spec.js

[jameskoster]

cornerRadius applies to the whole radius scale, so you can't target one specific component like Button and say "I want this to be pill shaped". That is a valid request though, and one we should support, but at this stage I'm unsure how best to approach it.

Would we want to allow per-component control, or should the chosen 'pill' design language apply to other things like inputs and chips? Would it be additive to the chosen radius preset, and how does that relationship work? A simpler approach could be an additional preset with large enough values at the low end to ensure things like buttons are pilled regardless. On balance I think this feature would need to be explored separately.

[mirka]

I think we can also add this option to the Theme tool in the toolbar.

[jasmussen]

Would we want to allow per-component control, or should the chosen 'pill' design language apply to other things like inputs and chips?

I've always thought of this as there being a single default that is set somewhere globally that all inherit, and then a local prop that can be explicitly set. Use case: I have a particular design where I want 3 pill shaped buttons and one that is perfectly sharp. For example: a smart home dashboard where the three lamps are ON, and the 4th button is OFF. Slightly contrived, yes, but IMO valid.

What do we do for other theme props, can they be set once globally, then overridden locally? What do other design systems do?

[jameskoster]

@jasmussen Agree it's valid but I think it's something to figure out separately because it focuses on individual components whereas this PR is about applying corner radius globally. I did add a couple of extra presets though, including 2xl which produces almost-pill-shaped buttons:

Happy to continue tweaking values, but for true pill shapes I think that might be a component-level concern.

[aduth]

I see the note in the pull request about these being for portaled content, but I'm not sure I really follow the logic there. Those aren't :root nodes and I don't think we'd want to assume that portaled content necessarily inherits from :root styling. Those portaled contents should have their own ThemeProvider to forward the theme context into the portaled content (example). Maybe this is a similar problem to what was being explored in #78662 before we closed it due to density being dropped?

[jameskoster]

Thanks for pointing that out. I’ll remove the :root:has rules and rely on [data-wpds-corner-radius="…"] + portal-local ThemeProviders.

[ciampo]

This is an interesting nuance that we need to explore and make an explicit decision on.

I see why @jameskoster initially added the :root:has() selector, and I see @aduth 's point. It really comes down to the meaning we want to give to the isRoot prop on ThemeProvider.

1. isRoot exists only to write the handful of properties that must physically live on <html> and need to be applied outside of the React root (eg, page background, color-scheme). Border-radius has no such property.
2. isRoot marks the whole document's theme, apply everything to the whole document.

For me, the matter is less about portalled content, and more about the potential need to consume DS tokens outside of the React app (for example, having the PHP rendered HTML in WP Admin consume the tokens and dynamically adapting to their value changing)?

But if we're never going to have "mixed" (ie React + PHP) pages, that's not really a factor. We could follow the mental model at point 1, and if we ever need to apply a specific corner radius setting on the HTML element, we could add the data-wpds-corner-radius attribute (reading from user preferences).

[jameskoster]

But if we're never going to have "mixed" (ie React + PHP) pages, that's not really a factor

Don't we already have those? IE Appearance > Fonts, Gutenberg > Experiments?

[ciampo]

True. In that case, we may want to adopt solution no. 2, ie. applying all of the DS tokens from a root ThemeProvider to the its document element

[jameskoster]

Since solution 2 is about making the whole token surface behave consistently on , not just radius, do ou think we should handle it in a separate PR?

[ciampo]

Solution 2 is already what's currently in place for color and cursor tokens, so it would just be a matter of restoring the additional :root:has([data-wpds-root-provider="true"][data-wpds-corner-radius="none"]) selector in the terrazzo config.

@aduth this goes against your initial comment, although the framing is different: we'd be adding it back for the reasons highlighted in this comment (and not for portalled content)

[aduth]

Starting to get into nitpick territory with the discussion about cornerRadius option shape, but generally this is looking good from my technical point-of-view 👍

[aduth]

Minor: I wonder if we should just enable the Theme options for this screen and expect people to pick the corner radius from the dropdown?

[jameskoster]

If we update the Theme options to support custom colors it'd be the way to go. But until then I think the Theme options would interfere with the color pickers in this story?

[ciampo]

I haven't looked at the code yet, but I'll share my thoughts re. global vs per-component settings"

Would we want to allow per-component control, or should the chosen 'pill' design language apply to other things like inputs and chips?

I've always thought of this as there being a single default that is set somewhere globally that all inherit, and then a local prop that can be explicitly set. \

I can think of two approaches:

1. set value on ThemeProvider as a global setting. If in need of exceptions, override that specific value via a nested ThemeProvider. IMO this works well if such exceptions are rare, ie. if we assume that generally all UI should share a similar "corner radius" vibe;
2. if, instead, mixing and matching different corner radii is something we expect to do consistently/systematically (and that's a design-driven decision), it should applied as an individual component prop where necessary (similarly to how we already expose size related props).

A simpler approach could be an additional preset with large enough values at the low end to ensure things like buttons are pilled regardless. On balance I think this feature would need to be explored separately.

This could work, especially for the scenario 1 above.

[ciampo]

Let's rebase on top of latest trunk and also update the PR description to be up to date with the latest code changes:

• The "Preset scale (tapered)" table is missing xl and 2xl;
• The data-wpds-corner-radius is now always added (the description says it's omitted for sm)
• The part about testing portalled content inheriting the root presets is stale after the recent changes. Portalled content is expected to render dedicated ThemeProvider

[ciampo]

Adding a data-* attribute feels like the right approach, given that we know the values of the DS tokens for all presets in advance.

If in the future we will allow arbitrary values (ie. not presets), we will have to compute the DS tokens at runtime, and output them alongside other dynamically computed DS tokens (such as color).

The current setup is future-compatible with this possibility, so I think we're good :)

[ciampo]

Follow-up idea: update useThemeProviderStyles so that the resolved settings can never be undefined, meaning that the fallback to sm would happen only in one place (less duplication, less opportunity for drift)

[ciampo]

Linking to previous conversations, I wonder if having both token names AND the cornerRadius settings use the same t-shirt sizes could confuse consumers.

What about using more semantic names for cornerRadius such as sharp/subtle/rounded/round/pill .. ?

[jameskoster]

Very good point, I feel that tension every time I look at the table in the PR description haha.

I made an attempt to update this in 79c4be8 but quickly realised the names felt anchored to smaller elements which made them feel off considering the whole UI. For instance Cards do not feel 'sharp' with 8px radius when sharp mode is active. "Sharp" implies the entire UI should be very low radius.

So I tried a slightly different approach in cd55880;

none · subtle · soft · moderate · generous · pronounced

WDYT?

[jasmussen]

I'd still very much like an escape hatch for arbitrary values for this one, kind of like font size for text. Not blocking this PR in any way shape or form, just wondering: can we have such a one? Also unique to radius insofar as any arbitrarily non-percentage-based value will create a pill-shape, which is often useful.

[ciampo]

Yes, we discussed and agreed that in the future we'll want to explore supporting more granular/arbitrary values (ie. any number ≥ 0).

Technically it should be feasible, but the challenge IMO is to understand how to map one number internally to the full set of radii. Ie. do they all scale linearly with that number? Is it more nuanced (ie. exponential)? Does it apply to all radii, or some radii won't be affected (eg none will always be 0)

Not sure if you prefer to merge this PR and explore separately, or you'd prefer exploring those options in this PR to have a stronger reassurance that the direction taken is good.

In any case, we'll need to have a clear direction in mind in time for the 7.1 release (RC release on 5th of August), since we'll mark the theme package as stable and ready for use.

[jasmussen]

No strong opinions or blockers so long as we don't paint ourselves into a corner one way or the other!

[ciampo]

quickly realised the names felt anchored to smaller elements which made them feel off considering the whole UI. [...] So I tried a slightly different approach

none · subtle · soft · moderate · generous · pronounced

WDYT?

Definitely an improvement over thisrt sizes, although I think there is still some ambiguity:

• the difference / order betweensubtle and soft may not be obvious;
• same re. generous and pronounced

Especially since we're also planning on allowing arbitrary numbers, I wonder if we could do with fewer presets, dropping from 6 to 4: 'none' | 'subtle' | 'moderate' | 'pronounced'.

We could also map those presents internally to a numeric value and apply the math to the scales, as the bridging work towards allowing any arbitraty value.

[jameskoster]

Assuming the desire for pill shapes applies only to buttons and controls I think we should just bake that into one of the presets. Then we wouldn't need the escape hatch?

dropping from 6 to 4

Sure. I'll work on this now.

[jameskoster]

@ciampo @jasmussen I reduced the number of presets and updated the 'Pronounced' one to produce pill shaped buttons / controls. PR description/video updated.

[ciampo]

LGTM 🚀

I'll follow-up on #78816 (comment) in a separate PR