Radii

[jameskoster]

Recent work has expanded the values used for border radius in the UI. Specifically; the new menu component, document title, and command palette all make use of a larger 4px radius. The preview / content frame, and modal radius is larger still: 8px.

A defined scale for radius can add polish to the UI. For example compare how menu items nest neatly inside their container in the new menu component, compared with the current one:

DropdownMenu V2	DropdownMenu

Ad hoc proliferation of values for radius is going to create a maintenance headache down the road, so it would be good to think systematically about a refreshed radius scale, and semantic application thereof.

Radius scale

Members of the design team have been looking into this and formulated the following scale/guidelines:

• $radius-x-small: The smallest radius. Applied to contained elements within primitives like inputs or buttons. E.g. the selected item in a ToggleGroupControl, or the unit selector in UnitControl.
• $radius-small: Applied to primitive components like Badges, Buttons, Inputs, Checkboxes.
• $radius-medium: Applied to containers with smaller padding, e.g. Menus, Notices, Snackbars, Block toolbar. Also used for focus rings on primitive components.
• $radius-large: Applied to containers with larger padding, e.g. Modals, Pages, and the Preview Frame.
• $radius-full: For creating lozenges.
• $radius-round: For creating circles or ovals. (This variable already exists).

Note: The values assigned to each item in the scale can be decided separately, but we can discuss those here too.

Implementation

Once we find consensus around the scale and values, a possible implementation plan might look like:

• [x] https://github.com/WordPress/gutenberg/pull/64007
• [ ] Make changes across the repository, switching to the new variables (this can be further split into smaller PRs — the components package should probably have its separate one, for example)
• [ ] Mark old variables as deprecated, add linter rules, check that there are usages left of the deprecated variables

[ciampo]

Some feedback points on the naming:

• it may be confusing to know in advance which radius is bigger between "atom" vs "primitive"
• I find that mixing abstract names like "atom" and "primitive" with "container" feels a bit incoherent.

How do other design systems call their radius scale?

Also, should this be a 1:1 of what will be included for radii in the theme package?

[hanneslsm]

How do other design systems call their radius scale?

Usually xs, sm, md, lg in various spellings https://tailwindcss.com/docs/border-radius https://developer.apple.com/documentation/tvml/border-radius https://m3.material.io/styles/shape/overview

[jameskoster]

Good points. I was thinking there could be two parts;

• The scale itself which should likely use a naming convention like xs, sm, md, lg, as suggested
• Semantic tokens that help clarify which radius to use in a given situation. Names TBD :)

Perhaps the latter is unnecessary?

[ciampo]

xs, sm, md, lg, as suggested

That is definitely clearer to understand. The alternative is to go even more "literal" and use a number-based scale (example)

Semantic tokens that help clarify which radius to use in a given situation. Names TBD :) Perhaps the latter is unnecessary?

The risk of using semantic names is that, depending on what names are chosen, they can get "out of sync" if the design direction updates. Are there other design systems adopting semantic token names on top of a "neutral" scale?

Maybe a good way to move forward is to start without semantic tokens, get a feel for it, and re-discuss if we feel like semantic tokens would be a nice addition?

[jameskoster]

Semantic tokens is something we've been exploring in Figma for colors. But it might not need to be codified, especially for less-used scales like Radius.

Starting without tokens seems very reasonable.

[mattrwalker]

I agree with the Polaris example of naming being clearer but also potentially presenting risk if specific values are ever needed updating. The t-shirt size approach is a great iteration of the naming that feels clearer while also allowing us some flexibility to adjust values in the future too, I'd be in favor of the T-shirt size naming whenever we're ready to create tokens.

We could also ensure that descriptions and usage guidance for each radii are defined and communicated clearly whenever it's referenced to ensure folks know how and when to use the right radius.

Great breakdown per usual @jameskoster