Four of the five radius tokens are lengths between 3px and 12px. The fifth is a percentage, which makes it a different kind of thing wearing the same scale.
- borderRadius.sm 3px
- borderRadius.md 4px
- borderRadius.lg 8px
- borderRadius.xl 12px
- borderRadius.circle 50%
Small and medium radius are one pixel apart
Section titled “Small and medium radius are one pixel apart”borderRadius.sm is 3px and borderRadius.md is 4px. At that difference the choice is invisible in isolation, and the split in the library is by scale rather than by kind: sm goes on the small marks and cells — Sticker, Tab Bar, the ends of a selected range in the Date Picker — and md goes on the controls a reader acts on, including Input, Icon Button, List Box, Button Group, Toast and Progress Indicator.
The rule that follows is not “pick by feel”. Match the component you are sitting next to, because a 1px difference reads as a mistake when two controls are adjacent and as nothing at all when they are apart.
Extra large radius has one precedent in the library
Section titled “Extra large radius has one precedent in the library”borderRadius.xl is referenced once in @persona/design-system, by Status Indicator. lg is also used once, by Floating Panel, and circle once, by Swatch Picker; md is used 15 times and sm 9. None of that makes xl wrong to reach for, but 12px has a precedent rather than a pattern behind it, so a second use is a decision about where the shape of PDS is going and worth making deliberately.
Circle is 50%, so it needs a square box
Section titled “Circle is 50%, so it needs a square box”A percentage radius resolves against the element’s own dimensions. borderRadius.circle on a square gives a circle; on anything wider than it is tall it gives an ellipse, which is not the shape Swatch Picker’s swatches are showing you.
The library writes 100%, 1000px and 100px in seven other places to mean “fully round”, and none of those values is on the scale. That is not all carelessness: a pill on a box wider than it is tall needs a large fixed length, and circle cannot express one. But three spellings of the same intent is three, and only one of them is greppable.
Thirty of the library’s seventy-seven corners name a token
Section titled “Thirty of the library’s seventy-seven corners name a token”@persona/design-system declares border-radius 77 times. 30 of those reference a radius token and 4 set 0, which is a corner removed rather than a corner chosen. That leaves 43 that set a radius without naming one: 16 read the React theme, whose radii are the literal strings "4px" and "8px" written into theme.ts rather than read from the token package; 25 are hard-coded lengths; and two are spacing[1].
Five of the hard-coded lengths — 1px, 5px, 100px, 100%, 1000px — are not on the scale in any form. The ones that are on it fail differently: Checkbox’s corners are 3px and Banner’s are 4px, which match sm and md exactly today and will stop matching the moment either token moves, with nothing to report it.
So the token list above is the intended shape of the system rather than a description of it, and a component’s corner is only worth quoting from the component.
Was this page helpful?